LDAP_SERVER_ASQ_OID

The LDAP_SERVER_ASQ_OID control is used with an extended LDAP search function to force the query to be based on a specific DN-valued attribute. Only one source attribute can be specified with this control and the search request is limited to base object scoped queries.

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

PWCHAR ldctl_oid = LDAP_SERVER_ASQ_OID;
struct berval ldctl_value;
BOOLEAN ldctl_iscritical;

Members

ldctl_oid

A pointer to a wide, null-terminated string, LDAP_SERVER_ASQ_OID, which is defined as "1.2.840.113556.1.4.1504".

ldctl_value

Specifies the DN name of the desired attribute used to base the search query on. In the berval structure, set bv_val to a pointer to a BER-encoded sequence containing the attribute's DN name in UTF-8 format, and set bv_len to the length of the sequence. For more information, see the Remarks section of this topic.

When this control is returned by the server, the berval structure contains a BER-encoded enumeration that indicates the status of the search results. For more information, see the Remarks section of this topic.

ldctl_iscritical

Can be TRUE or FALSE depending on whether the search results call is critical to your application.

Remarks

The Attribute Scoped Query (ASQ) control is used with the extended search functions, such as ldap_search_ext, to set the search base to the specified attribute. 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.

The ldctl_value field in the searchRequest message is set to the following BER-encoded sequence:

Sequence {
  sourceAttribute   OCTET STRING
}

The ber_printf routine is used to create the sequence data. The sourceAttribute field is a UTF-8 string that contains the DN name of the attribute the search request is based on.

The ldctl_value in the SearchResponse message is an Octet String and wraps the BER-encoded version of the following:

Sequence {
  searchResults	ENUM
}

The searchResult enumeration is as listed in the following table.

The search results consist of each value of the multi-value DN-valued attribute returned as a result entry with all of the attributes specified in the attribute list of the search request. If any of the attribute values in the search result are not available on the local DSA, the search results include all of the attributes that are locally available, and the searchResult return value is set to the affectsMultipleDSAs error code to indicate that some data that might be otherwise available is not present in the results.

Note  For more information about using attribute scoped queries with Active Directory servers, see Performing an Attribute Scoped Query.

Requirements

Client: Included in Windows XP.
Server: Included in Windows Server 2003.
Header: Declared in Winldap.h.

See Also

ldap_search_ext, Using Controls, Performing an Attribute Scoped Query