SmDirInitDirInstance()

stmndr 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.
casso126
CA Single Sign-On
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
CA Single Sign-On
completes the directory function call, it calls SmDirReleaseInstance(). This function is called multiple times.
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
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.