LDAP_SERVER_DIRSYNC_OID control code

The LDAP_SERVER_DIRSYNC_OID control enables an application to search the directory for objects changed from a previous state. It is also used with the extended LDAP search functions such as ldap_search_ext.

To use this control, set the members of the LDAPControl structure as follows:

PWCHAR ldctl_oid = LDAP_SERVER_DIRSYNC_OID;
struct berval ldctl_value;
BOOLEAN ldctl_iscritical = TRUE;

Members

ldctl_oid

LDAP_SERVER_DIRSYNC_OID, defined as "1.2.840.113556.1.4.841".

ldctl_value

Specifies a BER-encoded sequence of parameters that enables the application to limit the amount of data to be returned in a single call. The sequence also includes a "cookie" used for subsequent search calls. In the berval structure, set bv_val to a pointer to the sequence that contains the control and cookie data and set bv_len to the length of the sequence. For more information, see the Remarks section.

ldctl_iscritical

TRUE

Remarks

The LDAP_SERVER_DIRSYNC_OID control is used with the extended search functions, such as ldap_search_ext, to search a directory for objects changed since a previous request. This control must be exclusively used with a SearchRequest message and is ignored if used otherwise. However, if the criticality field is set to TRUE and the control is used with other than the SearchRequest message, the request fails and returns an UnsupportedCriticalExtension error.

On the first call to an extended LDAP search function that uses this control, the ldctl_value is a BER-encoded version of the following.

Sequence {
  Flags                INTEGER
  maxAttributeCount    INTEGER
  Cookie               OCTET STRING
}

Flags

Contains optional flags for use with the LDAP_SERVER_DIRSYNC_OID control. This can be zero or a combination of one or more of the values listed in the following list.

Value	Description
LDAP_DIRSYNC_OBJECT_SECURITY	**Windows Server 2003: **
LDAP_DIRSYNC_ANCESTORS_FIRST_ORDER	Return parent objects before child objects, when parent objects would otherwise appear later in the replication stream.
LDAP_DIRSYNC_PUBLIC_DATA_ONLY	Do not return private data in the search results.
LDAP_DIRSYNC_INCREMENTAL_VALUES	Windows Server 2003: If this flag is not present, all of the values, up to a server-specified limit, in a multi-valued attribute are returned when any value changes. If this flag is present, only the changed values are returned.

maxAttributeCount

Specifies the maximum number of bytes to return, subject to server limits.

The minimum value accepted in this field is 0x100000. This minimum value is used if a lower value is specified in this field.

The maximum value is the number of bytes it takes to accommodate the number of objects specified in MaxPageSize setting in the lDAPAdminLimits attribute, which is 1000 objects by default. This maximum limit is used if a larger value is specified in this field.

Cookie

An opaque Octet String that is implementation specific. It is updated during each SearchRequest by the directory and enables the DirSync control to incrementally read changes from the directory. Initial creation of this control should be a NULL string of 0 length.

The result of a search with the LDAP_SERVER_DIRSYNC_OID control is an LDAPControl structure that contains a BER-encoded version of the following data in the ldctl_value member.

Sequence {
  Flag                INTEGER
  maxAttributeCount   INTEGER
  Cookie              OCTET STRING
}

Flag

Contains a nonzero value if there is more data to retrieve or zero if there is no more data to retrieve. If this member contains a nonzero value, a subsequent search should be performed with the Cookie of this data to retrieve the next block of results.

maxAttributeCount

Specifies the maximum number of bytes to return, subject to server limits.

The minimum value accepted in this field is 0x100000. This minimum value is used if a lower value is specified in this field.

The maximum value is the number of bytes it takes to accommodate the number of objects specified in MaxPageSize setting in the lDAPAdminLimits attribute, which is 1000 objects by default. This maximum limit is used if a larger value is specified in this field.

Cookie

Contain an opaque Octet string that is implementation specific. This value is returned by the server for use in subsequent searches by the client.

Subsequent calls to the LDAP extended search functions should pass the returned Cookie data back in order to return any additional search results as indicated by the Flag data.

For more information about specific access rights required to use this control with an Active Directory server, see Polling_for_Changes_Using_the_DirSync_Control.

Requirements

Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Header	Ntldap.h