Chapter 15 Extended Operations

The Sun™ Java System LDAP SDK for C contains the functionality to integrate Lightweight Directory Access Protocol (LDAP) v3 extended operations. This chapter explains how LDAPv3 extended operations work and how to use those that are supported by your LDAP server. It contains the following sections:

How Extended Operations Work

Extended operations are part of the LDAPv3. Each extended operation is identified by an object identifier (OID). LDAP clients can request the operation by sending an extended operation request. Within the request, the client specifies:

The server receives the request, performs the extended operation, and sends back a response to the client containing an OID and any additional data.


Note	In order to use extended operations, both the server and the client must understand the specific extended operation to be performed. From the LDAP server perspective, Sun Java System Directory Server supports a server plug-in interface that you can use to add support for extended operations. For details, see the Sun ONE Directory Server Plug-In Programming Guide.

Determining Supported Extended Operations

To determine the extended operations supported by the server, get the root DSE of the server, and check the supportedExtension attribute. The values of this attribute are the OIDs of the extended operations supported by this server. If the root DSE does not have a supportedExtension attribute, the server does not support any extended operations. For information on the root DSE, see "Getting the Root DSE" of Chapter 10, "Retrieving Server Information."

Performing an Extended Operation

Both of these functions allow you to specify the OID of the extended operation and the data that you want applied to the operation.

Synchronous Extended Operation


Tip	Before calling the function to perform a LDAP extended operation, make sure to specify that your client is using version 3 of the LDAP. If you do not, an LDAP_NOT_SUPPORTED result code is returned. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."

If you want to wait for the results of an LDAP extended operation to complete before continuing, call the synchronous ldap_extended_operation_s() function. This function sends a SASL bind request to the server and blocks other work until the server sends the results of the operation back to your client.

Asynchronous Extended Operation

If you want to perform other work (in parallel) while waiting for an LDAP extended operation to complete, do the following:

Call the asynchronous ldap_extended_operation() function to send an LDAP extended operation request.

This function returns an LDAP_SUCCESS result code if the request was successfully sent (or an LDAP result code if an error occurred while sending the request). The function also sets the msgidp argument to point to a message ID identifying the extended operation. To determine whether the server sent a response to your client for this operation, call the ldap_result() function and pass in this message ID. The function passes back the response in an LDAPMessage structure.

Call the ldap_parse_extended_result() function to parse the LDAPMessage structure and retrieve information from the server’s response.

If the server sent an OID of an extended operation to your client, the OID is passed back as the retoidp argument. If the server sent a data to your client, the data is specified in the berval structure passed back as the retdatap argument.

Call the ldap_get_lderrno() function to get the LDAP result code for the operation.

The function returns an LDAP_SUCCESS result code if the extended operation was performed successfully or an LDAP error code if a problem occurred. See the documentation of the ldap_extended_operation() function for a list of result codes that the server can return for this operation.

Sample Code to Perform an Extended Operation

Code Example 15-1 is an example of an LDAP client that request an extended operation from the server with the OID 1.2.3.4.

Code Example 15-1 Requesting an Extended Operation


#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include "ldap.h"

/* Name and port of the LDAP server you want to connect to. */
#define MY_HOST "localhost"
#define MY_PORT 389
/* DN of user (and password of user) who you want to authenticate as */
#define MGR_DN "cn=Directory Manager"
#define MGR_PW "23skidoo"
int
main( int argc, char **argv )
{
/* OID of the extended operation that you are requesting */
const char *oidrequest = "1.2.3.4";
char *oidresult;
struct berval valrequest;
struct berval *valresult;
LDAP *ld;
int rc, version;
/* Set up the value that you want to pass to the server */
printf( "Setting up value to pass to server...\n" );
valrequest.bv_val = "My Value";
valrequest.bv_len = strlen( "My Value" );
/* Get a handle to an LDAP connection */
printf( "Getting the handle to the LDAP connection...\n" );
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
perror( "ldap_init" );
ldap_unbind( ld );
return( 1 );
}
/* Set the LDAP protocol version supported by the client
to 3. (By default, this is set to 2. Extended operations
are part of version 3 of the LDAP protocol.) */
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );
printf( "Resetting version %d to 3.0...\n", version );
version = LDAP_VERSION3;
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );
/* Authenticate to the directory as the Directory Manager */
printf( "Binding to the directory...\n" );
if ( ldap_simple_bind_s( ld, MGR_DN, MGR_PW ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_simple_bind_s" );
ldap_unbind( ld );
return( 1 );
}
/* Initiate the extended operation */
printf( "Initiating the extended operation...\n" );
if ( ( rc = ldap_extended_operation_s( ld, oidrequest, &valrequest, NULL, NULL, &oidresult, &valresult ) ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_extended_operation failed: " );
ldap_unbind( ld );
return( 1 );
}
/* Get the OID and the value from the result returned by the server. */
printf( "Operation successful.\n" );
printf( "\tReturned OID: %s\n", oidresult );
printf( "\tReturned value: %s\n", valresult->bv_val );
/* Disconnect from the server. */
ldap_unbind( ld );
return 0;
}