Sm_PolicyApi_SetDisabledUserState()

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

Sm_PolicyApi_SetDisabledUserState()

Sets the disabled state of a user. You can also enable a user with this function.

To make this function work, the attribute for tracking disabled users must be set in the user directory (the pszDisabledAttr field of structure Sm_PolicyApi_UserDir_t). You can also set the attribute using the Policy Server User Interface.

Type

User and user state function.

Syntax

int SM_EXTERN Sm_PolicyApi_SetDisabledUserState (
   void*                            pSessionHandle,
   const char*                      pszUserDirOid,
   const char*                      pszUserDN,
   const Sm_Api_DisabledReason_t    nDisabledReason,
   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 an existing user directory.
pszUserDN	I	The distinguished name of the user whose disabled state is to be changed.
nDisabledReason	I	Reason for disabling or enabling a user. The reasons are enumerated in Sm_Api_DisabledReason_t, which is defined in SmApi.h. It is the responsibility of the caller to set the correct state. Multiple reasons can exist concurrently. When a user is enabled, all the flags in the disabled mask should be cleared.
pszErrMsg	O	The error message is held in the string if the operation was not successful. You release the memory allocated for this variable by calling Sm_PolicyApi_FreeString().

Returns

Sm_PolicyApi_Success. The disable user state was set successfully.
Sm_PolicyApi_Failure:
- User state was not disabled.
- Memory could not be allocated to pszErrMsg.
Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
Sm_PolicyApi_NoSession. There is no valid administrator session.
Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege to set disabled user state.
Sm_PolicyApi_InvalidOid. The user directory OID was not found.

Examples

To disable a user for password expiration:

nDisabledReason = Sm_Api_Disabled_DisabledMask &
      Sm_Api_Disabled_PWExpired;

To disable a user for administrative reasons:

enum Sm_Api_DisabledReason_t nDisabledReason;

iRes =  Sm_PolicyApi_GetDisabledUserState (pSessionHandle,
                                           pszUserDirOid,
                                           pszUserDN,
                                           &nDisabledReason,
                                           &pszGetErrMsg);

if (iRes != Sm_PolicyApi_Success)
{
    cout << "Error: " << pszGetErrMsg << endl;
}

// Set admin disabled reason bit.
nDisabledReason=(Sm_Api_DisabledReason_t) (nDisabledReason | 
      Sm_Api_Disabled_AdminDisabled);

// Set Disable user state
iRes = Sm_PolicyApi_SetDisabledUserState(pSessionHandle,
                                         pszUserDirOid,
                                         pszUserDN,
                                         nDisabledReason,
                                         &pszSetErrMsg);

To enable a user and clear all disable reason bits:

enum Sm_Api_DisabledReason_t nDisabledReason;
iRes = Sm_PolicyApi_GetDisabledUserState(pSessionHandle,
                                         pszUserDirOid,
                                         pszUserDN,
                                         &nDisabledReason,
                                         &pszGetErrMsg);

if (iRes != Sm_PolicyApi_Success)
{
   if (pszGetErrMsg)
   {
      cout << "Error: " << pszGetErrMsg << endl;
   }
}
// Clear all the disable reason bits.
nDisabledReason=(Sm_Api_DisabledReason_t)
      (nDisabledReason & (~Sm_Api_Disabled_DisabledMask));

// Set Disable user state to enable
iRes = Sm_PolicyApi_SetDisabledUserState(pSessionHandle,
                                         pszUserDirOid,
                                         pszUserDN,
                                         nDisabledReason,
                                         &pszSetErrMsg);