Data Structures | |
| struct | apr_ldap_url_desc_t |
| struct | apr_ldap_apiinfo_t |
| struct | apr_ldap_apifeature_info_t |
| struct | apr_ldap_opt_tls_cert_t |
| union | apr_ldap_opt_t |
| struct | apr_ldap_control_oid_t |
| struct | apr_ldap_control_sortrequest_t |
| struct | apr_ldap_control_sortkey_t |
| struct | apr_ldap_control_sortresponse_t |
| struct | apr_ldap_control_pagerequest_t |
| struct | apr_ldap_control_pageresponse_t |
| struct | apr_ldap_control_vlvrequest_t |
| struct | apr_ldap_control_vlvresponse_t |
| struct | apr_ldap_control_t |
| struct | apr_ldap_bind_interact_t |
| struct | apr_ldap_search_entry_t |
| struct | apr_ldap_pair_t |
| struct | apr_ldap_modify_t |
Detailed Description
The APR LDAP routines provide a common, cross platform, ability to connect to and search an LDAP server.
The goals of the API are:
- Work within the functionality of APR pools. Requests from different pools can make LDAP requests of a common connection, and when the connection pool or the request pool goes away, the connection and/or LDAP requests are cleaned up gracefully.
- Offer an asynchronous API that can be used for non blocking access to an LDAP server. The responses APR_WANT_READ and APR_WANT_WRITE make it clear whether the API wants to read or write to the LDAP server in the next API call.
- Be as simple as possible. Data is returned fully processed in callbacks, removing the need for API calls to access data, and intermediate data structures.
In typical use, the following calls are used:
- apr_ldap_initialise() - create a handle to keep track of a connection.
- apr_ldap_option_set() - set the URL, or the socket descriptor for the connextion to the server.
- apr_ldap_connect() - if an URL was specified, connect to the server and confirm success.
- apr_ldap_bind() - initiate a bind, and specify a callback when done.
Enter the event loop, where we do the following until the connection is closed.
- apr_ldap_process() - when writable, perform tasks that require writing to the LDAP server.
- apr_ldap_result() - when readable, perform tasks that require reading from the LDAP server.
Respond appropriately to callbacks, lining up calls to apr_ldap_compare() and apr_ldap_search() as needed.
Macro Definition Documentation
◆ APR_LDAP_CA_TYPE_BASE64
| #define APR_LDAP_CA_TYPE_BASE64 2 |
PEM encoded CA certificate
◆ APR_LDAP_CA_TYPE_CACERTDIR_BASE64
| #define APR_LDAP_CA_TYPE_CACERTDIR_BASE64 15 |
Openldap directory full of base64-encoded cert authorities with hashes in corresponding .0 directory
◆ APR_LDAP_CA_TYPE_DER
| #define APR_LDAP_CA_TYPE_DER 1 |
Binary DER encoded CA certificate
◆ APR_LDAP_CA_TYPE_UNKNOWN
| #define APR_LDAP_CA_TYPE_UNKNOWN 0 |
CA certificate type unknown
◆ APR_LDAP_CA_TYPE_URI
| #define APR_LDAP_CA_TYPE_URI 18 |
CA Certificate at the given URI
◆ APR_LDAP_CERT_TYPE_BASE64
| #define APR_LDAP_CERT_TYPE_BASE64 7 |
PEM encoded client certificate
◆ APR_LDAP_CERT_TYPE_DER
| #define APR_LDAP_CERT_TYPE_DER 6 |
Binary DER encoded client certificate
◆ APR_LDAP_CERT_TYPE_PFX
| #define APR_LDAP_CERT_TYPE_PFX 13 |
PKCS#12 encoded client certificate
◆ APR_LDAP_CERT_TYPE_UNKNOWN
| #define APR_LDAP_CERT_TYPE_UNKNOWN 5 |
Client certificate type unknown
◆ APR_LDAP_CERT_TYPE_URI
| #define APR_LDAP_CERT_TYPE_URI 16 |
Certificate at the given URI
◆ APR_LDAP_CONTROL_PAGE_OID
| #define APR_LDAP_CONTROL_PAGE_OID "1.2.840.113556.1.4.319" /* RFC 2696 */ |
RFC 2696 Paged control OID.
◆ APR_LDAP_CONTROL_SORT_REQUEST_OID
| #define APR_LDAP_CONTROL_SORT_REQUEST_OID "1.2.840.113556.1.4.473" /* RFC 2891 */ |
RFC 2891 Sort request control OID.
◆ APR_LDAP_CONTROL_SORT_RESPONSE_OID
| #define APR_LDAP_CONTROL_SORT_RESPONSE_OID "1.2.840.113556.1.4.474" /* RFC 2891 */ |
RFC 2891 Sort response control OID.
◆ APR_LDAP_CONTROL_VLV_REQUEST_OID
| #define APR_LDAP_CONTROL_VLV_REQUEST_OID "2.16.840.1.113730.3.4.9" |
VLV request control OID.
◆ APR_LDAP_CONTROL_VLV_RESPONSE_OID
| #define APR_LDAP_CONTROL_VLV_RESPONSE_OID "2.16.840.1.113730.3.4.10" |
VLV response control OID.
◆ APR_LDAP_KEY_TYPE_BASE64
| #define APR_LDAP_KEY_TYPE_BASE64 12 |
PEM encoded private key
◆ APR_LDAP_KEY_TYPE_DER
| #define APR_LDAP_KEY_TYPE_DER 11 |
Binary DER encoded private key
◆ APR_LDAP_KEY_TYPE_PFX
| #define APR_LDAP_KEY_TYPE_PFX 14 |
PKCS#12 encoded private key
◆ APR_LDAP_KEY_TYPE_UNKNOWN
| #define APR_LDAP_KEY_TYPE_UNKNOWN 10 |
Private key type unknown
◆ APR_LDAP_KEY_TYPE_URI
| #define APR_LDAP_KEY_TYPE_URI 17 |
Private key at the given URI
◆ APR_LDAP_OPT_API_FEATURE_INFO
| #define APR_LDAP_OPT_API_FEATURE_INFO 0x6ff7 |
Get the LDAP API feature info.
◆ APR_LDAP_OPT_API_INFO
| #define APR_LDAP_OPT_API_INFO 0x6ff8 |
Get the LDAP API info.
◆ APR_LDAP_OPT_DEBUG_LEVEL
| #define APR_LDAP_OPT_DEBUG_LEVEL 0x5001 |
Get or set the debug level.
◆ APR_LDAP_OPT_DEREF
| #define APR_LDAP_OPT_DEREF 0x6ff6 |
Get the dereference setting.
◆ APR_LDAP_OPT_DESC
| #define APR_LDAP_OPT_DESC 0x6ff4 |
Get or set the underlying socket.
Use this to get the underlying socket so as to perform select/poll before attempting to read or write.
Note that LDAP libraries like OpenLDAP will successfully return an invalid socket if a previous attempt to connect failed. In this case, you will obtain an error the next time you use the socket.
This option can also be used to set the underlying socket, as an alternative to specifying a URI. This is typically done to perform non blocking DNS lookups, or non blocking TLS negotiation, neither of which is supported natively by LDAP APIs.
- Warning
- Either APR_LDAP_OPT_DESC or APR_LDAP_OPT_URI must be set before any other options are set, for the LDAP handle to be initialised internally.
◆ APR_LDAP_OPT_HANDLE
| #define APR_LDAP_OPT_HANDLE 0x6ffa |
Get the underlying native LDAP handle.
- See also
- apr_ldap_option_get
◆ APR_LDAP_OPT_NETWORK_TIMEOUT
| #define APR_LDAP_OPT_NETWORK_TIMEOUT 0x5005 |
Get/set the network timeout.
◆ APR_LDAP_OPT_PROTOCOL_VERSION
| #define APR_LDAP_OPT_PROTOCOL_VERSION 0x6ff9 |
Get/Set the LDAP protocol version.
◆ APR_LDAP_OPT_REFERRALS
| #define APR_LDAP_OPT_REFERRALS 0x6ffc |
Set the LDAP library to indicate if referrals should be chased during LDAP searches.
◆ APR_LDAP_OPT_REFHOPLIMIT
| #define APR_LDAP_OPT_REFHOPLIMIT 0x6ffb |
Set the LDAP library to indicate a maximum number of referral hops to chase before giving up on the search.
◆ APR_LDAP_OPT_RESULT_CODE
| #define APR_LDAP_OPT_RESULT_CODE 0x6ff5 |
Get the most recent result code.
- See also
- apr_ldap_option_get
◆ APR_LDAP_OPT_TIMEOUT
| #define APR_LDAP_OPT_TIMEOUT 0x5002 |
Get/set the timeout.
◆ APR_LDAP_OPT_TLS
| #define APR_LDAP_OPT_TLS 0x6fff |
Set SSL mode to one of APR_LDAP_NONE, APR_LDAP_SSL, APR_LDAP_STARTTLS or APR_LDAP_STOPTLS.
◆ APR_LDAP_OPT_TLS_CERT
| #define APR_LDAP_OPT_TLS_CERT 0x6ffe |
Set zero or more CA certificates, client certificates or private keys globally, or per connection (where supported).
◆ APR_LDAP_OPT_URI
| #define APR_LDAP_OPT_URI 0x5006 |
Set the URI to connect to.
- Warning
- This option (or APR_LDAP_OPT_DESC) must be set before other options, as this initialises the underlying LDAP API.
- See also
- apr_ldap_option_set
◆ APR_LDAP_OPT_VERIFY_CERT
| #define APR_LDAP_OPT_VERIFY_CERT 0x6ffd |
Set the LDAP library to not verify the server certificate. This means all servers are considered trusted.
- See also
- apr_ldap_option_set
- apr_ldap_verify_e
◆ APR_LDAP_PORT
| #define APR_LDAP_PORT 389 |
Ports used by LDAP. ldap:/// default LDAP port
◆ APR_LDAP_URL_ERR_BADATTRS
| #define APR_LDAP_URL_ERR_BADATTRS 0x07 |
Bad (or missing) attributes
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_BADENCLOSURE
| #define APR_LDAP_URL_ERR_BADENCLOSURE 0x04 |
URL is missing trailing ">"
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_BADEXTS
| #define APR_LDAP_URL_ERR_BADEXTS 0x0a |
Bad or missing extensions
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_BADFILTER
| #define APR_LDAP_URL_ERR_BADFILTER 0x09 |
Bad or missing filter
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_BADHOST
| #define APR_LDAP_URL_ERR_BADHOST 0x06 |
Host port is bad
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_BADSCHEME
| #define APR_LDAP_URL_ERR_BADSCHEME 0x03 |
URL doesn't begin with "ldap[si]://"
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_BADSCOPE
| #define APR_LDAP_URL_ERR_BADSCOPE 0x08 |
Scope string is invalid (or missing)
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_BADURL
| #define APR_LDAP_URL_ERR_BADURL 0x05 |
URL is bad
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_MEM
| #define APR_LDAP_URL_ERR_MEM 0x01 |
Can't allocate memory space
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_ERR_PARAM
| #define APR_LDAP_URL_ERR_PARAM 0x02 |
Parameter is bad
- See also
- apr_ldap_url_parse()
◆ APR_LDAP_URL_SUCCESS
| #define APR_LDAP_URL_SUCCESS 0x00 |
URL was successfully parsed.
- See also
- apr_ldap_url_parse()
◆ APR_LDAPS_PORT
| #define APR_LDAPS_PORT 636 |
ldaps:/// default LDAP over TLS port
◆ APU_DECLARE_LDAP
| #define APU_DECLARE_LDAP | ( | type | ) | APR_DECLARE(type) |
- See also
- APR_DECLARE
Typedef Documentation
◆ apr_ldap_add_cb
| typedef apr_status_t(* apr_ldap_add_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err) |
Callback to receive the results of an add operation.
When an addition is successful, this function is called with a status of APR_SUCCESS.
If the addition fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
If this callback was called during a pool cleanup, the return value is ignored.
- See also
- apr_ldap_add
- apr_ldap_result
◆ apr_ldap_apifeature_info_t
| typedef struct apr_ldap_apifeature_info_t apr_ldap_apifeature_info_t |
Structure returned by passing APR_LDAP_OPT_API_FEATURE_INFO to apr_ldap_option_get().
Use to return details of extensions supported by the underlying API.
◆ apr_ldap_apiinfo_t
| typedef struct apr_ldap_apiinfo_t apr_ldap_apiinfo_t |
Structure returned by passing APR_LDAP_OPT_API_INFO to apr_ldap_option_get().
Use to return information about the underlying LDAP API.
◆ apr_ldap_bind_cb
| typedef apr_status_t(* apr_ldap_bind_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err) |
Callback to receive the results of a bind operation.
When a bind is successful, this function is called with a status of APR_SUCCESS.
Bind success is returned from within apr_ldap_process(), and therefore it can be safely assumed that the underlying socket is writable ready for exactly one further LDAP operation like apr_ldap_search() or apr_ldap_compare().
If the bind fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_process().
If this callback was called during a pool cleanup, the return value is ignored.
◆ apr_ldap_bind_interact_cb
| typedef apr_status_t() apr_ldap_bind_interact_cb(apr_ldap_t *ld, unsigned int flags, apr_ldap_bind_interact_t *interact, void *ctx) |
Bind SASL interact callback.
Depending on the type of SASL mechanism chosen, this callback is called to request details needed for each bind.
◆ apr_ldap_bind_interact_t
| typedef struct apr_ldap_bind_interact_t apr_ldap_bind_interact_t |
During apr_ldap_bind(), a callback is passed this structure requesting authentication and authorisation details. The callback is expected to fill the buffer with the information requested.
This is used to obtain the information needed for SASL binds.
◆ apr_ldap_compare_cb
| typedef apr_status_t(* apr_ldap_compare_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err) |
Callback to receive the results of a compare operation.
When a compare is successful, this function is called with a status of APR_COMPARE_TRUE or APR_COMPARE_FALSE.
If the compare fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
If this callback was called during a pool cleanup, the return value is ignored.
- See also
- apr_ldap_compare
- apr_ldap_result
◆ apr_ldap_control_oid_t
| typedef struct apr_ldap_control_oid_t apr_ldap_control_oid_t |
Control specified by OID and value.
All controls unrecognised by this API can be parsed and returned as this type.
◆ apr_ldap_control_pagerequest_t
| typedef struct apr_ldap_control_pagerequest_t apr_ldap_control_pagerequest_t |
Page request control RFC 2696.
◆ apr_ldap_control_pageresponse_t
| typedef struct apr_ldap_control_pageresponse_t apr_ldap_control_pageresponse_t |
Page Response Control RFC 2696.
◆ apr_ldap_control_sortkey_t
| typedef struct apr_ldap_control_sortkey_t apr_ldap_control_sortkey_t |
Sort key list.
◆ apr_ldap_control_sortrequest_t
| typedef struct apr_ldap_control_sortrequest_t apr_ldap_control_sortrequest_t |
Sort request control RFC 2891.
◆ apr_ldap_control_sortresponse_t
| typedef struct apr_ldap_control_sortresponse_t apr_ldap_control_sortresponse_t |
Sort Response Control RFC 2891.
◆ apr_ldap_control_t
| typedef struct apr_ldap_control_t apr_ldap_control_t |
LDAP parsed control structures.
Use this structure to pass or receive the parameters required when creating or parsing a control.
Unrecognised controls can be created or parsed using the APR_LDAP_CONTROL_OID type and a raw binary value.
◆ apr_ldap_control_vlvrequest_t
| typedef struct apr_ldap_control_vlvrequest_t apr_ldap_control_vlvrequest_t |
VLV request control draft-ietf-ldapext-ldapv3-vlv-09.
◆ apr_ldap_control_vlvresponse_t
| typedef struct apr_ldap_control_vlvresponse_t apr_ldap_control_vlvresponse_t |
VLV Response Control draft-ietf-ldapext-ldapv3-vlv-09.
◆ apr_ldap_delete_cb
| typedef apr_status_t(* apr_ldap_delete_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err) |
Callback to receive the results of a delete operation.
When a deletion is successful, this function is called with a status of APR_SUCCESS.
If the delete fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
If this callback was called during a pool cleanup, the return value is ignored.
- See also
- apr_ldap_delete
- apr_ldap_result
◆ apr_ldap_driver_t
| typedef struct apr_ldap_driver_t apr_ldap_driver_t |
Opaque structure representing the LDAP driver.
- See also
- apr_ldap_get_driver
◆ apr_ldap_extended_cb
| typedef apr_status_t(* apr_ldap_extended_cb) (apr_ldap_t *ldap, apr_status_t status, const char *roid, apr_buffer_t *rdata, void *ctx, apu_err_t *err) |
Callback to receive the results of an extended operation.
When an extended operation is successful, this function is called with a status of APR_SUCCESS.
If the extended operation fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
If this callback was called during a pool cleanup, the return value is ignored.
- See also
- apr_ldap_extended
- apr_ldap_result
◆ apr_ldap_modify_cb
| typedef apr_status_t(* apr_ldap_modify_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err) |
Callback to receive the results of a modify operation.
When a modification is successful, this function is called with a status of APR_SUCCESS.
If the modify fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
If this callback was called during a pool cleanup, the return value is ignored.
- See also
- apr_ldap_modify
- apr_ldap_result
◆ apr_ldap_modify_t
| typedef struct apr_ldap_modify_t apr_ldap_modify_t |
Modification to be performed by apr_ldap_modify().
Modifications can take the form of additions, deletions, or the in place modification or increment of an attribute.
- See also
- apr_ldap_pair_t
- apr_ldap_modify
◆ apr_ldap_opt_t
| typedef union apr_ldap_opt_t apr_ldap_opt_t |
Union of all possible options to be passed to apr_ldap_option_get() and apr_ldap_option_set().
◆ apr_ldap_opt_tls_cert_t
| typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t |
Certificate structure.
This structure is used to store certificate details. An array of these structures is passed to apr_ldap_option_set() with the option APR_LDAP_OPT_TLS_CERT to set CA and client certificates.
◆ apr_ldap_pair_t
| typedef struct apr_ldap_pair_t apr_ldap_pair_t |
Attribute-value pair.
An array of pairs is passed to apr_ldap_add(), and a pair forms part of the apr_ldap_modify_t that is passed to apr_ldap_modify().
- See also
- apr_ldap_add
- apr_ldap_modify
◆ apr_ldap_prepare_cb
| typedef apr_status_t(* apr_ldap_prepare_cb) (apr_ldap_t *ldap, apr_status_t status, void *ctx, apu_err_t *err) |
Callback to prepare an LDAP request.
This callback is scheduled to be fired when the LDAP socket is next writable, from within apr_ldap_process().
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_process().
- See also
- apr_ldap_prepare
- apr_ldap_process
◆ apr_ldap_rename_cb
| typedef apr_status_t(* apr_ldap_rename_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err) |
Callback to receive the results of a rename operation.
When a rename is successful, this function is called with a status of APR_SUCCESS.
If the rename fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
If this callback was called during a pool cleanup, the return value is ignored.
- See also
- apr_ldap_rename
- apr_ldap_result
◆ apr_ldap_search_entry_cb
| typedef apr_status_t(* apr_ldap_search_entry_cb) (apr_ldap_t *ldap, const char *dn, apr_size_t eidx, apr_ldap_search_entry_t *entry, void *ctx, apu_err_t *err) |
Callback to receive the entries of a search operation.
This callback is fired once for every attribute and value combination, and then once for each entry to indicate the entry is complete.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
- See also
- apr_ldap_search
- apr_ldap_result
◆ apr_ldap_search_entry_t
| typedef struct apr_ldap_search_entry_t apr_ldap_search_entry_t |
Search entry attribute value callback structure.
The callback is passed a pointer to the following structure containing the current state of the attribute values being returned.
- See also
- apr_ldap_search
◆ apr_ldap_search_result_cb
| typedef apr_status_t(* apr_ldap_search_result_cb) (apr_ldap_t *ldap, apr_status_t status, apr_size_t count, const char *matcheddn, apr_hash_t *serverctrls, void *ctx, apu_err_t *err) |
Callback to receive the results of a search operation.
This callback is fired once for every search.
When a search is complete, this function is called with a status of APR_SUCCESS or APR_NO_RESULTS_RETURNED.
If the search fails, status will carry the error code, and err will return the human readable details.
If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.
When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().
If this callback was called during a pool cleanup, the return value is ignored.
- See also
- apr_ldap_search
- apr_ldap_result
◆ apr_ldap_t
| typedef struct apr_ldap_t apr_ldap_t |
Opaque structure tracking the state of an LDAP connection.
- See also
- apr_ldap_initialise
◆ apr_ldap_url_desc_t
| typedef struct apr_ldap_url_desc_t apr_ldap_url_desc_t |
Individual fields accessible within an LDAP URL.
- See also
- apr_ldap_url_parse
Enumeration Type Documentation
◆ apr_ldap_bind_interact_e
LDAP interaction identifiers during LDAP binding
◆ apr_ldap_control_e
| enum apr_ldap_control_e |
LDAP control types.
This enumeration represents the controls processed by the library.
Most controls are simple, consisting of an OID and a binary or text value. These controls need no special processing.
Some controls have values consisting of BER structures. For convenience, three such controls are understood by the library, paged control, sort control, and the vlv control.
Controls not specifically recognised can be created using APR_LDAP_CONTROL_OID and the binary control value, and will be parsed to APR_LDAP_CONTROL_OID and the binary control value.
◆ apr_ldap_control_sortkey_e
◆ apr_ldap_debug_e
| enum apr_ldap_debug_e |
LDAP debug settings
◆ apr_ldap_deref_e
| enum apr_ldap_deref_e |
LDAP deref settings
◆ apr_ldap_operation_e
| enum apr_ldap_operation_e |
LDAP modification operations
- See also
- apr_ldap_modify
◆ apr_ldap_protocol_version_e
◆ apr_ldap_rename_e
| enum apr_ldap_rename_e |
LDAP rename flags
- See also
- apr_ldap_rename
| Enumerator | |
|---|---|
| APR_LDAP_RENAME_NONE | No flags |
| APR_LDAP_RENAME_DELETEOLDRDN | Delete the old relative distinguished name from the entry |
◆ apr_ldap_search_scope_e
APR search scopes
- See also
- apr_ldap_search
| Enumerator | |
|---|---|
| APR_LDAP_SCOPE_BASE | base object search |
| APR_LDAP_SCOPE_ONELEVEL | one-level search |
| APR_LDAP_SCOPE_SUBTREE | subtree search |
| APR_LDAP_SCOPE_SUBORDINATE | subordinate search |
◆ apr_ldap_switch_e
| enum apr_ldap_switch_e |
◆ apr_ldap_tls_e
| enum apr_ldap_tls_e |
APR_LDAP_OPT_TLS
This sets the SSL level on the LDAP handle.
- See also
- APR_LDAP_OPT_TLS
- apr_ldap_option_set
| Enumerator | |
|---|---|
| APR_LDAP_TLS_NONE | No encryption |
| APR_LDAP_TLS_SSL | SSL encryption (ldaps://) |
| APR_LDAP_TLS_STARTTLS | TLS encryption (STARTTLS) |
| APR_LDAP_TLS_STOPTLS | end TLS encryption (STOPTLS) |
◆ apr_ldap_verify_e
| enum apr_ldap_verify_e |
Function Documentation
◆ apr_ldap_add()
| apr_status_t apr_ldap_add | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | dn, | ||
| apr_array_header_t * | adds, | ||
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apr_interval_time_t | timeout, | ||
| apr_ldap_add_cb | add_cb, | ||
| void * | ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP add function
This function allows addition of an entry containing attributes and values described by the given distinguished name stored in the directory.
Additions are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_add will return APR_WANT_READ or APR_WANT_WRITE to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the addition will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_add_cb provided.
- Parameters
-
pool The pool that keeps track of the lifetime of the add conversation. If this pool is cleaned up, the add conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle dn The distinguished named of the object to add. adds Array of apr_ldap_pair_t attributes and values. serverctrls NULL terminated array of server controls. clientctrls NULL terminated array of client controls. timeout The timeout to use for writes. add_cb The addition result callback function. When the add process has completed the success or failure of the addition is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. ctx Context passed to the add callback. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_SUCCESS means that the processing is complete, and the addition has been successful. Other error codes indicate that the addition was not successful.
◆ apr_ldap_bind()
| apr_status_t apr_ldap_bind | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | mech, | ||
| apr_ldap_bind_interact_cb * | interact_cb, | ||
| void * | interact_ctx, | ||
| apr_interval_time_t | timeout, | ||
| apr_ldap_bind_cb | bind_cb, | ||
| void * | bind_ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP bind function
This function initiates a bind on a previously initialised LDAP connection to the directory.
Pass the required SASL mechanism in mech, or set to NULL for a simple bind.
Unlike the native LDAP APIs, this function muct be called just once. The job of binding is done inside apr_ldap_process() and apr_ldap_result().
Binds are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_bind will return APR_WANT_READ to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the bind will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_bind_cb provided.
- Parameters
-
pool The pool that keeps track of the lifetime of the bind conversation. If this pool is cleaned up, the bind conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle mech The SASL mechanism. Pass NULL for simple bind. interact_cb The SASL interactive callback function. This function is is called to request credentials for the bind, depending on the mechanism. interact_ctx Context passed to the interactive callback. timeout The timeout to use for writes. bind_cb The bind result callback function. When the bind process has completed the success or failure of the bind is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. bind_ctx Context passed to the bind callback. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_WANT_WRITE means that processing has occurred, and the conversation needs to be continued with a call to apr_ldap_process(). APR_SUCCESS means that the processing is complete, and the bind has been successful. Other error codes indicate that the bind was not successful.
◆ apr_ldap_compare()
| apr_status_t apr_ldap_compare | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | dn, | ||
| const char * | attr, | ||
| const apr_buffer_t * | val, | ||
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apr_interval_time_t | timeout, | ||
| apr_ldap_compare_cb | compare_cb, | ||
| void * | ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP compare function
This function compares a string or binary value of an attribute within an entry described by the given distinguished name against a previously initialised LDAP connection to the directory.
Compares are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_compare will return APR_WANT_READ to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the compare will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_compare_cb provided.
- Parameters
-
pool The pool that keeps track of the lifetime of the compare conversation. If this pool is cleaned up, the compare conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle dn The distinguished named of the object to compare. attr The attribute of the object to compare. val The value to be compared to the attribute. The value can be zero terminated text, or binary. serverctrls NULL terminated array of server controls. clientctrls NULL terminated array of client controls. timeout The timeout to use for writes. compare_cb The compare result callback function. When the compare process has completed the success or failure of the compare is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. ctx Context passed to the compare callback. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_SUCCESS means that the processing is complete, and the bind has been successful. Other error codes indicate that the bind was not successful.
◆ apr_ldap_connect()
| apr_status_t apr_ldap_connect | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| apr_interval_time_t | timeout, | ||
| apu_err_t * | result_err | ||
| ) |
APR LDAP connect function.
This function makes an attempt to connect to the server initialised by apr_ldap_initialise().
While other functions will connect if not connected, use this function to explicitly handle errors in the connect case.
This function will synchronously perform DNS lookups and TLS negotiation and will block if needed.
If you need asynchronous handling, perform the DNS and TLS handling yourself, and then pass the socket with APR_LDAP_OPT_DESC.
- Returns
- APR_SUCCESS means that the connection connected successfully. Other error codes indicate that the connect was not successful.
◆ apr_ldap_delete()
| apr_status_t apr_ldap_delete | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | dn, | ||
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apr_interval_time_t | timeout, | ||
| apr_ldap_delete_cb | delete_cb, | ||
| void * | ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP delete function
This function allows deletion of an entry described by the given distinguished name stored in the directory.
Deletions are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_delete will return APR_WANT_READ or APR_WANT_WRITE to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the deletion will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_modify_cb provided.
- Parameters
-
pool The pool that keeps track of the lifetime of the delete conversation. If this pool is cleaned up, the delete conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle dn The distinguished named of the object to delete. serverctrls NULL terminated array of server controls. clientctrls NULL terminated array of client controls. timeout The timeout to use for writes. delete_cb The delete result callback function. When the delete process has completed the success or failure of the deletion is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. ctx Context passed to the delete callback. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_SUCCESS means that the processing is complete, and the delete has been successful. Other error codes indicate that the delete was not successful.
◆ apr_ldap_extended()
| apr_status_t apr_ldap_extended | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | oid, | ||
| apr_buffer_t * | data, | ||
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apr_interval_time_t | timeout, | ||
| apr_ldap_extended_cb | ext_cb, | ||
| void * | ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP extended operation function
This function allows extended operations to be performed on the directory.
Extended operations are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_extended_operation will return APR_WANT_READ or APR_WANT_WRITE to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the extended operation will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_extended_operation_cb provided.
- Parameters
-
pool The pool that keeps track of the lifetime of the extended operation conversation. If this pool is cleaned up, the extended operation conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle oid The OID of the extended operation. data The data used by the extended operation. serverctrls NULL terminated array of server controls. clientctrls NULL terminated array of client controls. timeout The timeout to use for writes. ext_cb The extended operation result callback function. When the extended operation process has completed the success or failure of the extended operation is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. ctx Context passed to the delete callback. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_SUCCESS means that the processing is complete, and the extended operation has been successful. Other error codes indicate that the extended operation was not successful.
◆ apr_ldap_get_driver()
| apr_status_t apr_ldap_get_driver | ( | apr_pool_t * | pool, |
| const apr_ldap_driver_t ** | driver, | ||
| apu_err_t * | err | ||
| ) |
apr_ldap_get_driver: get the driver struct for a name
The LDAP driver is unique in that LDAP libraries are almost exclusively derived from RFC1823 "The LDAP Application Program Interface".
As a result, unlike other drivers for other subsystems in APR, two different drivers cannot be loaded at once, as the underlying libraries share common symbols with one another.
For this reason we have exactly one driver available at a time.
This function loads the library, and registers a cleanup with the pool provided to unload the library.
This function can be called multiple times by independent code, cleanups are reference counted so the last pool cleanup unloads the library.
Calling this function explicitly is optional, and would be done to have complete control over the lifetime of the driver.
If this function is not called explicitly, this function will be called if needed before the apr_ldap_info(), apr_ldap_initialise(), apr_ldap_option_get(), and apr_ldap_option_set() functions, registering cleanups in the pools provided to those functions if needed.
- Parameters
-
pool (process) pool to register cleanup that will unload the library. Cleanup is reference counted so the driver is unloaded on last access. driver Pointer to driver struct. Can be NULL. err Human readable error messages
- Returns
- APR_SUCCESS for success
- APR_ENOTIMPL for no driver (when DSO not enabled)
- APR_EDSOOPEN if DSO driver file can't be opened
- APR_ESYMNOTFOUND if the driver file doesn't contain a driver
◆ apr_ldap_info()
| apr_status_t apr_ldap_info | ( | apr_pool_t * | pool, |
| apu_err_t ** | result_err | ||
| ) |
APR LDAP info function
This function returns a string describing the LDAP toolkit currently in use. The string is placed inside result_err->reason.
- Parameters
-
pool The pool to use result_err The returned result
◆ apr_ldap_initialise()
| apr_status_t apr_ldap_initialise | ( | apr_pool_t * | pool, |
| apr_ldap_t ** | ldap, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP initialise function
This function is responsible for initialising an LDAP connection in a toolkit independant way. It does the job of ldap_initialize() from the C api.
The setting of the LDAP server to connect is made after this function returns, using the apr_ldap_option_set() call with APR_LDAP_OPT_DESC or APR_LDAP_OPT_URI.
A cleanup for the connection is registered in the given pool.
- Parameters
-
pool The pool to use ldap The ldap context returned err On error, error details are written to the structure.
◆ apr_ldap_is_ldap_url()
| int apr_ldap_is_ldap_url | ( | const char * | url | ) |
Is this URL an ldap url? ldap://
- Parameters
-
url The url to test
◆ apr_ldap_is_ldapi_url()
| int apr_ldap_is_ldapi_url | ( | const char * | url | ) |
Is this URL an ldap socket url? ldapi://
- Parameters
-
url The url to test
◆ apr_ldap_is_ldaps_url()
| int apr_ldap_is_ldaps_url | ( | const char * | url | ) |
Is this URL an SSL ldap url? ldaps://
- Parameters
-
url The url to test
◆ apr_ldap_modify()
| apr_status_t apr_ldap_modify | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | dn, | ||
| apr_array_header_t * | mods, | ||
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apr_interval_time_t | timeout, | ||
| apr_ldap_modify_cb | modify_cb, | ||
| void * | ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP modify function
This function allows modification of attributes and values within an entry described by the given distinguished name stored in the directory.
Modifications are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_modify will return APR_WANT_READ or APR_WANT_WRITE to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the modification will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_modify_cb provided.
- Parameters
-
pool The pool that keeps track of the lifetime of the modify conversation. If this pool is cleaned up, the modify conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle dn The distinguished named of the object to modify. mods Array of apr_ldap_modify_t operations. serverctrls NULL terminated array of server controls. clientctrls NULL terminated array of client controls. timeout The timeout to use for writes. modify_cb The modify result callback function. When the modify process has completed the success or failure of the modification is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. ctx Context passed to the modify callback. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_SUCCESS means that the processing is complete, and the modify has been successful. Other error codes indicate that the modify was not successful.
◆ apr_ldap_option_get()
| apr_status_t apr_ldap_option_get | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| int | option, | ||
| apr_ldap_opt_t * | outvalue, | ||
| apu_err_t * | result_err | ||
| ) |
APR LDAP get option function
This function gets option values from a given LDAP session if one was specified. It maps to the native ldap_get_option() function.
- Parameters
-
pool The pool to use where needed ldap The LDAP handle option The LDAP_OPT_* option to return outvalue The value returned (if any) result_err On error, error details are written to the structure.
◆ apr_ldap_option_set()
| apr_status_t apr_ldap_option_set | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| int | option, | ||
| const apr_ldap_opt_t * | invalue, | ||
| apu_err_t * | result_err | ||
| ) |
APR LDAP set option function
This function sets option values to a given LDAP session if one was specified. It maps to the native ldap_set_option() function.
Where an option is not supported by an LDAP toolkit, this function will try and apply legacy functions to achieve the same effect, depending on the platform.
- Parameters
-
pool The pool to use where needed ldap The LDAP handle option The LDAP_OPT_* option to set invalue The value to set result_err On error, error details are written to the structure.
◆ apr_ldap_poll()
| apr_status_t apr_ldap_poll | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| apr_pollcb_t * | poll, | ||
| apr_interval_time_t | timeout, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP poll function.
For applications that need simple set of queries, this function provides an event loop that can handle a series of LDAP requests.
This function calls apr_ldap_process() and apr_ldap_result() as needed.
- Parameters
-
pool The pool to use ldap The LDAP handle timeout The timeout to use for reads and writes. err Error structure for reporting detailed results.
- Returns
- APR_SUCCESS means that no further processing is needed. Other error codes indicate that processing was not successful.
◆ apr_ldap_prepare()
| apr_status_t apr_ldap_prepare | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| apr_ldap_prepare_cb | prepare_cb, | ||
| void * | prepare_ctx | ||
| ) |
APR LDAP prepare function
This function schedules a generic callback, fired the next time the LDAP socket is writable.
This callback can be used to prepare the initial LDAP request, or to prepare additional requests as needed without blocking.
- Parameters
-
pool The pool that keeps track of the lifetime of the callback. If this pool is cleaned up, the callback will be will be gracefully removed without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle prepare_cb The prepare callback function. When apr_ldap_process() is next called this callback will be triggered in the expectation of the next LDAP request. prepare_ctx Context passed to the prepare callback.
- Returns
- APR_SUCCESS means the callback was successfully prepared. Other error codes indicate that the attept to send the cancellation was not successful.
◆ apr_ldap_process()
| apr_status_t apr_ldap_process | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| apr_interval_time_t | timeout, | ||
| apu_err_t * | err | ||
| ) |
APR process function.
This function performs outstanding processing of any LDAP conversations currently in progress.
When a request tells you that further processing is needed, schedule this call the next time the socket is writable.
Most callbacks are fired from within apr_ldap_process() so that we are ready to write the next LDAP query should that be needed.
- Parameters
-
pool The pool to use ldap The LDAP handle timeout The timeout to use for writes. err Error structure for reporting detailed results.
- Returns
- APR_WANT_WRITE means that at least one further process is outstanding and a further write callback should be scheduled. APR_WANTS_READ indicates the a request has been sent and we're waiting for the response. APR_SUCCESS means that no further processing is needed. Other error codes indicate that the processing of outstanding conversations was not successful.
◆ apr_ldap_rename()
| apr_status_t apr_ldap_rename | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | dn, | ||
| const char * | newrdn, | ||
| const char * | newparent, | ||
| apr_ldap_rename_e | flags, | ||
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apr_interval_time_t | timeout, | ||
| apr_ldap_rename_cb | rename_cb, | ||
| void * | ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP rename function
This function allows moving or renaming of an entry from the given distinguished name, to a new relative distinguished name, a new parent object, or both.
Renamed are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_rename will return APR_WANT_READ or APR_WANT_WRITE to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the deletion will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_rename_cb provided.
- Parameters
-
pool The pool that keeps track of the lifetime of the rename conversation. If this pool is cleaned up, the rename conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle dn The distinguished named of the object to rename. newrdn The new relative distinguished named of the object. newparent The distinguished named of the parent object to move to. flags If APR_LDAP_RENAME_DELETEOLDRDN is passed, the old RDN in the entry will be removed. serverctrls NULL terminated array of server controls. clientctrls NULL terminated array of client controls. timeout The timeout to use for writes. rename_cb The rename result callback function. When the rename process has completed the success or failure of the rename is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. ctx Context passed to the rename callback. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_SUCCESS means that the processing is complete, and the rename has been successful. Other error codes indicate that the rename was not successful.
◆ apr_ldap_result()
| apr_status_t apr_ldap_result | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| apr_interval_time_t | timeout, | ||
| apu_err_t * | err | ||
| ) |
APR result function.
This function returns the result of a previous request, ready for further processing.
- Parameters
-
pool The pool to use ldap The LDAP handle timeout The timeout to use for writes. err Error structure for reporting detailed results.
- Returns
- APR_WANT_WRITE means that at least one further process is outstanding and a further write callback should be scheduled. APR_WANTS_READ indicates more responses are expected and we're waiting for the response. APR_SUCCESS means that no further processing is needed. Other error codes indicate that the processing of outstanding conversations was not successful.
◆ apr_ldap_search()
| apr_status_t apr_ldap_search | ( | apr_pool_t * | pool, |
| apr_ldap_t * | ldap, | ||
| const char * | dn, | ||
| apr_ldap_search_scope_e | scope, | ||
| const char * | filter, | ||
| const char ** | attrs, | ||
| apr_ldap_switch_e | attrsonly, | ||
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apr_interval_time_t | timeout, | ||
| apr_ssize_t | sizelimit, | ||
| apr_ldap_search_result_cb | search_result_cb, | ||
| apr_ldap_search_entry_cb | search_entry_cb, | ||
| void * | ctx, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP search function
This function searches a previously initialised LDAP connection to the directory.
Searches are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.
In the absence of an error, apr_ldap_search will return APR_WANT_READ to indicate that the next message in the conversation be retrieved using apr_ldap_result().
The outcome of the search will be retrieved and handled by the apr_ldap_result() function as each result arrives.
If one or more results are returned, the apr_ldap_search_entry_cb callback is called once for each attribute and value combination.
At the end of each entry, apr_ldap_search_entry_cb will be called with no attribute or value, giving code an opportunity to perform any processing only possible after all of the entries have been retrieved.
Once all entries have been processed, apr_ldap_search_result_cb is called to indicate the final result of the search.
If no entries are returned, only apr_ldap_search_result_cb will be called.
- Parameters
-
pool The pool that keeps track of the lifetime of the search conversation. If this pool is cleaned up, the search conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool. ldap The ldap handle dn The base distinguished named of the search. scope The scope of the search. filter The search filter string. attrs NULL terminated array of attributes to return. attrsonly If on, attributes will be returned without values. serverctrls NULL terminated array of server controls. clientctrls NULL terminated array of client controls. timeout The timeout to use for writes. sizelimit The maximum number of entries to return in the search. search_result_cb The search result callback function. When the search process has completed the success or failure of the search is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request. search_entry_cb The search entry callback function. For each value of each attribute of each entry, this callback is called with each value. This callback is then fired off one more time at the end of each entry, giving the chance to handle that entry. The callback is triggered from inside apr_ldap_result(). ctx Context passed to the search result and search entry callbacks. err Error structure for reporting detailed results.
- Returns
- APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). Other error codes indicate that the search attempt was not successful.
◆ apr_ldap_unbind()
| apr_status_t apr_ldap_unbind | ( | apr_ldap_t * | ldap, |
| apr_array_header_t * | serverctrls, | ||
| apr_array_header_t * | clientctrls, | ||
| apu_err_t * | err | ||
| ) |
APR LDAP unbind function
This function unbinds from the LDAP server, and frees the connection handle.
Calling this function is optional, the same effect can be achieved by cleaning up the pool passed to apr_ldap_initialise().
- See also
- apr_ldap_initialise
◆ apr_ldap_url_parse()
| int apr_ldap_url_parse | ( | apr_pool_t * | pool, |
| const char * | url_in, | ||
| apr_ldap_url_desc_t ** | ludpp, | ||
| apu_err_t ** | result_err | ||
| ) |
Parse an LDAP URL.
- Parameters
-
pool The pool to use url_in The URL to parse ludpp The structure to return the exploded URL result_err The result structure of the operation
◆ apr_ldap_url_parse_ext()
| int apr_ldap_url_parse_ext | ( | apr_pool_t * | pool, |
| const char * | url_in, | ||
| apr_ldap_url_desc_t ** | ludpp, | ||
| apu_err_t ** | result_err | ||
| ) |
Parse an LDAP URL.
- Parameters
-
pool The pool to use url_in The URL to parse ludpp The structure to return the exploded URL result_err The result structure of the operation
