Sm_PolicyApi_GetPasswordMsg()

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

Sm_PolicyApi_GetPasswordMsg()

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 SiteMinder 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

SiteMinder password services errors contain a unique message identifier. A message 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 the pszPasswordMsg parameter.
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.