HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

13.14 Deleting an Entry

The following functions are used to delete a leaf entry from the LDAP directory. There are four variations.

        int ldap_delete_ext(
                LDAP                               *ld,
                const char                         *dn,
                LDAPControl                        **serverctrls,
                LDAPControl                        **clientctrls,
                int                                *msgidp
        );

        int ldap_delete_ext_s(
                LDAP                               *ld,
                const char                         *dn,
                LDAPControl                        **serverctrls,
                LDAPControl                        **clientctrls
        );

        int ldap_delete(
                LDAP                               *ld,
                const char                         *dn
        );

        int ldap_delete_s(
                LDAP                               *ld,
                const char                         *dn
        );

Parameters are as follows:

ld	The session handle.
dn	The name of the entry to delete.
serverctrls	List of LDAP server controls.
clientctrls	List of client controls.
msgidp	This result parameter will be set to the message id of the request if the `ldap_delete_ext()` call succeeds.

Note that the entry to delete must be a leaf entry (that is, it must have no children). Deletion of entire subtrees in a single operation is not supported by LDAP.

The ldap_delete_ext() function initiates an asynchronous delete operation and returns either the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 13.18 for more information about possible errors and how to interpret them. If successful, ldap_delete_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of the delete.

Similar to ldap_delete_ext() , the ldap_delete() function initiates an asynchronous delete operation and returns the message id of the operation initiated. As for ldap_delete_ext() , a subsequent call to ldap_result() can be used to obtain the result of the delete. In case of error, ldap_delete() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful or another LDAP error code if it was not. See Section 13.18 for more information about possible errors and how to interpret them.

The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 server controls and client controls.

13.15 Extended Operations

The ldap_extended_operation() and ldap_extended_operation_s() functions allow extended LDAP operations to be passed to the server, providing a general protocol extensibility mechanism.

        int ldap_extended_operation(
                LDAP                               *ld,
                const char                         *requestoid,
                const struct berval                *request data,
                LDAPControl                        **serverctrls,
                LDAPControl                        **clientctrls,
                int                                *msgidp
        );

        int ldap_extended_operation_s(
                LDAP                               *ld,
                const char                         *requestoid,
                const struct berval                *request data,
                LDAPControl                        **serverctrls,
                LDAPControl                        **clientctrls,
                char                               **retoidp,
                struct berval                      **retdatap
        );

Parameters are as follows:

ld	The session handle.
requestoid	The dotted-OID text string naming the request.
requestdata	The arbitrary data required by the operation (if NULL, no data is sent to the server).
serverctrls	List of LDAP server controls.
clientctrls	List of client controls.
msgidp	This result parameter will be set to the message id of the request if the `ldap_extended_operation()` call succeeds.
retoidp	Pointer to a character string that will be set to an allocated, dotted- OID text string returned by the server. This string should be disposed of using the `ldap_memfree()` function. If no OID was returned, *retoidp is set to NULL.
retdatap	Pointer to a berval structure pointer that will be set to an allocated copy of the data returned by the server. This struct berval should be disposed of using ber_bvfree(). If no data is returned, *retdatap is set to NULL.

The ldap_extended_operation() function initiates an asynchronous extended operation and returns either the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 13.18 for more information about possible errors and how to interpret them. If successful, ldap_extended_operation() places the message id of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of the extended operation which can be passed to ldap_parse_extended_result() to obtain the OID and data contained in the response.

The synchronous ldap_extended_operation_s() function returns the result of the operation, either the constant LDAP_SUCCESS if the operation was successful or another LDAP error code if it was not. See Section 13.18 for more information about possible errors and how to interpret them. The retoid and retdata parameters are filled in with the OID and data from the response. If no OID or data was returned, these parameters are set to NULL.

The ldap_extended_operation() and ldap_extended_operation_s() functions both support LDAPv3 server controls and client controls.

13.16 Abandoning an Operation

The following calls are used to abandon an operation in progress:

        int ldap_abandon_ext(
                LDAP                               *ld,
                int                                msgid,
                LDAPControl                        **serverctrls,
                LDAPControl                        **clientctrls
        );

        int ldap_abandon(
                LDAP                               *ld,
                int                                msgid
        );

Parameters are as follows:

ld	The session handle.
msgid	The message id of the request to be abandoned.
serverctrls	List of LDAP server controls.
clientctrls	List of client controls.

The ldap_abandon_ext() function abandons the operation with message id msgid and returns either the constant LDAP_SUCCESS if the abandon was successful or another LDAP error code if not. See Section 13.18 for more information about possible errors and how to interpret them.

The ldap_abandon() function is identical to ldap_abandon_ext() except that it does not accept client or server controls and it returns zero if the abandon was successful, -1 otherwise and does not support LDAPv3 server controls or client controls.

After a successful call to ldap_abandon() or ldap_abandon_ext() , results with the given message id are never returned from a subsequent call to ldap_result() . There is no server response to LDAP abandon operations.

13.17 Obtaining Results and Looking Inside LDAP Messages

The ldap_result() function is used to obtain the result of a previous asynchronously initiated operation. Note that depending on how it is called, ldap_result() may actually return a list or "chain" of result messages. Once a chain of messages has been returned to the caller, it is no longer tied in any caller-visible way to the LDAP request that produced it. Therefore, a chain of messages returned by calling ldap_result() or by calling a synchronous search function will never be affected by subsequent LDAP API calls (except for ldap_msgfree() , which is used to dispose of a chain of messages).

The ldap_msgfree() function frees the result messages (possibly an entire chain of messages) obtained from a previous call to ldap_result() or from a call to a synchronous search function.

The ldap_msgtype() function returns the type of an LDAP message. The ldap_msgid() function returns the message ID of an LDAP message.

        int ldap_result(
                LDAP                               *ld,
                int                                msgid,
                int                                all,
                struct timeval                     *timeout,
                LDAPMessage                        **res
        );

        int ldap_msgfree( LDAPMessage *res );

        int ldap_msgtype( LDAPMessage *res );

        int ldap_msgid( LDAPMessage *res );

Parameters are as follows:

ld	The session handle.
msgid	The message id of the operation whose results are to be returned, or the constant LDAP_RES_ANY (-1) if any result is desired.
all	Specifies how many messages will be retrieved in a single call to `ldap_result()` . This parameter only has meaning for search results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one message at a time. Pass LDAP_MSG_ALL (0x01) to request that all results of a search be received before returning all results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to indicate that all results retrieved so far should be returned in the result chain.
timeout	A timeout specifying how long to wait for results to be returned. A NULL value causes `ldap_result()` to block until results are available. A timeout value of zero seconds specifies a polling behavior.
res	For `ldap_result()` , a result parameter that will contain the result(s) of the operation. For `ldap_msgfree()` , the result chain to be freed, obtained from a previous call to `ldap_result()` , `ldap_search_s()` , or `ldap_search_st()` .

Upon successful completion, ldap_result() returns the type of the first result returned in the res parameter. This will be one of the following constants.

        LDAP_RES_BIND (0x61)

        LDAP_RES_SEARCH_ENTRY (0x64)

        LDAP_RES_SEARCH_REFERENCE (0x73)      -- new in LDAPv3

        LDAP_RES_SEARCH_RESULT (0x65)

        LDAP_RES_MODIFY (0x67)

        LDAP_RES_ADD (0x69)

        LDAP_RES_DELETE (0x6B)

        LDAP_RES_MODDN (0x6D)

        LDAP_RES_COMPARE (0x6F)

        LDAP_RES_EXTENDED (0x78)              -- new in LDAPv3

The ldap_result() function returns 0 if the timeout expired and -1 if an error occurs, in which case the error parameters of the LDAP session handle will be set accordingly.

The ldap_msgfree() function frees the result structure pointed to by res and returns the type of the message it freed.

The ldap_msgtype() function returns the type of the LDAP message it is passed as a parameter. The type will be one of the types listed above, or -1 on error.

The ldap_msgid() function returns the message ID associated with the LDAP message passed as a parameter.

13.18 Handling Errors and Parsing Results

The following calls are used to extract information from results and handle errors returned by other LDAP API functions. Note that ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typically be used in addition to ldap_parse_result() to retrieve all the result information from SASL bind and extended operations, respectively.

        int ldap_parse_result(
                LDAP                               *ld,
                LDAPMessage                        *res,
                int                                *errcodep,
                char                               **matcheddnp,
                char                               **errmsgp,
                char                               ***referralsp,
                LDAPControl                        ***serverctrlsp,
                int                                freeit
        );

        int ldap_parse_sasl_bind_result(
                LDAP                               *ld,
                LDAPMessage                        *res,
                struct berval                      **servercredp,
                int                                freeit
        );

        int ldap_parse_extended_result(
                LDAP                               *ld,
                LDAPMessage                        *res,
                char                               **resultoidp,
                struct berval                      **resultdata,
                int                                freeit
        );

        char *ldap_err2string( int err );

The use of the following functions is deprecated.

        int ldap_result2error(
                LDAP                               *ld,
                LDAPMessage                        *res,
                int                                freeit
        );

        void ldap_perror( LDAP *ld, const char *msg );

Parameters are as follows:

ld	The session handle.
res	The result of an LDAP operation as returned by `ldap_result()` or one of the synchronous API operation calls.
errcodep	This result parameter will be filled in with the LDAP error code field from the LDAPMessage result. This is the indication from the server of the outcome of the operation. NULL may be passed to ignore this field.
matcheddnp	In the case of a return of LDAP_NO_SUCH_OBJECT, this result parameter will be filled in with a DN indicating how much of the name in the request was recognized. NULL may be passed to ignore this field. The matched DN string should be freed by calling `ldap_memfree()` .
errmsgp	This result parameter will be filled in with the contents of the error message field from the LDAPMessage result. The error message string should be freed by calling `ldap_memfree()` . NULL may be passed to ignore this field.
referralsp	This result parameter will be filled in with the contents of the referrals field from the LDAPMessage result, indicating zero or more alternate LDAP servers where the request should be retried. The referrals array should be freed by calling `ldap_value_free()` . NULL may be passed to ignore this field.
serverctrlsp	This result parameter will be filled in with an allocated array of controls copied out of the LDAPMessage result. The control array should be freed by calling `ldap_controls_free()` .
freeit	A boolean that determines whether or not the res parameter is disposed of. Pass any non-zero value to have these functions free res after extracting the requested information. This option is provided as a convenience; you can also use `ldap_msgfree()` to free the result later. If freeit is non-zero, the entire chain of messages represented by res is disposed of.
servercredp	For SASL bind results, this result parameter will be filled in with the credentials passed back by the server for mutual authentication, if given. An allocated berval structure is returned that should be disposed of by calling ber_bvfree(). NULL may be passed to ignore this field.
resultoidp	For extended results, this result parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. This string should be disposed of by calling `ldap_memfree()` . NULL may be passed to ignore this field.
resultdatap	For extended results, this result parameter will be filled in with a pointer to a struct berval containing the data in the extended operation response. It should be disposed of by calling ber_bvfree(). NULL may be passed to ignore this field.
err	For `ldap_err2string()` , an LDAP error code, as returned by `ldap_parse_result()` or another LDAP API call.

Additional parameters for the deprecated functions are not described. See RFC 1823 for more information.

All three of the ldap_parse_*_result() functions skip over messages of type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a result message to parse. They return either the constant LDAP_SUCCESS if the result was successfully parsed or another LDAP error code if not. Note that the LDAP error code that indicates the outcome of the operation performed by the server is placed in the errcodep ldap_parse_result() parameter. If a chain of messages that contains more than one result message is passed to these functions, they always operate on the first result in the chain.

The ldap_err2string() function is used to convert a numeric LDAP error code, as returned by either one of the three ldap_parse_*_result() functions or one of the synchronous API operation calls, into an informative zero-terminated character string message describing the error. It returns a pointer to static data.

13.18.1 Stepping Through a List of Results

The 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.

 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
 LDAPMessage *ldap_next_message ( LDAP *ld, LDAPMesage *msg );
 int ldap_count_messages( LDAP *ld, LDAPMessage *res );

Parameters are as follows:

ld	The session handle.
res	The result chain, as obtained by a call to one of the synchronous search functions or `ldap_result()` .
msg	The message returned by a previous call to `ldap_first_message()` or `ldap_next_message()` .

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() .

Contents

Index