Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide
Chapter 18 Functions

ldap_extended_operation_s()

Sends a request to the server to perform an extended operation synchronously.

Syntax

#include <ldap.h>
int ldap_extended_operation_s( LDAP *ld, const char *requestoid, 
   struct berval *requestdata, LDAPControl **serverctrls, 
   LDAPControl **clientctrls, char **retoidp, 
   struct berval **retdatap );

Parameters

This function has the following parameters:

ld
Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

requestoid
Object identifier (OID) of the extended operation that you want the server to perform.

requestdata
Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation.

serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

retoidp
Pointer to the object identifier (OID) returned by the server after performing the extended operation.
When done, you can free this by calling the ldap_memfree() function.

retdatap
Pointer to the pointer to a berval structure containing the data returned by the server after performing the extended operation.
When done, you can free this by calling the ber_bvfree() function.

Returns

One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.

LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using the LDAP v3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" on page 54.)

The following result codes can be returned by the Netscape Directory Server when processing an LDAP extended operation request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.

LDAP_OPERATIONS_ERROR may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request.

LDAP_PROTOCOL_ERROR if the extended operation request did not comply with the LDAP protocol. The Netscape Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:

The server encountered an error when decoding your client's BER-encoded request.

The extended operation specified by the requestoid argument is not supported by the server.

Depending on the extended operation requested, the Netscape Directory Server may send other result codes in addition to the codes described here. In the Netscape Directory Server, the people deploying the server are responsible for implementing the mechanisms for handling extended operations. Check with your server administrator for additional result codes returned to the client.

Description

The ldap_extended_operation_s() function sends a request to the server to perform an LDAP v3 extended operation synchronously.

The LDAP server must support the extended operation. The Netscape Directory Server 3.0 supports a server plug-in interface that you can use to add support for extended operations to the server. For details, see the Netscape Directory Server 3.0 Programmer's Guide.

For information on determining the extended operations supported by a server, see "Determining the Extended Operations Supported" on page 308.

After processing an LDAP v3 extended operation, an LDAP server can return an object identifier and data in the results. The retoidp and retdatap arguments point to these values.

ldap_extended_operation_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_extended_operation() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions" on page 80.)

See Also

ldap_extended_operation().

Table of Contents | Previous | Next | Index

Last Updated: 10/01/98 17:06:23