Sm_PolicyApi_GetPasswordMsg()

Gets information about an error that occurred during an attempt to validate a new password.
sm1252sp1
Gets information about an error that occurred during an attempt to validate a new password.
Call this function when Sm_PolicyApi_SetPassword() returns the error code Sm_PolicyApi_InvalidPasswordSyntax.
Type
User and user state function.
Syntax
int SM_EXTERN Sm_PolicyApi_GetPasswordMsg (
void*
pSessionHandle
,
const char*
pszPasswordMsg
,
unsigned int*
nVersion
,
unsigned int*
nMsgId
,
unsigned int*
nArgs
,
Sm_PolicyApi_PasswordMsgField_t**
ppStructMsgField
);
Parameter
I/O
Description
pSessionHandle
I
A pointer to an internal Policy Management API data structure. The structure holds information about the administrator session and the client session.
pszPasswordMsg
I
Encoded error message returned in the
pszErrMsg
parameter of the function Sm_PolicyApi_SetPassword().
nVersion
O
The version of the
CA Single Sign-On
password services.
nMsgId
O
The password services message identifier retrieved for the encoded error message. Message identifiers are enumerated in Sm_PolicyApi_PasswordMsgId_t.
nArgs
O
The number of fields in the Sm_PolicyApi_PasswordMsgField_t structure referenced by
ppStructMsgField
.
ppStructMsgField
O
The address of a pointer to an Sm_PolicyApi_PasswordMsgField_t structure containing the password error message information.
 
Remarks
CA Single Sign-On
password services errors contain a unique message identifier. Amessage identifier (enumerated in Sm_PolicyApi_PasswordMsgId_t) is returned in the
nMsgId
parameter of the function Sm_PolicyApi_GetPasswordMsg().
Further, each message identifier is associated with additional information about the error. This additional information is referenced by a field identifier (enumerated in Sm_PolicyApi_PasswordMsgFieldId_t).
For example, suppose an administrator sets the minimum length of a password to seven characters. If a user tries to validate a new password containing just six characters, the following events can occur:
  1. As a result of the failed password validation attempt, Sm_PolicyApi_SetPassword() returns Sm_PolicyApi_InvalidPasswordSyntax.
  2. The Policy Management application responds by calling Sm_PolicyApi_GetPasswordMsg(), passing the encoded error message returned from Sm_PolicyApi_SetPassword() in the
    pszPasswordMsg
    parameter.
  3. When Sm_PolicyApi_GetPasswordMsg() returns:
    • nMsgId
      contains Sm_PolicyApi_PasswordMsgId_PasswordShort
    • ppStructMsgField
      points to an Sm_PolicyApi_PasswordMsgField_t structure containing the following additional information about the password error:
Field
Value and Meaning
iStructId
Sm_PolicyApi_PasswordMsgField_ID.
The error information relates to a password policy.
nId
Sm_PolicyApi_PasswordMsgField_Id_Min.
The error violates a minimum character requirement for the password (the minimum password length).
nType
Sm_PolicyApi_FieldType_Int.
The error description is an integer, so
nValue
is filled and
pszMsg
is not.
pszMsg
"".
Not applicable to this error.
nValue
7.
The minimum password length. The length of the requested password was less than this value.