Share via


LDAP_SERVER_SEARCH_OPTIONS_OID control code

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 enables the application to specify various search flags. In the berval structure, set bv_val to a pointer to the sequence that contains the flag data and set bv_len to the length of the sequence. For more information, see the Remarks section.

ldctl_iscritical

Can be TRUE or FALSE depending on whether the search call is critical to the operation.

Remarks

The Search Options control enables 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 bit flags listed in the following table.

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 NCs held on the DC that are subordinate than the search base. This also enables search bases like dc=com, which would cause the server to search all of the NCs that it holds.

The following example shows how to 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 and 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;

// Cleanup temporary berval.
ber_bvfree(pldctrl_value);

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

Requirements

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

See also

Data Structures

LDAPMessage

Using Controls