Programming Guides › Programming Guide for C › Directory API Guidance › Structures Used in the Sample Directory Application

Structures Used in the Sample Directory Application

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:

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.

More Information:

How To Distinguish between Handle Types

Directory Provider Handle

The sample defines the provider handle structure ProviderHandle_t to serve as a bridge between the SiteMinder Policy Server and the Directory API. The provider handle can be used to store data from the time SiteMinder loads the library until the SiteMinder 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.