NWDSRead(3nw)

NWDSRead -- reads values from one or more of the specified object's attributes

Synopsis

#include <nwnet.h> or #include <nwdsdsa.h>

NWDSCCODE N_API NWDSRead (NWDSContextHandle context, pnstr8 object, nuint32 infoType, nbool8 allAttrs, pBuf_T attrNames, pnint32 iterationHandle, pBuf_T objectInfo);

Description

The parameters are as follows:

context

(IN) Specifies the Directory context for the request.

object

(IN) Points to the name of the object whose information is to be read.

infoType

(IN) Specifies the type of information desired:

0: DS_ATTRIBUTE_NAMES
1: DS_ATTRIBUTE_VALES
2: DS_EFFECTIVE_PRIVILEGES

allAttrs

(IN) Specifies the scope of the request. If TRUE, information concerning all attributes is requested; if FALSE, information concerning only attributes named in attrNames is requested.

attrNames

(IN) Points to a buffer containing the names of the object's attributes for which information is to be returned.

iterationHandle

(IN/OUT) Points to information needed to resume subsequent iterations of NWDSRead.

objectInfo

(OUT) Points to a buffer receiving the requested attribute names and/or values.

Return values

0x0000: SUCCESSFUL
Negative Value: Negative values indicate errors. For errors returned by Directory Services, see ``Directory Services OS Errors'' (-001 to -255), ``Directory Services Client Library Errors'' (-301 to -399), or ``Directory Services Agent in the Server Errors'' (-601 to -699).

Notices

infoType, allAttrs, and attrNames indicate what attribute information is requested.

If allAttrs is TRUE, information about all attributes associated with the object is requested and attrNames is ignored (in which case, pass in a NULL for attrNames). If allAttrs is FALSE, only the attributes specified by the request buffer pointed to by attrNames are requested.

If allAttrs is FALSE and attrNames is NULL, no attribute information is returned; and infoType is not meaningful. In this case, the return value of NWDSRead can determine whether the specified object exists (verifying the object's distinguished name), or whether access to the object is allowed.

The request buffer pointed to by attrNames explicitly specifies the attribute to be returned. If allAttrs is TRUE, attrNames can be NULL (as mentioned above).

The result buffer pointed to by objectInfo received the requested information. This result buffer either contains a list of attribute names or a sequence of attribute-name and attribute-value sets. The type of information returned depends on infoType (as mentioned above).

iterationHandle controls retrieval of lists results larger than the result buffer pointed to by attrNames.

Before the initial call to NWDSListAttrsEffectiveRights, set the contents of the iteration handle pointed to by iterationHandle to NO_MORE_ITERATIONS.

If the result buffer hold the complete results when NWDSRead returns from its initial call, the location pointed to by iterationHandle is set to NO_MORE_ITERATIONS. If the iteration handle is not set to NO_MORE_ITERATIONS, use the iteration handle for subsequent calls to NWDSRead in order to obtain further portions of the results. When the results are completely retrieved, the contents of the iteration handle will be set to NO_MORE_ITERATIONS.

To end the Read operation before the complete results have been retrieved, call NWDSCloseIteration with a value of DSV_READ to free memory and states associated with the Read operation.

To read values from an object's attributes, follow these steps:

Allocate the result buffer by calling NWDSAllocBuf. This buffer does not need to be initialized since it is a result buffer.
If you are requesting information for all attributes, skip to step 6. Otherwise, complete steps 3 through 5.
Allocate a request buffer by calling NWDSAllocBuf.
Initialize the request buffer for a DSV_READ operation by calling NWDSInitBuf.
Store the desired attribute names one-by-one in the buffer by calling NWDSPutAttrName once for each attribute name.
Set the iteration handle to NO_MORE_ITERATIONS.
Call NWDSList.
Determine the number of attributes in the result buffer by calling NWDSGetAttrCount.
Retrieve the name of the current attribute in the result buffer and the count of the number of attribute values following the name by calling NWDSGetAttrName.
Determine the size of the attribute by calling NWDSComputeAttrValSize, and allocate a contiguous block of memory of that size.
Read the attribute values from the buffer one-by-one by calling NWDSGetAttrVal. For single-valued attributes, call NWDSGetAttrVal only once. For multi-valued attributes, call NWDSGetAttrVal for each of the values.
Free the memory that was allocated in step 10.
If all of the attribute information has not been removed from the result buffer, loop to step 9 to retrieve the name of the next attribute from the result buffer. Keep looping until all attribute names and values have been removed from the buffer.
If the iteration handle has not been set to NO_MORE_ITERATIONS, loop to step 7. Otherwise, go to step 15.
Free the request buffer by calling NWDSFreeBuf.
Free the result buffer by calling NWDSFreeBuf.

The results of NWDSRead are not ordered and might not appear in alphabetical order.

If allAttrs is set to DS_ATTRIBUTE_VALUES, specifying the Read operation should return both attribute names and values, you cannot remove only names from the buffer. You must remove the information in the correct order of attribute name first, then all of the values associated with the attribute. Then you must remove the next attribute name and its values and so on. Otherwise, NWDSGetAttrName will return erroneous information.

Services

NCP calls

0x2222 23 17: Get File Server Information
0x2222 23 22: Get Station's Logged Info (old)
0x2222 23 28: Get Station's Logged Info
0x2222 104 01: Ping for NDS NCP
0x2222 104 02: Send NDS Fragmented Request/Reply

References

NWDSReadObjectInfo(3nw)