Table of Contents | Previous | Next | Index

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

ldap_abandon_ext()

Cancels ("abandons") an asynchronous LDAP operation that is in progress. For example, you can cancel an LDAP search operation that you started with ldap_search_ext().

Syntax 

#include <ldap.h>
int ldap_abandon_ext( LDAP *ld, int msgid, 
   LDAPControl **serverctrls, LDAPControl **clientctrls );

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. 

msgid

Message ID of the LDAP operation that you want to cancel. 

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.

Returns

One of the following values:

Description

The ldap_abandon() function cancels ("abandons") an asynchronous LDAP operation that is in progress. For example, if you called ldap_search_ext() to initiate an LDAP search operation on the server, you can call ldap_abandon_ext() to cancel the LDAP search operation.

This function is a new version of the ldap_abandon() function. If you are writing a new LDAP client, you should call this function instead of ldap_abandon().

When you call this function, your LDAP client sends a request to cancel an operation being processed by the LDAP server. To identify the operation to be cancelled, specify the message ID of the operation in the msgid argument.

(When you call an asynchronous function such as ldap_search_ext() and ldap_modify_ext(), the msgidp argument of the function returns a pointer to a message ID that identifies the operation. For example, when you call ldap_search_ext() to start an LDAP search operation on the server, the msgidp argument returns a pointer to a message ID identifying that LDAP search operation.)

When you call ldap_abandon_ext(), the function checks to see if the results of the operation have already been returned. If so, ldap_abandon_ext() deletes the message ID from the queue of pending messages. If the results have not been returned, ldap_abandon_ext() sends a request to abandon the operation on the LDAP server.

Once you cancel an operation, results of the operation will not be returned, even if you subsequently call ldap_result() to try to get the results.

For more information, see "Canceling an Operation in Progress" on page 89.

Example

The following example cancels an ldap_url_search() operation, abandoning the results of the operation. 

LDAP *ld;
char *url = "ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich";
int msgid;
LDAPControl **srvrctrls, **clntctrls;
...
/* Initiate a search operation */
msgid = ldap_url_search( ld, url, 0 );
...
/* Abandon the search operation */
if ( ldap_abandon_ext( ld, msgid, srvrctrls, clntctrls ) 
      != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_abandon" );
   return( 1 );
}
...

See Also

ldap_add_ext(), ldap_compare_ext(), ldap_delete_ext(), ldap_extended_operation(), ldap_modify_ext(), ldap_rename(), ldap_sasl_bind(), ldap_search_ext(), ldap_simple_bind(), ldap_url_search().

Table of Contents | Previous | Next | Index

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