Sm_PolicyApi_SetPassword()

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

Sm_PolicyApi_SetPassword()

Changes the password of a user account. It can also be used to validate a new password or an old password without changing the password.

To validate a new password, you must set SiteMinder Password services for the directory, and you must identify a password attribute in the SiteMinder user directory.

Type

User and user state function.

Syntax

int SM_EXTERN Sm_PolicyApi_SetPassword (
   void*          pSessionHandle,
   const char*    pszUserDirOid,
   const char*    pszUserDN,
   const char*    pszNewPassword,
   const char*    pszOldPassword,
   bool           bChangePassword,
   bool           bValidateNewPassword,
   bool           bValidateOldPassword,
   char**         pszErrMsg
);

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.
pszUserDirOid	I	A null-terminated string containing the object identifier of the user directory where the user may be found.
pszUserDN	I	The distinguished name of the user whose password is to be changed and/or whose new or old password is to be validated.
pszNewPassword	I	New user password to validate or change.
pszOldPassword	I	Old user password to validate or change.
bChangePassword	I	If true, the password is changed to the new password and is recorded in the user's password history. If an error occurs, the function returns an error code.
bValidateNewPassword	I	If true, the new password is checked to make sure it satisfies all password policy requirements. If the new password is in violation of any password policies, pszErrMsg is set and the function returns an error code.
bValidateOldPassword	I	If true, the old password is used to authenticate the user. If authentication fails, the function returns an error code.
pszErrMsg	O	String containing an error message if the user password change or validation was not successful. You release the memory allocated for this variable by calling Sm_PolicyApi_FreeString().

Returns

Sm_PolicyApi_Success. The change or validation was successful.
Sm_PolicyApi_Failure. The change or validation was not successful or memory could not be allocated to the error message string.
Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
Sm_PolicyApi_InvalidPasswordSyntax. Returned when both of these conditions exist:
- bValidateNewPassword is true.
- The new password did not satisfy the password policy requirements set for the specified directory.
For information about the error, call Sm_PolicyApi_GetPasswordMsg() and pass to it the encoded error message (pszErrMsg) returned from Sm_PolicyApi_SetPassword().
Sm_PolicyApi_NoSession. There is no valid administrator session.
Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to set or validate user passwords.
Sm_PolicyApi_InvalidOid. The user directory OID was not found.