NWDSGetContext(3nw)

NWDSGetContext -- returns value of a Directory context variable

Synopsis

   #include <nwnet.h> 
   or 
   #include <nwdsdc.h> 
    
   NWDSCCODE N_API NWDSGetContext 
     (NWDSContextHandle   context, 
      nint                key, 
      nptr                value);

Description

The parameters are as follows:

context: (IN) Specifies the Directory context to be queried.
key: (IN) Specifies the context variable to be retrieved.
value: (OUT) Points to the value of the context variable.

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

Applications do not have direct access to the Directory context variables. To determine the settings of the context variables, applications must call NWDSGetContext, using a context key identifying which variable's information to retrieve.

The context key is identified by key. The following keys are defined in NWDSDC.H:

Key Name Value Description

DCK_FLAGS 1 Bit definitions

DCK_CONFIDENCE 2 Definitions:

0
DCV_LOW_CONF
1
DCV_MED_CONF
2
DCV_HIGH_CONF

DCK_NAME_CONTEXT 3 Character string array

DCK_TRANSPORT_TYPE 4 Not currently in use

DCK_REFERRAL_SCOPE 5 Definitions:

0
DCV_ANY_SCOPE
1
DCV_COUNTRY_SCOPE
2
DCV_ORGANIZATION_SCOPE
3
DCV_LOCAL_SCOPE

DCK_LAST_CONNECTION 8 Connection handle

DCK_TREE_NAME 11 Character string array

Key Name	Value	Description
DCK_FLAGS	1	Bit definitions
DCK_CONFIDENCE	2	Definitions: 0 DCV_LOW_CONF 1 DCV_MED_CONF 2 DCV_HIGH_CONF
DCK_NAME_CONTEXT	3	Character string array
DCK_TRANSPORT_TYPE	4	Not currently in use
DCK_REFERRAL_SCOPE	5	Definitions: 0 DCV_ANY_SCOPE 1 DCV_COUNTRY_SCOPE 2 DCV_ORGANIZATION_SCOPE 3 DCV_LOCAL_SCOPE
DCK_LAST_CONNECTION	8	Connection handle
DCK_TREE_NAME	11	Character string array

 
 ------------------------------------------------------------- 
| Key Name           |  Value|  Description                  | 
|--------------------|-------|-------------------------------| 
| DCK_FLAGS          |  1    |  Bit definitions              | 
|--------------------|-------|-------------------------------| 
| DCK_CONFIDENCE     |  2    |  Definitions:                 | 
|                    |       |                               | 
|                    |       |  0    DCV_LOW_CONF            | 
|                    |       |                               | 
|                    |       |  1    DCV_MED_CONF            | 
|                    |       |                               | 
|                    |       |  2    DCV_HIGH_CONF           | 
|                    |       |                               | 
|--------------------|-------|-------------------------------| 
| DCK_NAME_CONTEXT   |  3    |  Character string array       | 
|--------------------|-------|-------------------------------| 
| DCK_TRANSPORT_TYPE |  4    |  Not currently in use         | 
|--------------------|-------|-------------------------------| 
| DCK_REFERRAL_SCOPE |  5    |  Definitions:                 | 
|                    |       |                               | 
|                    |       |  0    DCV_ANY_SCOPE           | 
|                    |       |                               | 
|                    |       |  1    DCV_COUNTRY_SCOPE       | 
|                    |       |                               | 
|                    |       |  2    DCV_ORGANIZATION_SCOPE  | 
|                    |       |                               | 
|                    |       |  3    DCV_LOCAL_SCOPE         | 
|                    |       |                               | 
|--------------------|-------|-------------------------------| 
| DCK_LAST_CONNECTION|  8    |  Connection handle            | 
|--------------------|-------|-------------------------------| 
| DCK_TREE_NAME      |  11   |  Character string array       | 
|--------------------|-------|-------------------------------|

value should point to a variable of a type appropriate to receive the specified variable. The data types associated with each key are listed in the explanations below.

The flags associated with DCK_FLAGS are defined as follows:

0x00000001L: DCV_DEREF_ALIASES
0x00000002L: DCV_XLATE_STRINGS
0x00000004L: DCV_TYPELESS_NAMES
0x00000008L: DCV_ASYNC_MODE
0x00000010L: DCV_CANONICALIZE_NAMES
0x00000040L: DCV_DEREF_BASE_CLASS
0x00000080L: DCV_DISALLOW_REFERRALS

DCV_DEREF_ALIASES, DCV_XLATE_STRINGS, and DCV_CANONICALIZE_NAMES are set by default.

The data type used to retrieve the flags is a nuint32.

If key is DCK_CONFIDENCE, the value pointed to by value can be one of the following:

0: DCV_LOW_CONF
1: DCV_MED_CONF
2: DCV_HIGH_CONF

DCV_LOW_CONF is set by default.

The data type used to retrieve the confidence level is a nuint32.

If key is DCK_NAME_CONTEXT, value points to a buffer containing the name context. You must allocate space for this buffer. The size of the memory needed to store the name context is ((MAX_DN_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.

DCK_TRANSPORT_TYPE is currently not used. The data type for this value is a nuint32[2].

If key is DCK_REFERRAL_SCOPE, value can be one of the following:

0: DCV_ANY_SCOPE
1: DCV_COUNTRY_SCOPE
2: DCV_ORGANIZATION_SCOPE
3: DCV_LOCAL_SCOPE

DCV_ANY_SCOPE is set by default.

The data type used to retrieve the referral scope is a nuint32.

Directory context variables can be changed by calling NWDSSetContext.

Services

NCP calls

None

References

NWDSCreateContext(3nw), NWDSSetContext(3nw)