Sm_PolicyApi_SetDisabledUserState()

Sets the disabled state of a user. You can also enable a user with this function.
casso10
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 beset in the user directory (the
pszDisabledAttr
field of structure Sm_PolicyApi_UserDir_t). You can also set the attribute using the Administrative UI.
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_tnDisabledReason,
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 stateiRes = 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);