NWDSExtSyncRead(3nw)


NWDSExtSyncRead -- reads values from one or more of a Directory object's attributes allowing for restrictions on the attributes modification time

Synopsis

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

NWDSCCODE N_API NWDSExtSyncRead (NWDSContextHandle context, pnstr8 objectName, nuint32 infoType, nbool8 allAttrs, pBuf_T attrNames, pnint32 iterationHandle, pTimeStamp_T timeStamp, pBuf_T objectInfo);

Description

The parameters are as follows:

context
(IN) Specifies the Directory context for the request.

objectName
(IN) Points to the name of the object whose attributes are to be read.

infoType
(IN) Specifies the type of information desired.

allAttrs
(IN) Specifies the scope of the request.

attrNames
(IN) Points to a request buffer containing the attribute names for which information is to be returned.

iterationHandle
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSExtSyncRead. This should be set initially to NO_MORE_ITERATIONS.

timeStamp
(IN) Points to an object-modification time to be used as a filter.

objectInfo
(OUT) Points to a result buffer that receives the attribute names or names and 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

The name specified by objectName is relative to the current name context in the Directory context specified by context.

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

infoType specifies whether both attribute names and attribute values are requested:

0 DS_ATTRIBUTE_NAME defines attribute names only.
1 DS_ATTRIBUTE_VALUES defines both attribute names and attribute values.

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

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

The request buffer pointed to by attrNames explicitly specifies the attributes whose information is to be returned. This buffer is filled out using the following steps:

  1. Allocate the buffer by calling NWDSAllocBuf.

  2. Initialize the buffer for a DSV_READ operation by calling NWDSInitBuf.

  3. Store the attribute names one-by-one in the buffer by calling NWDSPutAttrName.

The timestamp pointed to by timeStamp is used to exclude attributes that have not been modified since a certain time. The timestamp filter limits the attribute list to be those attributes having modification times greater than or equal to the specified time.

When filling out TimeStamp_T, set eventID to zero, replicaNum to zero, and wholeSeconds to the appropriate value.

On return, the result buffer pointed to by objectInfo contains the requested information. This result buffer is allocated by calling NWDSAllocBuf. It is not initialized since it is a result buffer.

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. The results must be read from the result buffer by using the following steps:

  1. Determine the number of attributes in the result buffer by calling NWDSGetAttrCount.

  2. Get the name of the attribute and the count of the number of attribute values following the name by calling NWDSGetAttrName.

  3. Determine the size of the attribute by calling NWDSComputeAttrValSize, and allocate a contiguous block of memory of that size.

  4. Read the attribute values form the buffer one-by-one by calling NWDSGetAttrVal. For single-valued attributes, call NWDSGetAttrVal once. For multi-valued attributes, call NWDSGetAttrVal once for each of the values.

  5. Loop to step 2 to get the name of the next attribute in the result buffer. Keep looping until all attribute names and values have been removed from the result buffer.

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 result 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 remove the next attribute name and its values. Otherwise, NWDSGetAttrName will return erroneous information.

iterationHandle controls retrieval of search results larger than the result buffer pointed to by objectInfo.

Before the inital call to NWDSExtSyncRead, set the contents of the iteration handle pointed to by iterationHandle to NO_MORE_ITERATIONS.

If, when NWDSExtSyncRead returns from its initial call, the result buffer holds the complete results, 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 NWDSExtSyncRead 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.

The level of granularity for partial results is an individual value of an attribute. If an attribute is multivalued and its values are split across two or more NWDSExtSyncRead results, the attribute name is repeated in each result.

The results of NWDSExtSyncRead are not ordered and might not be in alphabetical order.

NWDSExtSyncRead can be useful for detecting changes in an object's attributes. However, NWDSExtSyncRead does not return information about attributes that have been deleted or for which your attribute privileges have changed.

Services

Directory

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

NWDSRead(3nw), NWDSReadObjectInfo(3nw)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.