Programming Guides › Programming Guide for C › Directory API

Directory API

This section contains the following topics:

Purpose of the Directory API

Before You Use the Directory API

How to Use the Directory API

Sequence of Function Calls

Structures Used in the Sample Directory Application

Purpose of the Directory API

The Directory API accesses data stored in a type of database or directory that SiteMinder does not support. With the Directory API, you can:

• Add a non-supported directory entry (user) to a SiteMinder policy
• Manage non-supported directory entries

SiteMinder supports the following namespaces for user directories:

• LDAP
• ODBC
• Microsoft Windows NT
• Custom

The LDAP, ODBC and NT namespaces can be used without the Directory API. To access another type of user directory, create an interface to the directory with the Directory API.

Before You Use the Directory API

Before using the Directory API, go to the SiteMinder Administrative UI and create and configure a user directory object with a Custom namespace.

To use the Directory API, you must have the following:

• One or more application developers who have experience with the following tasks:
  • Coding in the C programming language
  • Building shared libraries
  • Using relevant APIs provided by the vendor of the desired directory type
• A supported development environment for building a shared library.

  Because no linking is required, there is no restrictive list of supported development environments. For example, you can use the GNU Compiler Collection (GCC). The Directory API has been tested using the following development environments:

  • UNIX platforms: Sun Visual WorkShop C++ 5.0
  • Windows platforms: Microsoft Visual C++ 6.0
• The SiteMinder Policy Server

  Although you don’t need the SiteMinder Policy Server to build a Directory API application, you need the SiteMinder Policy Server to use the application. The SiteMinder Policy Server calls the Directory API.

How to Use the Directory API

When you have met the prerequisites, follow these steps:

1. Review the sample provided with the Directory API.
2. Write source code to implement the Directory API.
3. Build a shared library from the source code.
4. Place the shared library in the default location, as follows:
   • On UNIX platforms, in the SiteMinder lib directory
   • On Windows platforms, in the SiteMinder bin directory

   Optionally, you can place the shared library in a different location, as long as the SiteMinder Policy Server can access it. If you use an alternate location, indicate the fully qualified path to the shared library in the Library field of the SiteMinder User Directory Dialog box.

Build a Directory Application

When you build a Directory API application, include the SmAPI.h file. Your source code must contain the statement:

#include "SmApi.h"

When building a shared library that implements the Directory API, you need not link to any other shared libraries or import libraries. The Directory API is built as a shared library with the exportable functions defined in the include file SmApi.h.

Exported Enumerations

SmApi.h includes the following enumerations used by the Directory API:

• Sm_DirApi_Capability_t (directory capabilities)
• Sm_PolicyResolution_t (policy resolutions)

Directory Capabilities

Sm_DirApi_Capability_t enumerates the capabilities that can be configured for a custom directory.

The following table lists the directory capabilities enumerated in Sm_DirApi_Capability_t. Descriptions of each capability follow the table.

For a custom directory to have a specific capability, you must define the required user attributes for that capability. For example, to enable SiteMinder to change a user’s password, you need to identify a Password Attribute. SiteMinder then uses that attribute to get and set the user password.

• Sm_DirApi_Capability_ForceResetUserPassword. The custom directory is capable of forcing user password reset.

  To enable SiteMinder to force a reset of the password, define the following user attributes:

  • Password attribute. An attribute that SiteMinder can use to get and set the user password. In the SiteMinder Administrative UI, enter that attribute name in the Password Attribute field on the User Attributes tab on the User Directory Dialog box. In the sample, the attribute name is password.
  • Disabled Flag. An attribute that SiteMinder can use to get and set the disabled state of a user. In the SiteMinder Administrative UI, enter that attribute name in the Disabled Flag field on the User Attributes tab on the User Directory Dialog box. In the sample, the attribute name is Disabled.

  When users are forced to change their passwords, the Policy Server calls SmDirSetUserDisabledState(). In the sample code, the user’s Disabled Flag is set to Sm_Api_Disabled_PWMustChange (the disabled reason).

• Sm_DirApi_Capability_ChangeUserPassword. The custom directory is capable of changing the user password. To change the password, you need to identify a Password Attribute, which is an attribute that SiteMinder can use to get and set the user password. In the SiteMinder Administrative UI, enter that attribute name in the Password Attribute field on the User Attributes tab on the User Directory Dialog box.

  The SiteMinder Policy Server calls SmDirChangeUserPassword() so that you can change the value in the password field for an entry in your custom directory.

• Sm_DirApi_Capability_DisableUser. The custom directory is capable of disabling a user account. To disable a user, you need to identify a Disabled Flag, which is an attribute that SiteMinder can use to get and set the disabled state of a user. In the SiteMinder Administrative UI, enter that attribute name in the Disabled Flag field on the User Attributes tab on the User Directory Dialog box.

  When an administrator uses the SiteMinder Administrative UI to disable or enable a user account, or when Password Services disables a user account, the SiteMinder Policy Server calls SmDirSetUserDisabledState().

  In SiteMinder, user accounts can be disabled for a number of reasons, and these reasons are represented by the members of the data structure Sm_Api_DisabledReason_t.

• Sm_DirApi_Capability_SetUserAttributes. SiteMinder can set user attributes in the custom directory.

  The SiteMinder Policy Server calls SmDirSetUserAttr() so that you can use SiteMinder to set a user attribute in your custom directory.

• Sm_DirApi_Capability_Recursive. The custom directory is capable of supporting recursion. For example, the custom directory may support nested groups.

  The following functions in the Directory API have a parameter to hold a recursive flag:

  • SmDirGetUserGroups()
  • SmDirValidateUserPolicyRelationship()

To send information about the directory capabilities to the SiteMinder Policy Server, implement the function SmDirQueryVersion(). Use the capabilities parameter (pnCapabilites) to pass one or more values enumerated in Sm_DirApi_Capability_t. SiteMinder then checks for those capabilities.

For example, if a user attempts to change a password, the SiteMinder Policy Server calls SmDirQueryVersion() to check for the capability Sm_DirApi_Capability_ChangeUserPassword. If the custom directory does not have that capability, the user receives an error message.

An example of setting the directory capabilities is shown in the sample code. First, initialize *pnCapabilities to zero, then set *pnCapabilities as follows:

*pnCapabilities = 
   *pnCapabilities | Sm_DirApi_Capability_<supported_capability>;

For example:

*pnCapabilities =
   *pnCapabilities | Sm_DirApi_Capability_ChangeUserPassword;
*pnCapabilities =
   *pnCapabilities | Sm_DirApi_Capability_DisableUser;

Ensure that no other application changes data in fields intended for use by SiteMinder. For example, no other application should change data in the field that holds the disabled state of a SiteMinder user.

Policy Resolutions

Sm_PolicyResolution_t, defined in SmApi.h, enumerates the values that describe the relationship between two policy objects. The following Directory API functions use Sm_PolicyResolution_t:

• SmDirAddEntry()
• SmDirGetDirObjInfo()
• SmDirRemoveEntry()
• SmDirValidateUserPolicyRelationship()

General Data Types and Structures

The data types and structures are used in the Directory API, but may also be used by other SiteMinder APIs.

Sm_Api_DisabledReason_t enumerates the reasons that a user account can be disabled.

The following Directory API functions use Sm_Api_DisabledReason_t:

• SmDirGetUserDisabledState()
• SmDirSetUserDisabledState()

When a user’s account is enabled or disabled, the SiteMinder Policy Server calls SmDirSetUserDisabledState(). This call gives you the opportunity to set the disabled flag in your custom directory to one or more of the disabled reasons, as enumerated in Sm_Api_DisabledReason_t. If a user’s account is disabled or enabled, SmDirGetUserDisabledState() returns the disabled reason(s). When implementing SmDirGetUserDisabledState(), return Sm_Api_Disabled_Enabled if your custom directory does not support a disabled flag.

Note: A user’s account can be disabled for multiple reasons. For example, if the User must change password at next login checkbox is checked and the administrator then clicks Disable, the nDisabledReason holds both the Sm_Api_Disabled_PWMustChange bit and the Sm_Api_Disabled_AdminDisabled bit.

The disabled flag is a SiteMinder user attribute. In the SiteMinder Administrative UI, on the User Attributes tab of the User Directory Dialog box, enter the attribute name in the Disabled Flag field. In the sample, the attribute name is Disabled.

The structure Sm_Api_Context_t gives the function pointers for the SiteMinder logging utility, trace utility, and error utility.

Sm_Api_Reason_t enumerates the reasons for an access event, such as an authentication failure. When a user supplies credentials for authentication, the SiteMinder Policy Server, validating the username and DN, calls SmDirAuthenticateUser(). This call gives you the opportunity to return information about the access event.

Initialization and Release Functions

To initialize objects, the SiteMinder Policy Server calls the functions in the following table:

Initializing the Directory Provider

The first time that the custom directory provider is required after the SiteMinder Policy Server is started, the Policy Server calls SmDirInit() to initialize the directory provider. At this point, set the provider handle as shown in the sample code. The SiteMinder Policy Server will not call SmDirInit() again until one of the Policy Server services is started (or re-started).

SmDirInit() is called once per custom directory provider library (.dll or .so).

Initializing the Directory Instance

The Policy Server calls SmDirInitDirInstance() to initialize the directory instance. Set the directory instance handle as shown in the sample code.

SmDirInitDirInstance() is called once per directory instance using this directory provider library. SiteMinder calls the function when it needs a directory context (to perform an operation such as search or get properties) while processing an authentication or authorization request. This function is typically called at the beginning of a request.

Initializing the Directory Entry (User) Instance

The SiteMinder Policy Server initializes the user instance by calling SmDirInitUserInstance(). Set the directory entry (user) instance handle as shown in the sample code.

To release objects, use the functions in the following table:

Releasing the User Instance

The SiteMinder Policy Server calls SmDirReleaseInstance() so that you can release the user instance handle if you choose. Ensure that the handle that is passed is the user instance handle, not the directory instance handle.

Releasing the Directory Instance

The SiteMinder Policy Server calls SmDirReleaseInstance() so that you can release the directory instance handle if you choose. Ensure that the handle that is passed is the directory instance handle, not the user instance handle.

SiteMinder calls SmDirReleaseInstance() once per every call to SmDirInitDirInstance(), after the directory context is no longer needed. It is typically called at the end of a request.

Releasing the Directory Provider

When an administrator starts to shut down the SiteMinder Policy Server, the SiteMinder Policy Server calls SmDirRelease() to release the directory provider.

More Information:

How To Distinguish between Handle Types

Utility Functions

These functions can be called either within a sequence of directory operations or within a sequence of directory entry (user) operations. If the function receives an instance handle through a parameter, determine whether it is a directory instance handle or a directory entry (user) instance handle.

Free Strings and String Arrays

After the SiteMinder Policy Server calls an operation function that takes string parameters, the SiteMinder Policy Server calls SmDirFreeString() or SmDirFreeStringArray() to release allocated memory. Calls may be repeated so that multiple strings can be freed.

For example, a SiteMinder Administrator can use the SiteMinder Administrative UI to perform a search for the user Mikel. The SiteMinder Administrator first selects the string User from the Search drop-down list box, then enters the string Mikel in the Search Expression field. SiteMinder calls SmDirLookup() and passes the strings (in the form “User = Mikel”) into the lpszPattern parameter. SiteMinder then calls SmDirFreeStringArray() twice. On the first call, SiteMinder passes the string array Mikel. On the second call, SiteMinder passes the string array User.

Query and Validation

The SiteMinder Policy Server frequently calls SmDirQueryVersion(), then SmDirValidateInstance(). This sequence may be repeated several times.

Operations on the Directory

The Policy Server calls the directory operations function(s) to let you define directory operations tasks for your custom directory. For example, if a user is using the SiteMinder Administrative UI to search for a user, the Policy Server calls SmDirLookup().

Operations on a Directory Entry (User)

The operations covered in this section apply to directory entries, such as users, groups and roles.

The SiteMinder Policy Server calls the directory entry (user) operation function(s) relevant to the operation performed. For example, if a user is using the SiteMinder Administrative UI to disable a user account, the SiteMinder Policy Server calls SmDirSetUserDisabledState().

Sequence of Function Calls

The following diagrams outline the order of function calls for procedures that perform operations on the directory and possibly perform operations on a directory entry (user). For example, using the SiteMinder Administrative UI to search for a particular user in a custom directory requires both operations on the directory and operations on a directory entry (user). Some procedures involve only operations on the directory. For example, using the SiteMinder Administrative UI only to view the properties of a custom user directory requires only operations on the directory.

This second diagram shows an additional sequence that occurs only if directory entry (user) operations occur.

To authenticate a user, the SiteMinder Policy Server requests a username from the user. SmDirValidateUsername() is called to translate the user-supplied username into the internal user ID key used by the directory as the primary key to the user’s data. The username from the credentials is supplied in the lpszUsername parameter. If SmDirValidateUsername() is not implemented, the user-supplied username is passed into lpszUserDN.

If SmDirValidateUsername() is implemented, it should return the user’s ID in the lpszNewUsername parameter. The value returned by lpszNewUsername becomes the lpszUserDN parameter value.

The lpszUserDN parameter value is passed into many other functions, such as SmDirValidateUserDN() and SmDirAuthenticateUser().

SmDirAddEntry()

The SiteMinder Policy Server calls SmDirAddEntry() so that you can insert a directory entry (user) into your custom directory. Examples of directory entries are users, groups and roles. For example, if you are using a SQL database and need to add a group, you could use SmDirAddEntry() to insert a record into the groups table (and all related tables) for the database.

When adding an entry to a hierarchical directory, it may be helpful to look at the attributes passed in with the entry, such as object class in LDAP.

Syntax

int SM_EXTERN SmDirAddEntry (
   const Sm_Api_Context_t*       lpApiContext,
   void*                         pHandle,
   void*                         pInstanceHandle,
   const Sm_PolicyResolution_t   nEntryType,
   const char*                   lpszEntryDN,
   const char**                  lpszAttrNames,
   const char**                  lpszAttrValues
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when Delegated Management Services is used to create directory entries, including users or roles.

SmDirAddMemberToGroup()

The SiteMinder Policy Server calls SmDirAddMemberToGroup() so that you can add a user or group to an existing group.

If you want to add a user or group to a role, use SmDirAddMemberToRole(). The difference between a group and a role is defined by your custom directory provider. For some providers, there is no difference.

Syntax

int SM_EXTERN SmDirAddMemberToGroup (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszMemberDN,
   const char*              lpszGroupDN
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when Delegated Management Services is used to assign either a user or a group to an existing group.

SmDirAddMemberToRole()

The SiteMinder Policy Server calls SmDirAddMemberToRole() so that you can assign a role to a user or to a group.

For example, in Oracle, a role is a set of object or system privileges that can be granted to a user. A group is a set of users. If you want everyone that performs collections to be able to update the AR table and select from the CUSTOMER table, you could create a role named COLLECTIONS. You could then assign the COLLECTIONS role to each of the individual users who perform collections, or even to a group such as Accounts Receivable.

If you want to add either a user or group to an existing group, use SmDirAddMemberToGroup(). The difference between a group and a role is defined by the provider of the custom directory.

For some providers, there will be no difference between a role and a group.

Syntax

int SM_EXTERN SmDirAddMemberToRole (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszMemberDN,
   const char*              lpszRoleDN
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when Delegated Management Services is used to assign a role to a user or a group.

SmDirAuthenticateUser()

Use the SmDirAuthenticateUser() function to check the directory for the provided user name and password.

After the call to SmDirAuthenticateUser(), SiteMinder calls SmDirFreeString() to free the lpszUserMsg buffer, then calls SmDirFreeString() again to free the lpszErrMsg buffer.

Syntax

int SM_EXTERN SmDirAuthenticateUser (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const char*              lpszPassword,
   Sm_Api_Reason_t*         pnReason,
   char**                   lpszUserMsg,
   char**                   lpszErrMsg
);

Returns

Returns 0 if authentication succeeds, or -1 if there is an error in processing or if the user-supplied credentials are invalid.

If authentication fails, convey the reason through the output parameter pnReason and return -1.

Remarks

This function is called when you use the SiteMinder Test Tool to run IsAuthenticated for a user in the custom directory.

SmDirChangeUserPassword()

The SiteMinder Policy Server calls SmDirChangeUserPassword() so that you can change the value in the password field for an entry in your custom directory.

To implement SmDirChangeUserPassword(), you must specify the name of the password field in your custom directory. In the SiteMinder Administrative UI, enter that attribute name in the Password Attribute field on the User Attributes tab of the User Directory Dialog box.

The user’s distinguished name is passed in with the following information:

• Old password
• New password
• Name of the password field in the custom directory
• Whether the old password is needed

Syntax

int SM_EXTERN SmDirChangeUserPassword (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const char*              lpszOldPassword,
   const char*              lpszNewPassword,
   const char*              lpszPasswordAttr,
   const int                bDoNotRequireOldPassword
);

Returns

Returns 0 if successful or -1 if not successful.

Sample Code Information

If you are changing a user password, SiteMinder passes the name of the password attribute through lpszPasswordAttr. To indicate the name of the directory attribute that holds this information:

1. In the SiteMinder Administrative UI, go to the User Directory Dialog box
2. In the User Attributes tab, complete the Password Attribute field. To use the sample, type password in this field.

SmDirEnumerate()

The SiteMinder Policy Server calls SmDirEnumerate() to retrieve a list of distinguished names and their corresponding class names (User or Group) in the user directory.

The SiteMinder Policy Server calls SmDirFreeStringArray() to free the lpszDNs and lpszClasses arrays.

Syntax

int SM_EXTERN SmDirEnumerate (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   char***                  lpszDNs,
   char***                  lpszClasses
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when you click the View Contents button in the SiteMinder User Directory Dialog box.

SmDirFreeString()

The SiteMinder Policy Server calls SmDirFreeString() to free memory allocated for the specified string in lpszString.

Syntax

void SM_EXTERN SmDirFreeString (
   char* lpszString
);

SmDirFreeStringArray()

The SiteMinder Policy Server calls SmDirFreeStringArray() to free memory allocated for the specified string array in lpszStringArray. For example, after a call to SmDirEnumerate(), the SiteMinder Policy Server calls SmDirFreeStringArray() to free memory allocated for parameter lpszDNs, then calls SmDirFreeStringArray() again to free memory allocated for parameter lpszClasses.

Syntax

void SM_EXTERN SmDirFreeStringArray (
   char* lpszStringArray
);

SmDirGetDirConnection()

This function is called to get the connection handle to the directory.

If you are using active rules, policies, or responses, the SiteMinder Policy Server calls SmDirGetDirConnection() when it calls an authentication scheme library or an active library. The SiteMinder Policy Server calls SmDirGetDirConnection() before authentication.

When implementing SmDirGetDirConnection(), return NULL.

Syntax

void* SM_EXTERN SmDirGetDirConnection (
   const Sm_Api_Context_t*   lpApiContext,
   void*                     pHandle,
   void*                     pInstanceHandle
);

Returns

When implementing SmDirGetDirConnection(), return NULL, as shown in the sample.

SmDirGetDirObjInfo()

The SiteMinder Policy Server calls SmDirGetDirObjInfo() to get information about the object specified in the lpszObject buffer. You can use this function to get the following information about the object passed in as lpszObject:

• Distinguished Name (lpszDN)
• Class (lpszClass)
• Policy Resolution (pnSmPolicyResolution)

The SiteMinder Policy Server calls SmDirFreeString() to free the lpszDN and lpszClass buffers.

Syntax

int SM_EXTERN SmDirGetDirObjInfo (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszObject,
   char**                   lpszDN,
   char**                   lpszClass,
   int*                     pnSmPolicyResolution
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called in the following circumstances:

• Searching for a user
• Enabling or disabling a user account

Sample Code Information

If you are disabling user account Mikel, Mikel is passed in as lpszObject. Using the sample code, the following values are returned:

SmDirGetGroupMembers()

The SiteMinder Policy Server calls SmDirGetGroupMembers() so that you can retrieve the members of a user group. This function is designed to support Delegated Management Services.

Syntax

int SM_EXTERN SmDirGetGroupMembers (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszGroupDN,
   char***                  lpszMembers,
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirGetLastErrMsg()

Calling the function SmDirGetLastErrMsg() retrieves the last error message that resulted from a Directory API call.

If a user operation or directory operation fails, store the error message in szErrMsg, which is the third field of the instance handle structure. You can then call SmDirGetLastErrMsg() to retrieve the error message. The SiteMinder Policy Server also calls SmDirGetLastErrMsg() upon operation failure.

This function call is made for both the directory instance and the user instance. Either the directory instance handle or user instance handle can be passed through pInstanceHandle. Your code must determine which handle is passed and return the appropriate error message. See the sample code for an example.

After calling SmDirGetLastErrMsg(), the SiteMinder Policy Server calls SmDirFreeString() to free the error buffer.

Syntax

char* SM_EXTERN SmDirGetLastErrMsg (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle
);

Returns

The last error message occurred during a directory operation or user operation.

Remarks

This function is called when you are searching for users or groups and the lookup (SmDirLookup()) fails.

Sample Code Information

In the sample code for SmDirValidateUserPolicyRelationship(), under the condition that the policy resolution is UserGroup, there is a call to the function chk_grp(). The third parameter of chk_grp() is an output parameter that returns szErrMsg in the user handle. If you then called SmDirGetLastErrMsg() and passed the user instance handle, you would get the value stored in szErrMsg.

SmDirGetRoleMembers()

The SiteMinder Policy Server calls SmDirGetRoleMembers() so that you can retrieve the directory entries assigned to a role. This function is designed to support Delegated Management Services.

Syntax

int SM_EXTERN SmDirGetRoleMembers (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszRoleDN,
   char***                  lpszMembers
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirGetUserAttr()

The SiteMinder Policy Server calls SmDirGetUserAttr() so that you can retrieve the value for a user attribute in your custom directory. For example, you may need to retrieve the last name of a user.

SiteMinder calls SmDirFreeString() to free the lpszAttrData buffer.

Syntax

int SM_EXTERN SmDirGetUserAttr (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const char*              lpszAttrName,
   char**                   lpszAttrData
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirGetUserAttrMulti()

The SiteMinder Policy Server calls SmDirGetUserAttrMulti() so that you can retrieve an array of values for a single attribute. The provider needs to handle the case where this function is called and the attribute has only a single value.

SiteMinder calls SmDirFreeStringArray() to free the lpszAttrData buffer.

Syntax

int SM_EXTERN SmDirGetUserAttrMulti (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const char*              lpszAttrName,
   char***                  lpszAttrData
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirGetUserClasses()

The SiteMinder Policy Server calls SmDirGetUserClasses() so that you can get the object classes of the specified distinguished name (DN). This function is designed to support Delegated Management Services.

Your custom directory may be hierarchical or flat. If your directory is hierarchical, as with an LDAP directory, the DN may belong to multiple object classes. If the directory is flat, as with a SQL database, the user DN belongs to a single class, such as User or Group.

Your code must determine the type of DN passed and handle it appropriately. For example, if a the name of a group is passed in, you need to be able to determine that it is a group and return Group.

SiteMinder calls SmDirFreeStringArray() to free the lpszAttrData buffer.

Syntax

int SM_EXTERN SmDirGetUserClasses (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   char***                  lpszClasses
);

Returns

Returns 0 if successful or -1 if not successful.

If you decide not to implement this function, return -1.

SmDirGetUserDisabledState()

The SiteMinder Policy Server calls SmDirGetUserDisabledState() to get information about whether a user account is disabled.

If a user account is disabled, SmDirGetUserDisabledState() returns information in pnDisabledReason about how the account was disabled.

The possible reasons that a user is disabled are enumerated in Sm_Api_DisabledReason_t, which is defined in SmApi.h. The disabled reason is set when the SiteMinder Policy Server calls SmDirSetUserDisabledState().

If the custom directory does not support a disabled flag, use the following code to indicate that the user is always enabled:

*pnDisabledReason = Sm_Api_Disabled_Enabled;
return 0;

Syntax

int SM_EXTERN SmDirGetUserDisabledState (
   const Sm_Api_Context_t*   lpApiContext,
   void*                     pHandle,
   void*                     pInstanceHandle,
   const char*               lpszUserDN,
   const char*               lpszDisabledAttr,
   Sm_Api_DisabledReason_t*  pnDisabledReason
);

Returns

Return values indicate whether the function successfully determines the user’s disabled state:

• Return 0 if the function successfully determines the user’s disabled state.
• Return -1 if the function fails to determine the user’s disabled state.

Return values do not indicate the disabled state, which is stored in the parameter pnDisabledReason.

Remarks

This function is called in the following circumstances:

• When searching for a user, after calling SmDirLookup() to perform the lookup.
• After calling SmDirSetUserDisabledState() to change the disabled state of a user.
• After calling SmDirAuthenticateUser() to authenticate a user. If the disabled flag is set for a user, SiteMinder does not authenticate the user—even if the user supplies valid credentials.

Sample Code Information

If you are managing users, when you lookup the user, SiteMinder checks the disabled state for that user by checking lpszDisabledAttr. To indicate the name of the directory attribute that holds this information, in the SiteMinder Administrative UI, in the User Directory Dialog box, on the User Attributes tab, complete the Disabled Flag field. To use the sample, type Disabled in this field.

If the user is enabled, then running the sample code results in a value of Sm_Api_Disabled_Enabled for pnDisabledReason. If the SiteMinder administrator has used the Disable button to disable the user, then running the sample code results in a value of Sm_Api_Disabled_AdminDisabled for pnDisabledReason.

SmDirGetUserGroups()

The SiteMinder Policy Server calls SmDirGetUserGroups so that you can retrieve the groups to which a user belongs.

SiteMinder calls SmDirFreeStringArray() to free the lpszGroups array.

Syntax

int SM_EXTERN SmDirGetUserGroups (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const int                bRecursive,
   char***                  lpszGroups
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirGetUserProperties()

SiteMinder calls SmDirGetUserProperties() so that you can return the names of all user attributes or only required user attributes.

Unlike SmDirGetUserAttr(), which is designed to return values for the attribute names passed, SmDirGetUserProperties() is designed for returning only attribute names.

SiteMinder calls SmDirFreeStringArray() to free the lpszProperties array.

Syntax

int SM_EXTERN SmDirGetUserProperties (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const int                bMandatory,
   char***                  lpszProperties
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirGetUserRoles()

The SiteMinder Policy Server calls SmDirGetUserRoles() so that you can retrieve the roles to which a user belongs.

SiteMinder calls SmDirFreeStringArray() to free the lpszRoles array.

Syntax

int SM_EXTERN SmDirGetUserRoles (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   char***                  lpszRoles
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirInit()

SmDirInit() is called when SiteMinder initializes the directory services provider for the custom namespace.

This function is called once before any other Directory API functions are called. The function returns the address of a pointer to the handle for the directory. The handle is passed in all subsequent function calls.

Once the administration process starts, the SiteMinder Policy Server calls SmDirInit() the first time you perform any task for which the custom directory provider is required.

For example, if you were to start the Policy Server, then immediately view the properties of a user directory with a Custom namespace, the SiteMinder Policy Server would call SmDirInit(), then call SmDirInitDirInstance().

Syntax

int SM_EXTERN SmDirInit (
   const Sm_Api_Context_t*  lpApiContext,
   void**                   ppHandle,
   const char*              lpszParameter
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

Instantiate ProviderHandle_t when SmDirInit() is called. This 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.

Release ProviderHandle_t when SmDirRelease() is called.

You could use SmDirInit() to load another shared library. The vendor of the directory containing your data may provide an interface that you can implement by building a shared library. You could use SmDirInit() to load that shared library by placing the path to the shared library in the Parameter field on the Directory Setup tab of the User Directory Dialog box. The string entered in the Parameter field is passed to lpszParameter in calls to SmDirInit() and SmDirInitDirInstance().

Note: The string entered in the Parameter field is also passed to lpszSearchRoot in calls to SmDirSearch() and SmDirSearchCount(). If your code for SmDirInit() needs to use lpszParameter and your code for the search functions needs a search root, you will have to parse the string from the Parameter field.

SmDirInitDirInstance()

SiteMinder calls this directory instance initialization function before it calls any of the directory functions on the given directory instance. This function provides you an opportunity to make a connection to the custom directory.

After SiteMinder completes the directory function call, it calls SmDirReleaseInstance(). This function is called multiple times. SiteMinder does not require you to make and break directory connections every time the initialization and release calls are made.

Syntax

int SM_EXTERN SmDirInitDirInstance (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void**                   ppInstanceHandle,
   const char*              lpszUniqueKey,
   const char*              lpszParameter,
   const char*              lpszUsername,
   const char*              lpszPassword,
   const int                bRequireCredentials,
   const int                bSecureConnection,
   const int                nSearchResults,
   const int                nSearchTimeout
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

Instantiate DirHandle_t when SmDirInitDirInstance() is called. Set nTag to 0 to distinguish the directory instance handle from the user instance handle.

The handle referenced by DirHandle_t is passed to subsequent directory operations functions. You can change the handle value.

Release DirHandle_t when SmDirReleaseInstance() is called. Use the value of nTag to distinguish between the directory instance handle and the user instance handle.

More Information:

Operations on the Directory

SmDirInitUserInstance()

The SiteMinder Policy Server calls SmDirInitUserInstance() before it calls any of the directory entry (user) operations functions on the given directory instance.

SmDirInitUserInstance() can be called multiple times.

Syntax

int SM_EXTERN SmDirInitUserInstance (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void**                   ppInstanceHandle,
   void*                    pDirInstanceHandle,
   const char*              lpszUserDN
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

Instantiate UserHandle_t when SmDirInitUserInstance() is called. Set nTag to 1 to distinguish the user instance handle from the directory instance handle.

The handle referenced by UserHandle_t is passed to subsequent directory entry (user) operations functions. You can change the handle value.

After SiteMinder completes the calls to the relevant directory entry (user) operations functions, it calls SmDirReleaseInstance(). Release UserHandle_t when this call is made. Use the value of nTag to distinguish between the user instance handle and the directory instance handle.

SmDirLookup()

SiteMinder calls SmDirLookup() to look up a pattern in the directory.

Use the following search expression grammar for the search pattern:

[<class> =] <value>

In the search pattern format:

• <class> = empty-string | user | group (empty-string implies user & group)
• <value> = wildcard-string

Your code must be able to interpret a search pattern that begins with the string user=. For example:

...
CStringArray Paths, Classes;
CString szPattern = CString ("user=") + UserDir.m_szUniversalIDAttr
   + CString ("=") + Session.m_szUnivId;
if (m_pDsDir->Lookup (szPattern, Paths, Classes))
....

SiteMinder calls SmDirFreeStringArray() to free the lpszDNs and lpszClasses arrays.

Syntax

int SM_EXTERN SmDirLookup (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszPattern,
   char***                  lpszDNs,
   char***                  lpszClasses
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when you perform a user directory search.

Sample Code Information

When trying the sample code, go to the SiteMinder Administrative UI, navigate to the dialog box for the directory search, and enter the search criteria as follows:

• In the Search drop-down list box, select User.
• In the Search Expression field, enter the exact name of one of the sample users, such as Mikel. Do not use wild cards.

SmDirQueryVersion()

SmDirQueryVersion() queries the Directory API to find out its version and its directory capabilities. Supported capabilities are enumerated in Sm_DirApi_Capability_t.

Syntax

int SM_EXTERN SmDirQueryVersion (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   unsigned long*           pnCapabilities
);

Returns

Returns the version number of the Directory API that the custom library complies with. Currently the versions supported are Sm_Api_Version_V4 and Sm_Api_Version_V4_1. Version constants are defined in SmApi.h.

SmDirRelease()

The Policy Server calls SmDirRelease() when the directory service provider for the Custom Namespace is no longer required.

Syntax

void SM_EXTERN SmDirRelease (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle
);

Remarks

This function is called when you stop one of the Policy Server services.

SmDirReleaseInstance()

The SiteMinder Policy Server calls SmDirReleaseInstance() so that you can release the user instance or the directory instance if you choose.

Syntax

void SM_EXTERN SmDirReleaseInstance (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle
);

Remarks

You need to write your release code so that it will work with the type of instance handle— user or directory—that is passed.

During a process, the SiteMinder Policy Server may first call SmDirInitDirInstance() and then call SmDirInitUserInstance(). If so, the SiteMinder Policy Server calls SmDirReleaseInstance() twice at the end of the process. At the first call, the user instance handle (as pInstanceHandle) is passed so that you can release the user instance. At the second call, the directory instance handle is passed (as pInstanceHandle) so that you can release the directory instance.

Use the value of nTag to distinguish between a user handle and a directory handle, as follows:

• With user handles, nTag in structure DirHandle_t is 0.
• With directory handles, nTag in structure UserHandle_t is 1.

SmDirRemoveEntry()

The SiteMinder Policy Server calls SmDirRemoveEntry() so that you can delete a directory entry (user) from your custom directory.

Examples of directory entries are users, groups and roles. For example, if you are using an SQL database and need to remove a group, you could use SmDirRemoveEntry() to delete the relevant record from the groups table (and all related tables) for the database.

If your directory is hierarchical, as with an LDAP directory, you need to handle the process of deleting relevant data at different levels of the hierarchy. It may be helpful to look at the attributes of the entry, such as object class in LDAP.

Syntax

int SM_EXTERN SmDirRemoveEntry (
   const Sm_Api_Context_t*       lpApiContext,
   void*                         pHandle,
   void*                         pInstanceHandle,
   const Sm_PolicyResolution_t   nEntryType,
   const char*                   lpszEntryDN
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when Delegated Management Services is used to delete directory entries, including groups or roles.

SmDirRemoveMemberFromGroup()

The SiteMinder Policy Server calls SmDirRemoveMemberFromGroup() so that you can remove a user or group from a existing group.

Syntax

int SM_EXTERN SmDirRemoveMemberFromGroup (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszMemberDN,
   const char*              lpszGroupDN
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when Delegated Management Services is used to remove users or groups from groups.

SmDirRemoveMemberFromRole()

The SiteMinder Policy Server calls SmDirRemoveMemberFromRole() so that you can remove a user or group from an assigned role.

Syntax

int SM_EXTERN SmDirRemoveMemberFromRole (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszMemberDN,
   const char*              lpszRoleDN
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when Delegated Management Services is used to remove users or groups from assigned roles.

SmDirSearch()

SiteMinder calls SmDirSearch() to search on the criteria specified in the search filter lpszSearchFilter. You could use SmDirSearch() to execute a query, such as an SQL select, on your custom directory.

In addition to the search filter, the function SmDirSearch() passes directory search parameters. In the SiteMinder Administrative UI, on the Directory Setup tab, you can specify parameters in the following fields:

• Max time
• Max results

The nSearchTimeout and nSearchResults parameters of SmDirSearch() pass the information entered in those fields.

SiteMinder calls SmDirFreeStringArray() to free the lpszDNs array.

Syntax

int SM_EXTERN SmDirSearch (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   char***                  lpszDNs,
   const char*              lpszSearchFilter,
   const char*              lpszSearchRoot,
   const int                nSearchResults,
   const int                nSearchTimeout,
   const int                nSearchScope
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirSearchCount()

Use the function SmDirSearchCount() to return a count of the entries retrieved through the search criteria specified in lpszSearchFilter, subject to the restrictions specified in the directory search parameters. See the Remarks section for more information.

Syntax

int SM_EXTERN SmDirSearchCount (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   int*                     pnCount,
   const char*              lpszSearchFilter,
   const char*              lpszSearchRoot,
   const int                nSearchResults,
   const int                nSearchTimeout,
   const int                nSearchScope
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

In the SiteMinder Policy Server User Interface, on the Directory Setup tab, parameters can be specified in the following fields:

• Parameter—Search root. Its value is passed in through parameter lpszSearchRoot.
• Max time—Maximum search time in seconds. Its value is passed in through parameter nSearchTimeout.
• Max results—Maximum number of results to return. Its value is passed in through parameter nSearchResults.

Note: The string entered in the Parameter field is also passed to lpszParameter for use with SmDirInit() and SmDirInitDirInstance(). If your code for SmDirInit() needs to use lpszParameter and your code for SmDirSearchCount() needs a search root, you will have to parse the string from the Parameter field.

SmDirSetUserAttr()

The SiteMinder Policy Server calls SmDirSetUserAttr() so that you can use SiteMinder to set a user attribute in your custom directory. For example, you may need to change the last name of a user.

Syntax

int SM_EXTERN SmDirSetUserAttr (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const char*              lpszAttrName,
   const char*              lpszAttrData
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirSetUserAttrMulti()

The SiteMinder Policy Server calls SmDirSetUserAttrMulti() so that you can set an array of values for a single attribute in your custom directory.

Syntax

int SM_EXTERN SmDirSetUserAttrMulti (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const char*              lpszAttrName,
   const char**             lpszAttrData
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirSetUserDisabledState()

The SiteMinder Policy Server calls SmDirSetUserDisabledState() when an administrator uses the SiteMinder Policy Server User Interface to disable or enable a user, or Password Services disables a user.

This call gives you the opportunity to set the disabled flag in your custom directory to the disabled reason passed in through nDisabledReason.

When implementing SmDirSetUserDisabledState(), be sure that you have specified which field (or attribute) in the custom directory will hold the disabled reason. In the SiteMinder Policy Server User Interface, specify the attribute name in the Disabled Flag field on the User Attributes tab on the User Directory dialog box. This attribute is passed in through lpszDisabledAttr.

Syntax

int SM_EXTERN SmDirSetUserDisabledState (
   const Sm_Api_Context_t*        lpApiContext,
   void*                          pHandle,
   void*                          pInstanceHandle,
   const char*                    lpszUserDN,
   const char*                    lpszDisabledAttr,
   const Sm_Api_DisabledReason_t  nDisabledReason
);

Note: A user account can be disabled for multiple reasons. Be sure to hold onto the disabled reason(s) and be sure that you don’t overwrite those bits. For example, if the User must change password at next login checkbox is checked and the administrator clicks Disable, the nDisabledReason parameter holds both the Sm_Api_Disabled_PWMustChange bit and the Sm_Api_Disabled_AdminDisabled bit. When the user account is enabled, be sure to clear all the disabled bits.

Returns

Returns 0 if successful or -1 if not successful.

Remarks

To enable a user’s account in the Policy Server User Interface:

1. Navigate to the User Management dialog box.
2. Select the user whose account you are enabling.
3. Click Enable.

To disable a user’s account in the Policy Server User Interface:

1. Navigate to the User Management dialog box.
2. Select the user whose account you are disabling.
3. Click Disable.

Enabled user accounts can also be disabled by using Password Services. For example, you can configure Password Services to disable a user account under the following conditions:

• Inactivity—A specified period of time has elapsed since the user has logged in.
• Failed login attempts—The user has reached a specified number of consecutive failed log in attempts.
• Expired password—The user has failed to make a required password change.
• Forced password change—The user is being forced to change his or her password. On the User Management dialog box, the administrator has checked User must change password at next login.

Sample Code Information

When using the sample, specify the disabled attribute as Disabled. This attribute will be passed in through the parameter lpszDisabledAttr. You can specify the attribute by entering Disabled in the Disabled Flag field on the User Attributes tab of the User Directory dialog box.

In the SiteMinder Policy Server User Interface, in the User Management dialog box, suppose an administrator selects the enabled user Mikel and clicks Disable. Using the sample code, the User DN (lpszUserDN) is Mikel, and the Disabled Attribute (lpszDisabledAttr) is Disabled. The Disabled Reason (nDisabledReason) is Sm_Api_Disabled_AdminDisabled. In the SiteMinder Policy Server User Interface, the User Management dialog box shows that the Current Settings for Mikel have changed from User is enabled to Disabled - administrative.

SmDirValidateInstance()

SiteMinder calls SmDirValidateInstance() so that the Directory API can validate the instance for which the handle is passed.

Either the directory instance handle or user instance handle can be passed through pInstanceHandle. Your code must determine which handle is passed. Check to see if the handle is valid and return the corresponding response.

Syntax

int SM_EXTERN SmDirValidateInstance (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle
);

Returns

Returns 0 if successful or -1 if not successful.

SmDirValidateUserDN()

Use this function to perform any needed validation on the user ID passed in through lpszUserDN.

If you do not need to implement SmDirValidateUserDN(), return 0, as shown in the sample code.

Syntax

int SM_EXTERN SmDirValidateUserDN (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when you use the SiteMinder Test Tool to run IsAuthenticated for a user in the custom directory.

SmDirValidateUsername()

SiteMinder calls this function to validate the user name passed in through lpszUsername.

You can use this function to resolve the user name and copy the user ID into the lpszNewUsername buffer. If you choose not to implement SmDirValidateUsername(), set lpszNewUsername to NULL, as shown in the sample.

SiteMinder calls SmDirFreeString() to free the lpszNewUsername buffer.

Syntax

int SM_EXTERN SmDirValidateUsername (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUsername,
   char**                   lpszNewUsername
);

Returns

Returns 0 if successful or -1 if not successful.

Remarks

This function is called when you use the SiteMinder Test Tool to run IsAuthenticated for a user in the custom directory.

SmDirValidateUserPolicyRelationship()

Use SmDirValidateUserPolicyRelationship() to validate the relationship between policy objects. Determine whether the user distinguished name has the specified relationship to the policy distinguished name. The relationship is passed in through nPolicyResolution.

For example:

• If nPolicyResolution is Sm_PolicyResolution_User, determine whether the user passed in through lpszUserDN is the same user that is passed in through lpszPolicyDN.
• If nPolicyResolution is Sm_PolicyResolution_UserGroup, determine whether the user passed in through lpszUserDN is a member of the group passed in through lpszPolicyDN.

Syntax

int SM_EXTERN SmDirValidateUserPolicyRelationship (
   const Sm_Api_Context_t*      lpApiContext,
   void*                        pHandle,
   void*                        pInstanceHandle,
   const char*                  lpszUserDN,
   const Sm_PolicyResolution_t  nPolicyResolution,
   const int                    bRecursive,
   const char*                  lpszPolicyDN,
   const char*                  lpszPolicyClass
);

Returns

Returns 0 if successful or -1 if not successful.

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.