Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

## 12.13 Adding an Entry

The following functions are used to add entries to the LDAP directory. There are four variations.

            int ldap_add_ext(
                    LDAP                                    *ld,
                    const char                              *dn,
                    LDAPMod                                 **attrs,
                    LDAPControl                             **serverctrls,
                    LDAPControl                             **clientctrls,
                    int                                     *msgidp
            );

            int ldap_add_ext_s(
                    LDAP                                    *ld,
                    const char                              *dn,
                    LDAPMod                                 **attrs,
                    LDAPControl                             **serverctrls,
                    LDAPControl                             **clientctrls
            );

            int ldap_add(
                    LDAP                                    *ld,
                    const char                              *dn,
                    LDAPMod                                 **attrs
            );

            int ldap_add_s(
                    LDAP                                    *ld,
                    const char                              *dn,
                    LDAPMod                                 **attrs
            );

Parameters are as follows:

ld | The session handle.
dn | The name of the entry to add.
attrs | The entry's attributes, specified using the LDAPMod structure defined for `ldap_modify()` . The mod_type and mod_vals fields should be filled in. The mod_op field is ignored unless ORed with the constant LDAP_MOD_BVALUES, used to select the mod_bvalues case of the mod_vals union.
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_add_ext()` call succeeds.

Note that the parent of the entry being added must already exist or the parent must be empty (that is, equal to the root DN) for an add to succeed.

The `ldap_add_ext()` function initiates an asynchronous add operation and returns either the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 12.18 for more information about possible errors and how to interpret them. If successful, `ldap_add_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 add.

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

The synchronous `ldap_add_ext_s()` and `ldap_add_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 12.18 for more information about possible errors and how to interpret them.

The `ldap_add_ext()` and `ldap_add_ext_s()` functions support LDAPv3 server controls and client controls.

## 12.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 12.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 12.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.

## 12.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 12.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 12.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.

## 12.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 12.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.

## 12.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.

## 12.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 the res parameter is disposed of or not. Pass any non-zero value to have these functions free res after extracting the requested information. This 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.

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_029.HTML