Programming Guides › Programming Guide for C › Directory API › Sequence of Function Calls › SmDirInitDirInstance()

Previous Topic: SmDirInit()

Next Topic: SmDirInitUserInstance()
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
);

Parameter

I/O

Description

lpApiContext

I

Pointer to the API context structure.

pHandle

I

The address of the pointer returned by SmDirInit().

ppInstanceHandle

O

Use this parameter to set the handle for the directory instance. For example, you could use ppInstanceHandle to hold information about a connection to the directory.

At the end of the directory instance lifecycle, the SiteMinder Policy Server calls SmDirReleaseInstance() and passes the directory instance handle so that you can delete the handle.

lpszUniqueKey

I

A unique identifier for the directory instance session. This unique key holds the object identifier (OID) of the custom directory object.

lpszParameter

I

The null-terminated string specified in the Parameter field of the SiteMinder User Directory Dialog box. The value is the same as it was for the call to SmDirInit().

lpszUsername

I

The string containing the user name as specified in the Credentials and Connection tab of the SiteMinder User Directory Dialog box.

When bRequireCredentials is set to true, lpszUsername holds the value in the Username field in the Administrator Credentials group box.

lpszPassword

I

The string containing the password as specified in the Credentials and Connection tab of the SiteMinder User Directory Dialog box.

When bRequireCredentials is set to true, lpszPassword holds the value in the Password field in the Administrator Credentials group box.

bRequireCredentials

I

This boolean indicates whether credentials are required for user directory access.

In the SiteMinder Administrative UI, on the Credentials and Connection tab, in the Administrator Credentials group box, there is a Require Credentials check box. Checking this check box sets bRequireCredentials to true (1). When bRequireCredentials is set to true, lpszUsername and lpszPassword will hold the values in the Username and Password fields in the Administrator Credentials group box. The SiteMinder Policy Server uses these credentials to access the directory.

bSecureConnection

I

This boolean indicates whether an SSL connection is required to access the user directory.

nSearchResults

I

This parameter indicates the maximum number of records to return as the result set of a single search by the Directory API. In the SiteMinder User Directory Dialog box, on the Directory Setup tab, in the Custom NameSpace group box, there is a Max results field. The nSearchResults parameter holds the value in the Max results field.

nSearchTimeout

I

This parameter indicates the time in seconds after which the Directory API will stop searching the user directory for results. In the SiteMinder User Directory Dialog box, on the Directory Setup tab, in the Custom NameSpace group box, there is a Max time field. The nSearchResults parameter holds the value in the Max time field.

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

Copyright © 2010 CA. All rights reserved. Email CA about this topic