NWDSReadSyntaxes(3nw)

Synopsis

   #include <nwnet.h> 
   or 
   #include <nwdsmisc.h> 
   
 
   NWDSCCODE N_API NWDSReadSyntaxes 
     (NWDSContextHandle   context, 
      nuint32             infoType, 
      nbool8              allSyntaxes, 
      pBuf_T              syntaxNames, 
      pnint32             iterationHandle, 
      pBuf_T              syntaxDefs); 

Description

context

(IN) Specifies the Directory context for the request.

infoType

(IN) Specifies the type of information desired (names only, or names and syntax definitions).

allSyntaxes

(IN) Specifies the scope of the request (all or selected syntaxes).

syntaxNames

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

iterationHandle

(IN/OUT) Points to information needed to resume subsequent iterations of NWDSReadSyntaxes.

syntaxDefs

(OUT) Points to a result buffer containing the requested syntax names and/or definitions.

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

infoType, allSyntaxes, and syntaxNames indicate what syntax information is requested.

infoType specifies whether both syntax names and syntax values are requested. The valid values for infoType are as follows:

0

DS_SYNTAX_NAMES returns syntax names only

1

DS_SYNTAX_DEFS returns syntax names and values

If allSyntaxes is TRUE, information about all syntaxes associated with the object is requested and syntaxNames is ignored). If allSyntaxes is FALSE, only the syntaxes specified by syntaxNames are requested.

If allSyntaxes is FALSE and syntaxNames is NULL, no syntax information is returned. infoType is not meaningful.

syntaxNames is a request buffer containing the names of the specific syntaxes whose information is to be returned. It is used to explicitly specify the syntaxes to be returned.

iterationHandle controls the retrieval of results that are larger than the result buffer pointed to by syntaxDefs.

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

When NWDSReadSyntaxes 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 NWDSReadSyntaxes 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.

The level of granularity for partial results is an individual syntax value of a value set. If a value set is split across two or more NWDSReadSyntaxes results, the syntax name of the current value set is repeated in each result.

syntaxDefs points to a result buffer receiving the requested information. This buffer contains either a list of syntax names or a sequence of syntax name and value sets, depending upon the value of infoType.

Read results from the buffer by calling NWDSGetSyntaxCount, and NWDSGetSyntaxDef.

The results of NWDSReadSyntaxes are not ordered, meaning the syntaxes might not be stored in the result buffer in alphabetical order.

To retrieve names and definitions for all syntaxes in the Directory Schema, use the following steps:

1. Allocate memory for the result buffer by calling NWDSAllocBuf. (This buffer does not need to be initializes, since it is a result buffer.)

2. Set the contents of the iteration handle to NO_MORE_ITERATIONS.

3. Call NWDSReadSyntaxes with infoType=DS_SYNTAX_DEFS, allSyntaxes=TRUE, and syntaxNames=NULL.

4. Determine the number of syntax definitions in the result buffer by calling NWDSGetSyntaxCount.

5. For each syntax in the result buffer, retrieve the syntax name and definition by calling NWDSGetSyntaxDef.

6. If the contents of the iteration handle is not set to NO_MORE_ITERATIONS, loop to step 3. Otherwise, go to step 7.

7. Free the result buffer by calling NWDSFreeBuf.

If both syntax names and values are stored in the buffer, the names and values must be pulled from the buffer. If both names and values are requested and names only are extracted, erroneous information results.

To retrieve all information about specific syntaxes in the Directory Schema, use the following steps:

1. Allocate memory for the request buffer by calling NWDSAllocBuf.

2. Initialize the request buffer for a DSV_READ_SYNTAXES operation by calling NWDSInitBuf.

3. For each syntax whose information you want to retrieve, store the syntax's name in the request buffer by calling NWDSPutSyntaxName.

4. Allocate memory for the result buffer by calling NWDSAllocBuf. (This buffer does not need to be initialized since it is a result buffer.)

5. Set the contents of the iteration handle to NO_MORE_ITERATIONS.

6. Call NWDSReadSyntaxes with infoType=DS_SYNTAX_DEFS, allSyntaxes=FALSE, and syntaxNames=the address of the request buffer.

7. Determine the number of syntax definitions in the result buffer by calling NWDSGetSyntaxCount.

8. For each syntax in the buffer, retrieve the syntax name and definition by calling NWDSGetSyntaxDef.

9. If the contents of the iteration handle is not set to NO_MORE_ITERATIONS, loop to step 6. Otherwise, go to step 10.

10. Free the request buffer by calling NWDSFreeBuf.

11. Free the result buffer by calling NWDSFreeBuf.

Services

Directory

NCP calls