| Platform SDK: Active Directory, ADSI, and Directory Services |
The LDAPControl structure is used to represent both client-side and server controls.
typedef struct ldapcontrol
{
PWCHAR ldctl_oid;
struct berval ldctl_value;
BOOLEAN ldctl_iscritical;
} LDAPControl, *PLDAPControl;
Effective with LDAP 3, you can extend LDAP operations through the use of controls. Server controls can be sent to the server or returned to the client with any LDAP message. Client controls extend the behavior of the LDAP API on the client side only and are never sent to the server. All supported controls are stored as object identifiers (OIDs) in the Directory Service root. See table below.
The ldctl_iscritical member allows an extended operation to succeed when the server or client does not support the control. If the value of this field is zero, the server and/or client ignores the control if it is not supported and carries out the operation. If the value is nonzero the operation is carried out only if the control is recognized by the server and/or client.
The following table contains the LDAP extended controls and their descriptions.
| LDAP Extended Controls | Description |
|---|---|
| LDAP_SERVER_CROSSDOM_MOVE_TARGET_OID | Cross Domain Move Control facilitates the moving of an object across a domain. It is used as part of the LDAP ModifyDN request.
CrossDomMoveTarget :== Sequence { Name OCTET STRING } The value of Name is the target domain to where the object is being moved. |
| LDAP_SERVER_DIRSYNC_OID | The DirSync control provides sharing of information between dissimilar directories in a mixed-directory environment. See Directory Synchronization Control below for more information. Also see, Polling for Changes Using the DirSync Control. |
| LDAP_SERVER_DOMAIN_SCOPE_OID | Tells the server not to generate referrals. |
| LDAP_SERVER_EXTENDED_DN_OID | Return extended distinguished names |
| LDAP_SERVER_NOTIFICATION_OID | The Server Notification Control registers the client of be notified when changes are made to an object in the Active Directory™. See Server Notification Control below for more information. Also see, Change Notifications in Active Directory. |
| LDAP_SERVER_SD_FLAGS_OID | Security Descriptor Flag
Sequence { Flags INTEGER } |
| LDAP_SERVER_SEARCH_OPTIONS_OID | Server Search Options
This control allows the client to pass flags to control various search behaviors. Sequence { Flags INTEGER } |
| LDAP_SERVER_SHOW_DELETED_OID | The Show Deleted control is used with the extended search functions, such as ldap_search_ext, to view deleted objects along with other objects that match the search filter. When an Active Directory object is deleted, a tombstone of the object is preserved in the tombstone container for a configurable period of time known as the garbage collection interval. To view tombstones using the LDAP functions, you must specify the Show Deleted control. After the garbage collection interval, a tombstone is permanently deleted and can no longer be viewed using this control or otherwise. The RDN of a tombstone is the objectGUID of the deleted object. A tombstone has its isDeleted attribute set to TRUE and contains only a subset of the object's attributes (see the description of searchFlags in Characteristics of Attributes).
This control is part of the SearchRequest and SearchResultDone messages in the control fields of LDAPMessage. The ControlType is the OID. The criticality field is set to True or False. The ControlValue field is empty. |
| LDAP_SERVER_TREE_DELETE_OID | The Tree Delete control deletes an entire subtree as part of the DelRequest message in the control fields of LDAPMessage. See Tree Delete Control below for error message information. |
| LDAP_SERVER_VERIFY_NAME_OID | Tells the Domain Controller which server to verify with an existing distinguished name.
Sequence { Flags INTEGER ServerName OCTET STRING \\Unicode server string } |
| SERVER_SEARCH_FLAG_DOMAIN_SCOPE | Search option flag. No referrals generated. |
| SERVER_SEARCH_FLAG_PHANTOM_ROOT | Search option flag. Search all NCs subordinate to search base. |
This control must be exclusively used with a SearchRequest message and will be 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 will fail and return an UnsupportedCriticalExtension error. Server compatibility is contingent on the server recognizing this control in the SupportControl attribute of the root DSE. For information on Active Directory's Synchronization Controls, see Polling for Changes Using the DirSync Control.
The replication control is part of the SearchResult and SerachResultDone messages in the server controls field of LDAPMessage as follows.
Repl Control ::= Sequence {
controlType OID
controlValue replControlValue
criticality True
}
The ReplControlValue is an Octet String in the SearchRequest message and wraps the BER-endcoded version of the following.
realReplControlValue ::= Sequence {
parentsFirst Integer
maxAttributeCount Integer
Cookie Octet String
}
The ReplControlValue in the SearchResponse message is an Octet String and wraps the BER-encoded version of the following.
realReplControlValue ::= Sequence {
Flag Integer
maxAttributeCount Integer
Cookie Octet String
This control is part of the SearchRequest and SearchResultDone messages in the control fields of LDAPMessage. A client can register up to 5 notification requests with this control.
Notifications are asychronous operations. The server sends SearchEntry responses, that contain the modified objects, to the client using the LDAPMessage ID of the original notification request. Notifications from this control may be canceled using the LDAP Abandon function. For information on Notifications in Active Directory, see Change Notifications in Active Directory.
The ControlType is the OID. The criticality field is True or False. The ControlValue field is empty.
Limitations of the Server Notification Control are as follows.
The filter, (objectclass = *), is the only filter allowed on a persistent search.
Only base and one-level searches are allowed.
Only subtree searches, rooted on a Naming Context, are allowed.
Error Message:
This control must be exclusively used with the DelRequest message and will be ignored if used otherwise. However, if the criticality field is set to True and the control is used with other than the DelRequest message, the request will fail and return an UnsupportedCriticalExtension error. Server authentication of proper user permissions before completing the operation is required. Server compatibility is contingent on the server recognizing this control in the SupportControl attribute of the root DSE.
Error Messages:
If a Tree Delete control request fails, it may be retried with no adverse effects
Windows NT/2000: Requires Windows NT 4.0 SP4 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Winldap.h.