Returns information about the references of the specified object.
#include <nwnet.h>
or
#include <nwdsdsa.h>
N_EXTERN_LIBRARY (NWDSCCODE) NWDSReadReferences (
NWDSContextHandle context,
pnstr8 serverName,
pnstr8 objectName,
nuint32 infoType,
nbool8 allAttrs,
pBuf_T attrNames,
uint32 timeFilter,
pnint_ptr iterationHandle,
pBuf_T objectInfo);
uses netwin32
Function NWDSReadReferences
(context : NWDSContextHandle;
serverName : pnstr8;
objectName : pnstr8;
infoType : nuint32;
allAttrs : nbool8;
attrNames : pBuf_T;
timeFilter : nuint32;
iterationHandle : pnint_ptr;
objectInfo : pBuf_T
) : NWDSCCODE;
(IN) Specifies the NDS context for the request.
(IN) Points to the server name to read from.
(IN) Points to the object name whose reference information is to be read.
(IN) Specifies the type of information to be returned (see Section 5.16, Information Types for Search and Read).
(IN) Specifies the scope of the request.
(IN) Points to a request buffer containing the names of attributes whose information is to be returned. This can be NULL.
(IN) Specifies the attribute modification time to be used as a filter. This parameter must be specified and cannot be NULL.
(IN/OUT) Points to information necessary to resume subsequent calls to NWDSReadReferences. This should be initially set to NO_MORE_ITERATIONS.
(OUT) Points to a result buffer containing the requested attribute names or attribute names and values. This parameter can be NULL.
These are common return values.
|
0x0000 0000 |
SUCCESSFUL |
|
0xFE0D |
UNI_NO_OFFSET_DEFAULT |
|
0xFE0F |
UNI_HANDLE_MISMATCH |
|
0xFE10 |
UNI_HANDLE_BAD |
|
0xFEB5 |
ERR_NULL_POINTER |
|
0xFEBB |
ERR_INVALID_ATTR_SYNTAX |
|
0xFEBD |
ERR_BUFFER_ZERO_LENGTH |
|
0xFEBE |
ERR_INVALID_HANDLE |
|
0xFEBF |
ERR_UNABLE_TO_MATCH |
|
0xFED1 |
ERR_BAD_CONTEXT |
|
0xFED3 |
ERR_NOT_ENOUGH_MEMORY |
|
nonzero value |
Nonzero values indicate errors. See |
The NWDSReadReference function returns information about objects that are referencing a specified object on a specified server. The objectName parameter specifies the object, for example object X, that exists on the server. The function returns information about the objects, for example objects Y and Z, that are listed in the Reference attribute of object X. Information about each object listed in the Reference attribute is returned in the objectInfo buffer.
This function reads the Reference attribute of the object. Entires are added to this attribute when the object is referenced in an ACL of another object or the object is added to a list attribute. For example, User objects can belong to Group objects which have a Member attribute. When a User is added to just an attribute, the Group is added to the User's Reference attribute.
The infoType, allAttrs, and attrNames parameters indicate what attribute information to return concerning the reference entries.
If allAttrs is TRUE, information about all attributes associated 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 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 NWDSReadReferences 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 attributes to be returned. For more information, see Preparing eDirectory Output Buffers.
The information in the result buffer depends on infoType. To read the information in the buffer, first call NWDSGetObjectCount. For more information, see Retrieving Results from eDirectory Output Buffers.
The iterationHandle parameter controls retrieval of read results larger than the result buffer pointed to by objectInfo. Before the initial call to NWDSReadReferences, set the iterationHandle parameter to NO_MORE_ITERATIONS.
If the result buffer holds the complete results when NWDSReadReferences 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 NWDSReadReferences to obtain further portions of the results. When the results are completely retrieved, iterationHandle 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_REFERENCES 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 NWDSReadReferences results, the attribute name is repeated in each result.
The results of NWDSReadReferences are not ordered and might not be returned in alphabetical order.
If infoType is set to return both attribute names and values, you cannot remove only the names from the result buffer. You must remove the information in the correct order of the attribute name first and then all of the values associated with the attribute. The next attribute name and its values can then be removed. Otherwise, NWDSGetAttrName will return erroneous information.