Applications access eDirectory services through functions that might require input and output parameters in a complex variety of data configurations. For example, some functions require input parameters of multiple objects with multiple attributes assigned multiple values. Other functions return parameters that are equally complex.
To accommodate the data requirements of the various functions and to provide a flexible client interface, most eDirectory functions pass input and output parameters through specially defined local buffers. Therefore, an understanding of buffer management is essential to developing eDirectory-aware programs.
In general, buffer management involves the following steps:
Allocate any input and output buffers required by an operation.
Initialize any input buffers.
Place any input parameters that define your operation into the input buffer.
Execute the request.
After the operation is complete, retrieve any results from the output buffer.
Clean up by deallocating buffers you no longer need.
The following sections describe buffer size, initialization, message length, allocation types, required search buffers, and then list the functions used in buffer management.
To allocate an input or output buffer, call NWDSAllocBuf. All input and output buffers are of type Buf_T. You must specify the size of the buffer to allocate. Rather than trying to determine the exact buffer size required for a particular operation, it’s usually more convenient to define a standard buffer length that will be adequate for most operations.
The size of an output buffer affects how the server processes a request. A server will continue adding data to the buffer until the buffer is full or the request is satisfied. Consequently, if you use a very large input buffer, you may wait longer for initial results than if you use a small buffer. At the same time, a larger buffer may require fewer transmissions than a smaller buffer. The DEFAULT_MESSAGE_LEN constant is defined as 4 KB.
Only input buffers (also called request buffers) need to be initialized with an operation type. Output buffers (also called result buffers) do not need to be initialized. Input buffers are used in read and search operations to restrict the operation to a list of classes or attributes. They are also used when creating class or attribute definitions and when adding objects to or modifying objects in the eDirectory tree. See Section 5.3, Buffer Operation Types and Related Functions for a list of operation types for buffer initialization.
Once the buffer is initialized, it is ready to receive data. However, you cannot put data directly into the buffer. eDirectory has a set of specialized functions for placing the data into the input buffer.
The following functions are used to allocate input and output buffers and to initialize the input buffers.
The following functions are used to set up the input or request buffers with the information that limits the scope of the request from all items of a type to the items listed in the request buffer.
The following functions are used to retrieve information from output or result buffers.