NWDSReadReferences(3nw)


NWDSReadReferences -- searches all of the replicas on a particular server and returns any objects that contain attributes that reference the specified object

Synopsis

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

NWDSCCODE N_API NWDSReadReferences (NWDSContextHandle context, pnstr8 serverName, pnstr8 objectName, nuint32 infoType, nbool8 allAttrs, pBuf_T attrNames, uint32 timeFilter, pnint32 iterationHandle, pBuf_T objectInfo);

Description

The parameters are as follows:

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

serverName
(IN) Points to the server name to read from.

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

infoType
(IN) Specifies the type of information to be returned.

allAttrs
(IN) Specifies the scope of the request.

attrNames
(IN) Points to an request buffer containing the names of attributes whose information is to be returned. This can be NULL.

timeFilter
(IN) Specifies the attribute modification time to be used as a filter. This parameter must be specified and cannot be NULL.

iterationHandle
(IN/OUT) Points to information necessary to resume subsequent calls to NWDSReadReferences. This should be initially set to NO_MORE_ITERATIONS.

objectInfo
(OUT) Points to a result buffer containing the requested attribute names or attribute names and values. This parameter can be NULL.

Return values

0x0000
SUCCESSFUL

0xFFFFFE0D
UNI_NO_OFFSET_DEFAULT

N0xFFFFFE0F
UNI_HANDLE_MISMATCH

0xFFFFFE10
UNI_HANDLE_BAD

0xFFFFFEB5
ERR_NULL_POINTER

0xFFFFFEBB
ERR_INVALID_ATTR_SYNTAX

0xFFFFFEBD
ERR_BUFFER_ZERO_LENGTH

0xFFFFFEBE
ERR_INVALID_HANDLE

0x0000FEBF
ERR_UNABLE_TO_MATCH

0x0000FED1
ERR_BAD_CONTEXT

0x0000FED3
ERR_NOT_ENOUGH_MEMORY

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.

infoType specifies whether both attribute names and values are requested:

0
DS_ATTRIBUTE_NAME defines attribute names only.

1
DS_ATTRIBUTE_VALUES defines both attribute names and values.

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. infoType is not meaningful. In this case, the return value of NWDSReadReferences 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 to be returned. This request buffer is prepared by using the following steps:

  1. Allocate the request 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 request buffer by calling NWDSPutAttrName once for each attribute name.

The result buffer pointed to by objectInfo receives the requested information. This 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 value sets. The type of information returned depends on infoType. The results must be read from the result buffer 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 from the buffer one-by-one by calling NWDSGetAttrVal. For single-valued attributes, you will call NWDSGetAttrVal only once. For multi-valued attributes, you will call NWDSGetAttrVal once for each value.

  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 buffer.

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

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

When NWDSReadReferences returns from its initial call, if 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 NWDSReadReferences in order 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 allAttrs is set to DS_ATTRIBUTE_VALUES, specifying the Read operation should 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, then all of the values associated with the attribute. Then remove the next attribute name and its values. Otherwise, NWDSGetAttrName will return erroneous information.

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

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