2.1 Context Handle Tasks

An NDS context points to a specific location in the eDirectory tree. This section gives instructions on how to create, free, modify, and read a context.

2.1.1 Creating a Context Handle

To create a context handle, the Unicode tables must be initialized.

  1. Call NWDSCreateContextHandle.

    The following code illustrates these steps.

      NWDSCCODE            ccode; 
  NWDSContextHandle    context; 
  ccode = NWDSCreateContextHandle(&context); 
  if(ccode) 
      /* handle creation error */

See Also:

2.1.2 Freeing a Context Handle

Freeing a context frees memory.

  1. Call NWDSFreeContext.

    The following code illustrates this procedure.

      NWDSCCODE err;  
  ...  
  // Now free the context before exiting the program.  
  err = NWDSFreeContext(context);  
  if(!err)  
     printf("\n\nContext was freed\n");  
  else  
     printf("\n\nError <%d> occurred while freeing context\n", err);

See Also:

2.1.3 Modifying the Context of the Context Handle

The following steps explain how to modify the context of the context handle. (For a list of other keys and flags that can be modified, see Section 5.6, Context Keys and Flags.)

Modifying the context of the context handle is only important if the context handle is set to use both dot name forms and canonicalized names. (These values are assigned as defaults when a context handle is created.)

  1. Call NWDSSetContext with the DCK_NAME_CONTEXT flag and the name of the new context.

    The context name should be in the following format:

    • In the local code page if the SCV_XPLATE_STRINGS flag is on (default) or Unicode if off.

    • The complete name of the context, without the tree name.

    The following code illustrates these procedures.

      NWDSCCODE err;  
  char newContextName[MAX_DN_CHARS+1]; /* ((MAX_DN_CHARS+1)*2)for unicode */  
  /* change the context name */ 
  printf("\n\nEnter a new name context: \n");  
  gets(newContextName);  
  err=NWDSSetContext(context,DCK_NAME_CONTEXT,newContextName);  
  if(err)  
  {  
     printf("\n\nNWDSSetContext returned error <%d>",err);  
  }  
  else  
  {  
     printf("\n\nNWDSSetContext returned <%d>",err);  
     printf("\nName context is set.");  
  }

See Also:

2.1.4 Reading the Context of the Context Handle

The following steps explain how to read the context of the context handle. (For a list of other information that can be read about the context handle, see Section 5.6, Context Keys and Flags.)

  1. Declare a variable that matches the data type of the context name key (a NULL terminated string) and that is large enough to hold the name of the context.

    Local code page names need a length of MAX_DN_CHARS+1 and Unicode names need ((MAX_DN_CHARS+1)*2).

  2. Call NWDSGetContext with the key parameter set to DCK_NAME_CONTEXT.

    The following code illustrates these procedures.

      void ShowNameContext(NWDSContextHandle context)  
  {  
     NWDSCCODE err;  
     char name[MAX_DN_CHARS+1]; /* ((MAX_DN_CHARS+1)*2)for unicode */  
     err = NWDSGetContext(context, DCK_NAME_CONTEXT, name);  
     if(err)  
     {  
        printf("\n\nNWDSGetContext returned error <%d>",err);  
     }  
     else  
     {  
        printf("\nCurrent Name Context: %s",name);  
     } 
  }

See Also: