3.1.1.3.4.1.3 LDAP_SERVER_DIRSYNC_OID
The LDAP_SERVER_DIRSYNC_OID control is used with an LDAP search operation to retrieve the changes made to objects since a previous search with an LDAP_SERVER_DIRSYNC_OID control was performed. The LDAP_SERVER_DIRSYNC_OID control can only be used to monitor for changes across an entire NC replica, not a subtree within an NC replica.
When sending this control to the DC, the controlValue field is set to the BER encoding of the following ASN.1 structure.
-
DirSyncRequestValue ::= SEQUENCE { Flags INTEGER MaxBytes INTEGER Cookie OCTET STRING }
The Flags value has the following format presented in big-endian byte order. X denotes unused bits set to 0 by the client and ignored by the server.
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
I |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
P |
X |
A |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
O |
The Flags value is a combination of zero or more bit flags from the following table, and is used to specify additional behaviors for the LDAP_SERVER_DIRSYNC_OID control.
|
Bit flag name and value |
Description |
|---|---|
|
LDAP_DIRSYNC_OBJECT_SECURITY (OS) 0x00000001 |
Windows Server 2003 operating system and later: If this flag is present, the client can only view objects and attributes that are otherwise accessible to the client. If this flag is not present, the server checks if the client has access rights to read the changes in the NC. Windows 2000 operating system: Not supported. |
|
LDAP_DIRSYNC_ANCESTORS_FIRST_ORDER (AFO) 0x00000800 |
The server returns parent objects before child objects. |
|
LDAP_DIRSYNC_PUBLIC_DATA_ONLY (PDO) 0x00002000 |
Windows Server 2003 and later: This flag can optionally be passed to the DC, but it has no effect. Windows 2000: Not supported. |
|
LDAP_DIRSYNC_INCREMENTAL_VALUES (IV) 0x80000000 |
Windows Server 2003 and later: If this flag is not present, all of the values, up to a server-specified limit, in a multivalued attribute are returned when any value changes. If this flag is present, only the changed values are returned, provided the attribute is a forward link value. Windows 2000: Not supported. |
MaxBytes specifies the maximum number of bytes to return in the reply message.
The minimum value for MaxBytes is 0x100000. When a lower value is specified, the value is ignored and the maximum number of bytes in the reply message is 0x100000.
The maximum value for MaxBytes is determined by the size, in bytes, of a response with the maximum number of objects that can be returned in a single search as specified by the MaxPageSize policy, section 3.1.1.3.4.6. When a higher value is specified, the value is ignored and the maximum number of bytes in the reply message is the size, in bytes, of a response with the MaxPageSize number of objects.
Cookie is an opaque value that was returned by the DC on a previous search request that included the LDAP_SERVER_DIRSYNC_OID control. The contents of Cookie are defined by the server and cannot be interpreted by the client. A search request with the LDAP_SERVER_DIRSYNC_OID control attached will return the changes made to objects since the point in time when the previous search request, which returned the value of Cookie that is being used in the current search request, took place. If there was no previous LDAP_SERVER_DIRSYNC_OID search request, Cookie is NULL, in which case the search will return all objects that satisfy the search request, along with a value of Cookie to use for the next LDAP_SERVER_DIRSYNC_OID search request.
If the base of the search is not the root of an NC, and the LDAP_DIRSYNC_OBJECT_SECURITY bit in the Flags field is not set, the server will return the error insufficientAccessRights / ERROR_DS_DRA_ACCESS_DENIED. If the LDAP_DIRSYNC_OBJECT_SECURITY bit in the Flags field is set, the server will return the error unwillingToPerform / <unrestricted>. If the search scope is not subtree scope, the server will treat the search as if subtree scope was specified.
Any valid LDAP search filter can be specified.
Any attributes can be requested in the search. Only those objects for which these attributes have been created or modified since the time represented by Cookie will be considered for inclusion in the search.
If the list of requested attributes contains an asterisk (*) plus some attribute, then the asterisk is ignored. That is, the list is effectively equal to the list with only the attributes explicitly requested.
The search results MUST always contain the objectGUID and instanceType attributes of each object, even if those attributes were not specified in the search request.
When the server receives a search request with the LDAP_SERVER_DIRSYNC_OID control attached to it, it includes a response control in the search response. The controlType field of the returned Control structure is set to the OID of the LDAP_SERVER_DIRSYNC_OID control, and the controlValue is the BER encoding of the following ASN.1 structure.
-
DirSyncResponseValue ::= SEQUENCE { MoreResults INTEGER unused INTEGER CookieServer OCTET STRING }
The structure of the controlValue in the response control is the same as the structure of the controlValue in the request control, but the fields are interpreted differently. MoreResults is nonzero if there are more changes to retrieve, unused is not used, and CookieServer is the value to be used for Cookie in the next LDAP_SERVER_DIRSYNC_OID control sent in a search request to the server to retrieve more changes.
Further details about how this control is processed are described in the pseudocode for the ProcessDirSyncSearchRequest procedure in [MS-DRSR] section 5.115.3.