Table of Contents | Previous | Next | Index

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

ldap_create_persistentsearch_control()

Creates a control that allows your client to perform a persistent search of an LDAP v3 server, which allows the search operation to continue without termination until your client abandons the search.

This function implements an extension to the LDAP v3 protocol. Persistent search is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAP v3 extension.

Syntax

#include <ldap.h>
int ldap_create_persistentsearch_control( LDAP *ld, 
   int changetypes, int changesonly, int return_echg_ctls, 
   char ctl_iscritical, LDAPControl **ctrlp );

After you create the control, you can pass it to the LDAP server during a search operation. (Pass the server control when calling the ldap_search_ext() function.) If you specify that you want "entry change notification" controls sent back (that is, if you specify a non-zero value for the return_echg_ctls argument), the server includes controls with each changed entry it sends back.

To retrieve the "entry change notification control" from each entry, call the ldap_get_entry_controls() function. To get data about the changes made to the entry from the control, call the ldap_parse_entrychange_control() function.

When you are done with the search, you can cancel the persistent search by calling the ldap_abandon_ext() function. You should also free the control from memory by calling the ldap_control_free() function.

ld	Connection handle, which is a pointer to an `LDAP` structure containing information about the connection to the LDAP server.
changetypes	Specifies the types of changes that you want to keep track of. This field can have one or more of the following values (you can OR the values together to specify multiple types): `LDAP_CHANGETYPE_ADD` specifies that you want to keep track of entries added to the directory. `LDAP_CHANGETYPE_DELETE` specifies that you want to keep track of entries deleted from the directory. `LDAP_CHANGETYPE_MODIFY` specifies that you want to keep track of entries that are modified. `LDAP_CHANGETYPE_MODDN` specifies that you want to keep track of entries that are renamed. `LDAP_CHANGETYPE_ANY` specifies that you want to keep track of all of the above changes to the directory.
changesonly	Specifies whether or not you want skip the initial search and only get the latest changes as they occur: If non-zero, the initial search is skipped and only entries that have changed after the initial search are returned. If 0, the results of the initial search are returned first.
return_echg_ctls	Specifies whether or not entry change notification controls are included with each entry returned to your client: If non-zero, an entry change notification control is included with each entry. If 0, entry change notification controls are not included with the entries returned from the server.
ctl_iscritical	Specifies whether or not the persistent search control is critical to the search operation: If non-zero, the control is critical to the search operation. If the server does not support persistent searches, the server will return an `LDAP_UNAVAILABLE_CRITICAL_EXTENSION` error. If 0, the control is not critical to the search operation. Even if the server does not support persistent searches, the search operation is still performed.
ctrlp	Pointer to a pointer to an `LDAPControl` structure that will be created by this function. When you are done using this control, you should free it by calling the `ldap_control_free()` function.

ldap_create_persistentsearch_control()

Syntax

Parameters

Returns

Description

See Also