Sm_PolicyApi_GetPasswordMsg()
Gets information about an error that occurred during an attempt to validate a new password.
casso127
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:
- As a result of the failed password validation attempt, Sm_PolicyApi_SetPassword() returns Sm_PolicyApi_InvalidPasswordSyntax.
- The Policy Management application responds by calling Sm_PolicyApi_GetPasswordMsg(), passing the encoded error message returned from Sm_PolicyApi_SetPassword() in thepszPasswordMsgparameter.
- When Sm_PolicyApi_GetPasswordMsg() returns:
- nMsgIdcontains Sm_PolicyApi_PasswordMsgId_PasswordShort
- ppStructMsgFieldpoints 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. |