LDAP_PAGED_RESULT_OID_STRING control code
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
}
The following table lists the sequence fields.
| Sequence data | Description |
|---|---|
| pageSize |
Specifies the requested page size from the client, or the estimated result set size returned by the server. |
| Cookie |
An opaque Octet String that is implementation specific. Initial creation of this control should be a NULL string of 0 length. |
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
| Minimum supported client |
Windows Vista |
| Minimum supported server |
Windows Server 2008 |
| Header |
|