Table of Contents | Previous | Next | Index

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

ldap_parse_extended_result()

Parses the results of an LDAP extended operation and retrieves the OID and data returned by the server.

This function implements an extension to the LDAP v3 protocol. Extended operations might not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAP v3 extension. See "Determining the Extended Operations Supported" on page 308 to determine if the server supports extended operations.

Syntax

#include <ldap.h> 
int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res, 
   char **retoidp, struct berval **retdatap, int freeit );

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.

res
Pointer to the LDAPMessage structure containing the results of an LDAP operation.

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.

freeit
Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:
0 specifies that the result should not be freed.
A non-zero value specifies that the result should be freed.

Returns

One of the following values, which indicates the result of parsing the server's response (this value does not apply to the LDAP extended operation itself):

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

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

After you call the ldap_extended_operation() function and the ldap_result() function, you can pass the results to the ldap_parse_extended_result() function. ldap_parse_extended_result() parses the server's response to an extended operation.

This function gets the following data from the server's response:

The extended operation OID received from the server is passed back as the retoidp argument.

The data received from the server is passed back in the berval structure as the retdatap argument.

The LDAP result code for the LDAP extended operation is placed in the ld structure. You can get the result code by calling the ldap_get_lderrno() function.

For a list of possible result codes for an LDAP extended operation, see the result code documentation for the

ldap_extended_operation_s()

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.

ldap_parse_extended_result()

Syntax

Parameters

Returns

Description

See Also

ld	Connection handle, which is a pointer to an `LDAP` structure containing information about the connection to the LDAP server.
res	Pointer to the `LDAPMessage` structure containing the results of an LDAP operation.
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.
freeit	Specifies whether or not to free the results of the operation (the `LDAPMessage` structure specified by the `res` argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed.