NWDSGetAttrName(3nw)

Synopsis

   #include <nwnet.h> 
   or 
   #include <nwdsbuft.h> 
   
 
   NWDSCCODE N_API NWDSGetAttrName 
     (NWDSContextHandle   context, 
      pBuf_T              buf, 
      pnstr8              attrName, 
      pnuint32            attrValCount, 
      pnuint32            syntaxID); 

Description

context

(IN) Specifies the Directory context for the request.

buf

(IN) Points to the result buffer being read.

attrName

(OUT) Points to the attribute name whose information is stored at the current position in the result buffer.

attrValCount

(OUT) Points to the number of attribute values following the attribute name in the result buffer. (Multivalued attributes can have more than one value.)

syntaxID

(OUT) Points to the syntax ID identifying the syntax type of the attribute returned in attrName.

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

NWDSGetAttrName is used to retrieve attribute information from a result buffer filled in by NWDSRead, NWDSSearch, or NWDSList.

You must allocate space for the attribute name. The size of the allocated memory is ((MAX_SCHEMA_NAME_CHARS)+1)*sizeof(character size) where character size is 1 for single-byte characters, and 2 for double-byte characters (Unicode is double-byte). One character is used for NULL termination.

The location pointed to by attrValCount is set to specify the number of attribute values associated with the current attribute in the result buffer. If no values are associated with the current attribute, the number will be zero. If the current attribute is a single-valued attribute, the number will be one. If the current attribute is a multi-valued attribute, the number can be zero or more.

The location pointed to by syntaxID receives a value identifying the syntax type of the attribute returned in attrName. This ID is passed as a parameter to subsequent calls to NWDSComputeAttrValSize and NWDSGetAttrVal. The syntax types (such as SYN_CI_STRING) are enumerated in NWDSDEFS.H.

If the function filling in the result buffer was called specifying that the results contain only names, NWDSGetAttrName will not place a value into the locations pointed to by attrValCount and syntaxID. In this case, attrValCount and syntaxID can be NULL.

The steps for removing the attribute information from the result buffer are as follows:

1. Determine the number of attributes whose information is stored in the result buffer by calling NWDSGetAttrCount.

2. Retrieve the name of the current attribute and the count of values associated with the attribute by calling NWDSGetAttrName.

3. Determine the size of memory needed to store the current attribute value by calling NWDSComputeAttrValSize.

4. Retrieve the value by calling NWDSGetAttrVal.

5. After storing the attribute value, free the memory used to retrieve the value by calling a function such as free.

6. If the current attribute is a multivalued attribute and more attribute values remain for current attribute, loop to step 3. Otherwise, go to step 7.

7. Loop to step 2 until all the names and values for the attributes has been read.

Services

Directory

NCP calls

References