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.
casso126
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,
intnCheckCreds,
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
CA Single Sign-On
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
CA Single Sign-On
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.