Structures Used in the Sample Directory Application

Contents
casso126
Contents
The sample Directory API application resides in:
<install_path>\sdk\samples\smdirapi\smdirapi.cpp
The Directory API includes a directory instance handle, a directory provider handle, and a directory entry (user) instance handle. These handles are returned from the initialization functions listed in section Initialization and Release Functions.
The sample code uses the following structures to manage these handles:
Handle Type
Data Structure
Directory instance
DirHandle_t
Directory provider
ProviderHandle_t
Directory entry (user) instance
UserHandle_t
Directory Instance Handle
The sample instantiates DirHandle_t when SmDirInitDirInstance() is called. The handle is then passed to the directory operations functions.
The same value need not be carried through the entire process. You are permitted to change the value.
The definition of DirHandle_t is as follows:
typedef struct DirHandle_s
{
   char nTag;
   bool bValid;
   char szErrMsg[ERRMSG_SIZE];
   char* pszUniqueKey;
   char* pszParameter;
   char* pszUsername;
   char* pszPassword;
   int bRequireCredentials;
   int bSecureConnection;
   int nSearchResults;
   int nSearchTimeout;
} DirHandle_t;
The sample releases DirHandle_t when SmDirReleaseInstance() is called. The value of
nTag
is used to distinguish between the directory instance handle and the user instance handle.
Directory Provider Handle
The sample defines the provider handle structure ProviderHandle_t to serve as a bridge between the
CA Single Sign-On
Policy Server and the Directory API. The provider handle can be used to store data from the time
CA Single Sign-On
loads the library until the
CA Single Sign-On
Policy Server shuts down.
The sample instantiates ProviderHandle_t when SmDirInit() is called. The handle is then passed to almost all subsequent functions. The same value need not be carried through the entire process. You are permitted to change the value.
The sample releases ProviderHandle_t when SmDirRelease() is called.
See the function SmDirInit() in the sample code for an example of ProviderHandle_t. You can follow this example, but you aren’t required to. ProviderHandle_t can contain any information that you would like to set at the beginning of the process and carry through, such as a user’s password.
Directory Entry (User) Instance Handle
The sample instantiates UserHandle_t when SmDirInitUserInstance() is called. This handle is then passed to the directory entry (user) operations functions. For a list of these functions, see Operations on a Directory Entry (User).
The same value need not be carried through the entire process. You are permitted to change the value.
The definition of UserHandle_t is as follows:
typedef struct UserHandle_s
{
   char nTag;
   bool bValid;
   char szErrMsg[ERRMSG_SIZE];
   DirHandle_t* phDir;
   char* pszUserDn;
} UserHandle_t;
The sample releases UserHandle_t when SmDirReleaseInstance() is called.
How To Distinguish between Handle Types
Some functions, such as SmDirReleaseInstance(), may be passed either the directory instance handle or the directory entry (user) instance handle. The sample code provides a way you can distinguish the directory instance handle from the directory entry (user) instance handle.
Notice that
nTag
is the first field of both DirHandle_t and UserHandle_t. When SmDirInitDirInstance() is called,
nTag
is set to 0 in DirHandle_t. When SmDirInitUserInstance is called,
nTag
is set to 1 in UserHandle_t.
When a function that accepts either type of handle is called, the value of
nTag
is checked to see which type of handle is being passed.