LDAP_PAGED_RESULT_OID_STRING

The LDAP_PAGED_RESULT_OID_STRING control is used internally with the LDAP paged search API functions to instruct the server to return the results of a search request in smaller, more manageable packets rather than in one large block.

To use this control, format the control contents using the ldap_create_page_control function, or set the members of the LDAPControl structure as follows.

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

Members

ldctl_oid

LDAP_PAGED_RESULT_OID_STRING, which is defined as "1.2.840.113556.1.4.319"

ldctl_value

Specifies a BER-encoded sequence of parameters that enables the application to limit the amount of data returned in a single call. The sequence also includes a "cookie" used for subsequent paged results search calls. In the berval structure, set bv_val to a pointer to the sequence containing the control and cookie 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 paging the results is critical to the application.

Remarks

An important benefit of using the paged control is that it enables applications to receive result sets which contain more entries than permitted by server defined limits. For example, by default, Active Directory limits search results to a maximum of 1000 entries. Using the paged control with a paged size of < 1000, an application can retrieve the complete set of results (more than 1000) in packet sizes that do not exceed the server limit.

Client applications should use the LDAP API functions, such as ldap_create_page_control, ldap_search_init_page, ldap_parse_result, ldap_parse_page_control, and so on, instead of attempting to create and manipulate this control directly.

If the value of the ldctl_value sequence argument is required to be created manually, the sequence data is formatted as follows.

Sequence {
  pageSize	 INTEGER
  Cookie	 OCTET STRING
}

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

LDAPControl lControl;
BerElement *pber = NULL;
PBERVAL pldctrl_value = NULL;
ber_int_t iPageSize = 250;
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,"{io}",iPageSize,NULL,0);

// 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 an error routine.
}

// Copy the BERVAL data to the LDAPControl structure.
lControl.ldctl_oid = LDAP_PAGED_RESULT_OID_STRING;
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 ready for use in ldap_search_ext()
// or another 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.

See Also

Data Structures, LDAPMessage, Using Controls