Directory Services

LDAP_SERVER_SEARCH_OPTIONS_OID

The LDAP_SERVER_SEARCH_OPTIONS_OID control is used to pass flags to the server to control various search behaviors.

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

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

Members

ldctl_oid: LDAP_SERVER_SEARCH_OPTIONS_OID, which is defined as "1.2.840.113556.1.4.1340".
ldctl_value: Specifies a BER-encoded sequence of parameters that allows the application to specify various search flags. In the berval structure, set bv_val to a pointer to the sequence containing the flag data (see the following Remarks section), and set bv_len to the length of the sequence.
ldctl_iscritical: Can be TRUE or FALSE depending on whether paging the results is critical to your application.

Remarks

The Search Options control allows the client to pass flags to control various search behaviors. The ldctl_value field is set to the following BER-encoded sequence:

Sequence {
  Flags	INTEGER
}

The ber_printf routine is used to create the sequence data. The flags portion contains the search options to include, and can contain any of the following bit flags:

Sequence Data	description
SERVER_SEARCH_FLAG_DOMAIN_SCOPE	Prevents referrals from being generated when the search results are returned. This performs the same function as the LDAP_SERVER_DOMAIN_SCOPE_OID control.
SERVER_SEARCH_FLAG_PHANTOM_ROOT	Instructs the server to search all NCs that are subordinate to the search base. This will cause the search to be executed over all NC's held on the DC that are subordinate than the search base. This also allows search bases like dc=com, which would cause the server to search all of the NC's that it holds.

This code shows how to manually format the sequence data for the call to an extended LDAP search function.

LDAPControl lControl;
BerElement *pber = NULL;
PBERVAL pldctrl_value = NULL;
ber_int_t iSearchFlags = SERVER_SEARCH_FLAG_DOMAIN_SCOPE;
int success = -1;


// format & encode the SEQUENCE data in a BerElement
pber = ber_alloc_t(LBER_USE_DER);
if(pber==NULL) return BER_ALLOC_FAILURE_CODE;
ber_printf(pber,"{i}",iSearchFlags);

// transfer the encoded data into a BERVAL
success = ber_flatten(pber,&pldctrl_value);
if(success == 0)
	ber_free(pber,1);
else
{
	printf("ber_flatten failed");
	// Call error handler here.
}

// copy the BERVAL data to the LDAPControl structure
lControl.ldctl_oid = LDAP_SERVER_SEARCH_OPTIONS_OID;
lControl.ldctl_iscritical = TRUE;
lControl.ldctl_value.bv_val = new char[pldctrl_value->bv_len];
memcpy(lControl.ldctl_value.bv_val, 
	 pldctrl_value->bv_val, pldctrl_value->bv_len);
lControl.ldctl_value.bv_len = pldctrl_value->bv_len;

// clean up temporary berval
ber_bvfree(pldctrl_value);

// the LDAPControl data is now ready for use in ldap_search_ext()
//   or other call. . . .

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Winldap.h.

LDAP_SERVER_SEARCH_OPTIONS_OID

Members

Remarks

Requirements

See Also