Back to Handling Errors and Parsing Results
The ldap_first_message() and ldap_next_message() routines are used to step through the list of messages in a result chain returned by ldap_result(). For search operations, the result chain may actually include referral messages, entry messages, and result messages. ldap_count_messages() is used to count the number of messages returned. The ldap_msgtype() function, described above, can be used to distinguish between the different message types.
LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
int ldap_count_messages( LDAP *ld, LDAPMessage *res );
Parameters are:
ldap_first_message() and ldap_next_message() will return NULL when no more messages exist in the result set to be returned. NULL is also returned if an error occurs while stepping through the entries, in which case the error parameters in the session handle ld will be set to indicate the error.
ldap_count_messages() returns the number of messages contained in a chain of results. It can also be used to count the number of messages that remain in a chain if called with a message, entry, or reference returned by ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
The following calls are used to parse the entries and references returned by ldap_search() and friends. These results are returned in an opaque structure that should only be accessed by calling the routines described below. Routines are provided to step through the entries and references returned, step through the attributes of an entry, retrieve the name of an entry, and retrieve the values associated with a given attribute in an entry.
The ldap_first_entry() and ldap_next_entry() routines are used to step through and retrieve the list of entries from a search result chain. The ldap_first_reference() and ldap_next_reference() routines are used to step through and retrieve the list of continuation references from a search result chain. ldap_count_entries() is used to count the number of entries returned. ldap_count_references() is used to count the number of references returned.
LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
int ldap_count_entries( LDAP *ld, LDAPMessage *res );
int ldap_count_references( LDAP *ld, LDAPMessage *res );
Parameters are:
ldap_first_entry() and ldap_next_entry() will return NULL when no more entries or references exist in the result set to be returned. NULL is also returned if an error occurs while stepping through the entries, in which case the error parameters in the session handle ld will be set to indicate the error.
ldap_count_entries() returns the number of entries contained in a chain of entries. It can also be used to count the number of entries that remain in a chain if called with a message, entry or reference returned by ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
ldap_count_references() returns the number of references contained in a chain of search results. It can also be used to count the number of references that remain in a chain.
The ldap_first_attribute() and ldap_next_attribute() calls are used to step through the list of attribute types returned with an entry.
char *ldap_first_attribute(
LDAP *ld,
LDAPMessage *entry,
BerElement **ptr
);
char *ldap_next_attribute(
LDAP *ld,
LDAPMessage *entry,
BerElement *ptr
);
void ldap_memfree( char *mem );
Parameters are:
ldap_first_attribute() and ldap_next_attribute() will return NULL when the end of the attributes is reached, or if there is an error, in which case the error parameters in the session handle ld will be set to indicate the error.
Both routines return a pointer to an allocated buffer containing the current attribute name. This should be freed when no longer in use by calling ldap_memfree().
ldap_first_attribute() will allocate and return in ptr a pointer to a BerElement used to keep track of the current position. This pointer should be passed in subsequent calls to ldap_next_attribute() to step through the entry's attributes. After a set of calls to ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it should be freed by calling ldap_ber_free( ptr, 0 ). Note that it is very important to pass the second parameter as 0 (zero) in this call.
The attribute names returned are suitable for passing in a call to ldap_get_values() and friends to retrieve the associated values.
ldap_get_values() and ldap_get_values_len() are used to retrieve the values of a given attribute from an entry. ldap_count_values() and ldap_count_values_len() are used to count the returned values. ldap_value_free() and ldap_value_free_len() are used to free the values.
char **ldap_get_values(
LDAP *ld,
LDAPMessage *entry,
char *attr
);
struct berval **ldap_get_values_len(
LDAP *ld,
LDAPMessage *entry,
char *attr
);
int ldap_count_values( char **vals );
int ldap_count_values_len( struct berval **vals );
int ldap_value_free( char **vals );
int ldap_value_free_len( struct berval **vals );
Parameters are:
Two forms of the various calls are provided. The first form is only suitable for use with non-binary character string data. The second _len form is used with any kind of data.
Note that the values returned are dynamically allocated and should be freed by calling either ldap_value_free() or ldap_value_free_len() when no longer in use.
ldap_get_dn() is used to retrieve the name of an entry. ldap_explode_dn() and ldap_explode_rdn() are used to break up a name into its component parts. ldap_dn2ufn() is used to convert the name into a more "user friendly" format.
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
char **ldap_explode_dn( char *dn, int notypes );
char **ldap_explode_rdn( char *rdn, int notypes );
char **ldap_explode_ava (char *rdncomp);
char *ldap_dn2ufn( char *dn );
Parameters are:
ldap_get_dn() will return NULL if there is some error parsing the dn, setting error parameters in the session handle ld to indicate the error. It returns a pointer to malloc'ed space that the caller should free by calling ldap_memfree() when it is no longer in use. Note the format of the DNs returned is given by RFC 2253.
ldap_explode_dn() returns a NULL-terminated char * array containing the RDN components of the DN supplied, with or without types as indicated by the notypes parameter. The array returned should be freed when it is no longer in use by calling ldap_value_free().
ldap_explode_rdn() returns a NULL-terminated char * array containing the components of the RDN supplied, with or without types as indicated by the notypes parameter. The array returned should be freed when it is no longer in use by calling ldap_value_free().
ldap_explode_ava() separates a single RDN into its type and value. The resulting array should be freed by calling ldap_value_free(). This function is specific to this implementation.
ldap_dn2ufn() converts the DN into a user friendly format described in RFC 1779. The UFN returned is malloc'ed space that should be freed by a call to ldap_memfree() when no longer in use.