LDAP_EXTENDED_OPERATION

Use the LDAP_EXTENDED_OPERATION API or LDAP routine to conduct extended operations and parse extended result.

ldap_extended_operation
ldap_extended_operation_s

Synopsis

#include ldap.h


int     ldap_extended_operation(
                LDAP            *ld,
                const char      *reqoid, 
                const struct berval *reqdata,
                LDAPControl     **serverctrls, 
                LDAPControl     **clientctrls,
                int             *msgidp)

int     ldap_extended_operation_s(
                LDAP            *ld, 
                const char      *reqoid, 
                const struct berval *reqdata,
                LDAPControl     **serverctrls, 
                LDAPControl     **clientctrls,
                char            **retoidp,
                struct berval   **retdatap)

Input parameters

ld: Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init() or ldap_open().
reqoid: Specifies the dotted-object identifier (OID) text string that identifies the extended operation to be run by the server.
reqdata: Specifies the arbitrary data that is required by the extended operation. If NULL, no data is sent to the server.
serverctrls: Specifies a list of LDAP server controls. This parameter can be set to NULL. For more information about server controls, see LDAP controls.
clientctrls: Specifies a list of LDAP client controls. This parameter can be set to NULL. For more information about client controls, see LDAP controls.

Output parameters

msgidp: This result parameter is set to the message ID of the request if the ldap_extended_operation() call is successfully sent to the server. To check the result of this operation, call the ldap_result() and ldap_parse_result() APIs. The server can also return an OID and result data. Because the asynchronous ldap_extended_operation does not directly return the results, use ldap_parse_extended_result() to get the results.
retoidp: This result parameter is set to point to a character string that is set to an allocated, dotted-OID text string that is returned from the server. This string must be disposed of using the ldap_memfree() API. If no OID is returned, *retoidp is set to NULL.
retdatap: This result parameter is set to a pointer to a berval structure pointer that is set to an allocated copy of the data. This data is returned by the server. This struct berval must be disposed of using ber_bvfree(). If no data is returned, *retdatap is set to NULL.

Usage

The ldap_extended_operation() function is used to initiate an asynchronous extended operation, which returns LDAP_SUCCESS if the extended operation was successfully sent, or an LDAP error code is returned if the operation was not successful. If successful, the ldap_extended_operation() API 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 then be passed to ldap_parse_extended_result() to obtain the OID and data that is contained in the response.

The ldap_extended_operation_s() function is used to initiate a synchronous extended operation, which returns the result of the operation: either LDAP_SUCCESS if the operation was successful, or it returns another LDAP error code if it was not successful. The retoid and retdata parameters are provided with the OID and data from the response. If no OID or data was returned, these parameters are set to NULL.

If the LDAP server does not support the extended operation, the server rejects the request. IBM® Security Verify Directory, version 6.0 and later provide a server plug-in interface that can be used to add extended operation support. For more information, see the IBM Security Verify Directory Server Plug-ins Reference.

To determine whether the requisite extended operation is supported by the server, get the rootDSE of the LDAP server and check for the supportedExtension attribute. If the values for this attribute include the OID of your extended operation, then the server supports the extended operation. If the supportedExtension attribute is not present in the rootDSE, then the server is not configured to support any extended operations.

A list of OIDs for supported extended operations can be found in Object Identifiers (OIDs) for extended operations and controls.

Errors

The lldap_extended_operation() API returns the LDAP error code for the operation.

The ldap_extended_operation() API returns -1 instead of a valid msgid if an error occurs, setting the session error in the LD structure. The session error can be obtained by using ldap_get_errno().

For more information, see LDAP_ERROR.

Notes®

These routines allocate storage. Use ldap_memfree to free the returned OID. Use ber_bvfree to free the returned struct berval.