![]() |
![]() HP OpenVMS Systems Documentation |
![]() |
OpenVMS Utility Routines Manual
12.18.1 Stepping Through a List of ResultsThe ldap_first_message() and ldap_next_message() functions 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. The ldap_count_messages() function is used to count the number of messages returned. The ldap_msgtype() function can be used to distinguish between the different message types.
Parameters are as follows:
The ldap_first_message() and ldap_next_message() functions 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.
The
ldap_count_messages()
function 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()
. These results are returned in an opaque structure that should only be
accessed by calling the functions. Functions 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() functions are used to step through and retrieve the list of entries from a search result chain. The ldap_first_reference() and ldap_next_reference() functions are used to step through and retrieve the list of continuation references from a search result chain. The ldap_count_entries() function is used to count the number of entries returned. The ldap_count_references() function is used to count the number of references returned.
Parameters are as follows:
The ldap_first_entry() and ldap_next_entry() functions 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. The ldap_count_entries() function 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() .
The
ldap_count_references()
function 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.
Parameters are as follows:
The ldap_first_attribute() and ldap_next_attribute() functions 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 functions 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() . The ldap_first_attribute() function 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_attribute() , if ptr is non-NULL, it should be freed by calling ber_free(ptr, 0) . Note that it is very important to pass the second parameter as 0 (zero) in this call, since the buffer associated with the BerElement does not point to separately allocated memory.
The attribute type names returned are suitable for passing in a call to
ldap_get_values()
to retrieve the associated values.
The ldap_get_values() and ldap_get_values_len() functions are used to retrieve the values of a given attribute from an entry. The ldap_count_values() and ldap_count_values_len() functions are used to count the returned values. The ldap_value_free() and ldap_value_free_len() functions are used to free the values.
Parameters are as follows:
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. The ldap_get_values() and ldap_get_values_len() functions return NULL if no values are found for attr or if an error occurs. The ldap_count_values() and ldap_count_values_len() functions return -1 if an error occurs such as the vals parameter being invalid.
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.
The ldap_get_dn() function is used to retrieve the name of an entry. The ldap_explode_dn() and ldap_explode_rdn() functions are used to break up a name into its component parts. The ldap_dn2ufn() function is used to convert the name into a more user-friendly format.
Parameters are as follows:
The ldap_get_dn() function 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 newly allocated space that the caller should free by calling ldap_memfree() when it is no longer in use. The ldap_explode_dn() function 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 components are returned in the order they appear in the dn. The array returned should be freed when it is no longer in use by calling ldap_value_free() . The ldap_explode_rdn() function returns a NULL-terminated char * array containing the components of the RDN supplied, with or without types as indicated by the notypes parameter. The components are returned in the order they appear in the rdn. The array returned should be freed when it is no longer in use by calling ldap_value_free() .
The
ldap_dn2ufn()
function converts the DN into the user friendly format. The UFN
returned is newly allocated space that should be freed by a call to
ldap_memfree()
when no longer in use.
The ldap_get_entry_controls() function is used to extract LDAP controls from an entry.
Parameters are as follows:
The
ldap_get_entry_controls()
function returns an LDAP error code that indicates whether the
reference could be successfully parsed (LDAP_SUCCESS if all goes well).
The ldap_parse_reference() function is used to extract referrals and controls from a SearchResultReference message.
Parameters are as follows:
The
ldap_parse_reference()
function returns an LDAP error code that indicates whether the
reference could be successfully parsed (LDAP_SUCCESS if all goes well).
This section describes functions that may be used to encode and decode BER-encoded ASN.1 values, which are often used inside of control and extension values. The following additional integral types are defined for use in manipulation of BER encoded ASN.1 values:
With the exceptions of two new functions, ber_flatten() and ber_init() , these functions are compatible with the University of Michigan LDAP 3.3 implementation of BER.
A struct berval contains a sequence of bytes and an indication of its length. The bv_val is not null terminated. A bv_len must always be a nonnegative number. Applications may allocate their own berval structures.
The BerElement structure contains not only a copy of the encoded value, but also state information used in encoding or decoding. Applications cannot allocate their own BerElement structures. The internal state is neither thread-specific nor locked, so two threads should not manipulate the same BerElement value simultaneously. A single BerElement value cannot be used for both encoding and decoding.
The ber_bvfree() function frees a berval returned from this API. Both the bv->bv_val string and the berval itself are freed. Applications should not use ber_bvfree() with bervals which the application has allocated.
The ber_bvecfree() function frees an array of bervals returned from this API. Each of the bervals in the array are freed using ber_bvfree() , then the array itself is freed.
The ber_bvdup() function returns a copy of a berval. The bv_val field in the returned berval points to a different area of memory as the bv_val field in the argument berval. The null pointer is returned on error (for example, out of memory).
The ber_free() function frees a BerElement which is returned from the API calls ber_alloc_t() or ber_init() . Each BerElement must be freed by the caller. The second argument fbuf should always be set to 1 to ensure that the internal buffer used by the BER functions is freed as well as the BerElement container itself.
|