Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide
     Chapter 17 Data Types and Structures

LDAPVirtualList

LDAPVirtualList specifies the information that can be used to create a "virtual list view" control. This LDAP v3 control is designed to allow the client to retrieve subsets of search results to display in a "virtual list box".

This is the control with the OID 2.16.840.1.113730.3.4.9 (or LDAP_CONTROL_VLVREQUEST, as defined in ldap.h).

At this point in time, no server supports this control. (The Netscape Directory Server 3.x does not support this control, although future releases of the Directory Server plan to support it.) For information on determining if a server supports this or other LDAP v3 controls, see "Determining If the Server Supports LDAP v3."

A virtual list box is typically a graphical user interface that displays a long list of entries with a few entries visible. End users can display different sections of the list by scrolling up or down.

To display the list of entries, the client usually does not retrieve the entire list of entries from the server. Instead, the client just retrieves the subset of entries to be displayed to the end user.

The virtual list view control provides the means for your client to request and retrieve certain subsets of a long, sorted list of entries. The control specifies the following information:

The currently selected entry can be identified in one of the following ways:

For example, a virtual list view control might specify that you want to retrieve entries 15 through 24 in a list of 100 results with entry 20 being the selected entry. The control uses the following information to specify this:

As another example, a virtual list view control might specify that you want to retrieve a subset of entries that start with the letter "c" or a later letter in the alphabet. The control might specify the following information:

LDAPVirtualList is defined as follows: 

typedef struct ldapvirtuallist {
   unsigned long ldvlist_before_count;
   unsigned long ldvlist_after_count;
   char *ldvlist_attrvalue;
   unsigned long ldvlist_index;
   unsigned long ldvlist_size;
   void *ldvlist_extradata;
} LDAPVirtualList;
The fields in this structure are described below: 

ldvlist_before_count

Number of entries before the selected entry that you want to retrieve. 

ldvlist_after_count

Number of entries after the selected entry that you want to retrieve. 

ldvlist_attrvalue

Specifies the value that you want to find in the list. The selected entry in the list is the first entry that is greater than or equal to this value.

If this field is NULL, the ldvlist_index and ldvlist_size fields are used to determine the selected entry instead. 

ldvlist_index

If the ldvlist_attrvalue field is NULL, specifies the offset or index of the selected entry in the list. This field is used in conjunction with the ldvlist_size field to identify the selected entry. 

ldvlist_size

If the ldvlist_attrvalue field is NULL, specifies the total number tems in the list. This field is used in conjunction with the ldvlist_index field to identify the selected entry. 

ldvlist_extradata

Reserved for application-specific use. Note that this data is not used in the virtual list view control.

After you create an LDAPVirtualList structure and specify values for its fields, you can create the virtual list view control by calling the ldap_create_virtuallist_control() function.

You can pass this control and a server-side sorting control (created by calling the ldap_create_sort_keylist() function and the ldap_create_sort_control() function) to the ldap_search_ext() or ldap_search_ext_s() function.

To get the virtual list view response control sent back from the server, call the ldap_parse_result() function to get the list of controls returned by the server, then call the ldap_parse_virtuallist_control() function to retrieve information from the control.

For more information about this control, see "Using the Virtual List View Control."

Table of Contents | Previous | Next | Index

Last Updated: 10/01/98 17:05:28