Sm_PolicyApi

Programming Guides › Programming Guide for C › Policy Management API Guidance › Function Declarations for the Policy Management API › Sm_PolicyApi_Login()

Sm_PolicyApi_Login()

After initialization, a successful call to Sm_PolicyApi_Login() is a prerequisite to making any further function calls. This function checks the administrator's login credentials (username and password). If the API detects an uninitialized or improperly initialized init handle, an error is generated. If the administrator is authenticated, the function initializes internal data structures and resources. Once the administrator is logged in, the Policy Server initializes a session handle, which is used as an input parameter to all the Policy Management API functions.

Internally, the session handle contains data structures and context information required for the operation of the Policy Management API, including the client session data (from the init handle) and the administrator session data. The data structures and context information are transparent to the caller.

You can call Sm_PolicyApi_Login() to initialize a session handle without checking the administrator's credentials or without specifying any administrator. To log in under either of these circumstances, set the parameter nCheckCreds to false. See the description of the nCheckCreds parameter for more information.

This function can be called more than once during the client session and depends on the successful initialization of the Policy Store connection.

Type

Required function.

Syntax

int SM_EXTERN Sm_PolicyApi_Login (
   void*           pInitHandle,
   void**          ppSessionHandle,
   int             nCheckCreds,
   const char*     pszUserName,
   const char*     pszPassword,
   const char*     pszClientIP,
   char**          pszUserMsg,
   char**          pszErrMsg
);

Parameter	I/O	Description
pInitHandle	I	A pointer to an internal Policy Management API data structure. This is the init handle returned by Sm_PolicyApi_Init().
ppSessionHandle	O	A pointer to an internal Policy Management API data structure (a different instance of the structure from pInitHandle). The structure contains administrator session data. The session handle is transparent to the caller.
nCheckCreds	I	Flag indicating whether to check the credentials of the administrator, as follows: If nCheckCreds is false and an empty string ( "" ) is passed in pszUserName, no credential checking is done, and the caller is granted all administrator rights. If nCheckCreds is false and a user name is passed in pszUserName, no credential checking is done. However, the passed name must be that of a valid SiteMinder administrator. The caller is granted rights defined for the administrator. If nCheckCreds is true, both the user name and the password are verified and should match a valid SiteMinder administrator. The caller is granted rights defined for the administrator.
pszUserName	I	User Name of the Policy Management API administrator. If you pass in an empty string ( "" ) and set nCheckCreds to false, no administrator name and password are required. The caller is granted all administrator rights.
pszPassword	I	Password of the Policy Management API administrator.
pszClientIP	I	IP address of the machine the administrator is logging from.
pszUserMsg	O	User message returned by the Policy Management API. You release the memory allocated for this variable by calling Sm_PolicyApi_FreeString().
pszErrMsg	O	Error message returned by the Policy Management API. You release the memory allocated for this variable by calling Sm_PolicyApi_FreeString().

Returns

Sm_PolicyApi_Success. The login was successful.
Sm_PolicyApi_Failure. Memory cannot be allocated.
Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
Sm_PolicyApi_NoPrivilege. The administrator does not have privileges to some or all the domains.
Sm_PolicyApi_ErrorLogin. The authentication failed.

Example

See the Sm_PolicyApi_Login() call in the example application smpolicyapiexample.cpp.