Reads values from one or more of the specified object’s attributes.
#include <nwnet.h>
or
#include <nwdsdsa.h>
N_EXTERN_LIBRARY (NWDSCCODE) NWDSRead (
NWDSContextHandle context,
pnstr8 object,
nuint32 infoType,
nbool8 allAttrs,
pBuf_T attrNames,
pnint_ptr iterationHandle,
pBuf_T objectInfo);
uses netwin32
Function NWDSRead
(context : NWDSContextHandle;
object : pnstr8;
infoType : nuint32;
allAttrs : nbool8;
attrNames : pBuf_T;
iterationHandle : pnint_ptr;
objectInfo : pBuf_T
) : NWDSCCODE;
(IN) Specifies the NDS context for the request.
(IN) Points to the name of the object whose information is to be read.
(IN) Specifies the type of information desired (see Section 5.16, Information Types for Search and Read).
(IN) Specifies the scope of the request:
(IN) Points to a buffer containing the names of the object’s attributes for which information is to be returned.
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSRead.
(OUT) Points to a buffer receiving the requested attribute names and/or values.
|
0x0000 0000 |
SUCCESSFUL |
|
nonzero value |
Nonzero values indicate errors. See |
The infoType, allAttrs, and attrNames parameters indicate what attribute information is requested.
If NWDSRead is called using infoTypes DS_VALUE_INFO (3) or DS_ABBREVIATED_VALUE (4), eDirectory returns the attribute value flags and modification timestamp. If the attribute value has been deleted, but not synchronized, eDirectory can return a value flag of DS_NOT_PRESENT (value not present) and no data. In this case, the attribute value length is zero. NWDSComputeAttrValSize returns the correct size of 0, and the application should not call NWDSGetAttrVal to retrieve the data because there is no data to retrieve.
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. Initialize the buffer with a value of DSV_READ. For more information on setting up this buffer, see Reading Attributes of eDirectory Objects.
The iterationHandle parameter controls retrieval of list results larger than the result buffer pointed to by attrNames.
Before the initial call to NWDSRead, set the iterationHandle parameter to NO_MORE_ITERATIONS.
If the result buffer holds 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 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.
NOTE:On large networks, iterative processes, such as NWDSRead, might take a long time to complete. For example, listing all of the User objects on a corporate network might be too time consuming. Developers should use NWDSCloseIteration to allow users of their applications to abort an iterative process that is taking too long to complete.
To end the read operation before complete results have been retrieved, call NWDSCloseIteration with a value of DSV_READ to free memory and states associated with the read operation.