NWDSSetContext(3nw)

NWDSSetContext -- sets value of Directory context variable

Synopsis

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

Description

The parameters are as follows:

context: (IN) Specifies the Directory context for the request.
key: (IN) Specifies the context variable to set.
value: (IN) Points to the value for context.

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). See ``Error return values'' for more information on errors.

Notices

Applications do not have direct access to the Directory context variables. To change the settings of the context variables, applications must call NWDSSetContext, using a key to identify which context variable to set information for.

The 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 matching the type of the specified variable. The data types associates with each key are listed in the explanations below.

The flags associated with the DCK_FLAGS key 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

The data type to set the flags is a nuint32.

NOTE: Before setting the context flags, first read in the current settings of the flags by calling NWDSGetContext. Then use bitwise operations to change the flag(s) you want to change, while leaving the settings of the other flags unchanged. Then call NWDSSetContext to set the context flags to the desired settings.

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

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

If key is DCK_NAME_CONTEXT, value pointsto a buffer containing the name context. The maximum size of the buffer 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

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

Values stored in a directory context can be read by calling NWDSGetContext.

Services

NCP calls

None

References

NWDSCreateContext(3nw), NWDSFreeContext(3nw), NWDSGetContext(3nw)