%docentities; ]> &develguide;
Overview The LDAP module API can be used by other &kamailio; modules to implement LDAP search functionality. This frees the module implementer from having to care about LDAP connection management and configuration. In order to use this API, a module has to load the API using the load_ldap_api function which returns a pointer to a ldap_api structure. This structure includes pointers to the API functions described below. The LDAP module source file api.h includes all declarations needed to load the API, it has to be included in the file that use the API. Loading the API is typically done inside a module's mod_init call as the following example shows: Example code fragment to load LDAP module API The API functions can then be used like in the following example: Example LDAP module API function call
API Functions
ldap_params_search Performs an LDAP search using the parameters given as function arguments. Function arguments: int* _ld_result_count The function stores the number of returned LDAP entries in _ld_result_count. char* _lds_name LDAP session name as configured in the LDAP module configuration file. char* _dn LDAP search DN. int _scope LDAP search scope, one of LDAP_SCOPE_ONELEVEL, LDAP_SCOPE_BASE, or LDAP_SCOPE_SUBTREE, as defined in OpenLDAP's ldap.h. char** _attrs A null-terminated array of attribute types to return from entries. If empty (NULL), all attribute types are returned. char* _filter LDAP search filter string according to RFC 4515. printf patterns in this string do get replaced with the function arguments' values following the _filter argument. Return Values: -1 Internal error. 0 Success, _ld_result_count includes the number of LDAP entries found.
ldap_url_search Performs an LDAP search using an LDAP URL. Function arguments: char* _ldap_url LDAP URL as described in . int* _result_count The function stores the number of returned LDAP entries in _ld_result_count. Return Values: -1 Internal error. 0 Success, _ld_result_count includes the number of LDAP entries found.
ldap_result_attr_vals Retrieve the value(s) of a returned LDAP attribute. The function accesses the LDAP result returned by the last call of ldap_params_search or ldap_url_search. The berval structure is defined in OpenLDAP's ldap.h, which has to be included. This function allocates memory to store the LDAP attribute value(s). This memory has to freed with the function ldap_value_free_len (see next section). Function arguments: str* _attr_name str structure holding the LDAP attribute name. struct berval ***_vals A null-terminated array of the attribute's value(s). Return Values: -1 Internal error. 0 Success, _vals includes the attribute's value(s). 1 No attribute value found.
ldap_value_free_len Function used to free memory allocated by ldap_result_attr_vals. The berval structure is defined in OpenLDAP's ldap.h, which has to be included. Function arguments: struct berval **_vals berval array returned by ldap_result_attr_vals.
ldap_result_next Increments the LDAP result pointer. Return Values: -1 No LDAP result found, probably because ldap_params_search or ldap_url_search was not called. 0 Success, LDAP result pointer points now to next result. 1 No more results available.
ldap_str2scope Converts LDAP search scope string into integer value e.g. for ldap_params_search. Function arguments: char* scope_str LDAP search scope string. One of "one", "onelevel", "base", "sub", or "subtree". Return Values: -1 scope_str not recognized. n >= 0 LDAP search scope integer.
ldap_rfc4515_escape Applies escaping rules described in . Function arguments: str *sin str structure holding the string to apply the escaping rules. str *sout str structure holding the escaped string. The length of this string must be at least three times the length of sin plus one. int url_encode Flag that specifies if a '?' character gets escaped with '%3F' or not. If url_encode equals 0, '?' does not get escaped. Return Values: -1 Internal error. 0 Success, sout contains escaped string.
get_ldap_handle Returns the OpenLDAP LDAP handle for a specific LDAP session. This allows a module implementor to use the OpenLDAP API functions directly, instead of using the API functions exported by the &kamailio; LDAP module. The LDAP structure is defined in OpenLDAP's ldap.h, which has to be included. Function arguments: char* _lds_name LDAP session name as specified in the LDAP module configuration file. LDAP** _ldap_handle OpenLDAP LDAP handle returned by this function. Return Values: -1 Internal error. 0 Success, _ldap_handle contains the OpenLDAP LDAP handle.
get_last_ldap_result Returns the OpenLDAP LDAP handle and OpenLDAP result handle of the last LDAP search operation. These handles can be used as input for OpenLDAP LDAP result API functions. LDAP and LDAPMessage structures are defined in OpenLDAP's ldap.h, which has to be included. Function arguments: LDAP** _last_ldap_handle OpenLDAP LDAP handle returned by this function. LDAPMessage** _last_ldap_result OpenLDAP result handle returned by this function.
Example Usage The following example shows how this API can be used to perform an LDAP search operation. It is assumed that the API is loaded and available through the ldap_api pointer. bv_val; res_password.len = attr_vals[0]->bv_len; ldap_api.ldap_value_free_len(attr_vals); LM_INFO("Password for user [%s]: [%s]\n", sip_username, res_password.s); ... return 0; ]]>