SmDirGetUserDisabledState()

Programming Guides › Programming Guide for C › Directory API Guidance › Directory API Reference › SmDirGetUserDisabledState()

SmDirGetUserDisabledState()

The SiteMinder Policy Server calls SmDirGetUserDisabledState() to get information about whether a user account is disabled.

If a user account is disabled, SmDirGetUserDisabledState() returns information in pnDisabledReason about how the account was disabled.

The possible reasons that a user is disabled are enumerated in Sm_Api_DisabledReason_t, which is defined in SmApi.h. The disabled reason is set when the SiteMinder Policy Server calls SmDirSetUserDisabledState().

If the custom directory does not support a disabled flag, use the following code to indicate that the user is always enabled:

*pnDisabledReason = Sm_Api_Disabled_Enabled;
return 0;

Syntax

int SM_EXTERN SmDirGetUserDisabledState (
   const Sm_Api_Context_t*   lpApiContext,
   void*                     pHandle,
   void*                     pInstanceHandle,
   const char*               lpszUserDN,
   const char*               lpszDisabledAttr,
   Sm_Api_DisabledReason_t*  pnDisabledReason
);

Parameter	I/O	Description
lpApiContext	I	Pointer to the API context structure.
pHandle	I	The address of the pointer returned by SmDirInit().
pInstanceHandle	I	The address of a pointer to the user instance handle.
pszUserDN	I	Buffer containing the user DN whose disabled state has to be retrieved.
lpszDisabledAttr	I	The user directory attribute that is used by SiteMinder to track disabled users. Use this attribute to retrieve the disabled state.
pnDisabledReason	O	Attribute containing the user disabled state of the user. Store the user-disabled state that is fetched from the user directory attribute specified in lpszDisabledAttr.

Returns

Return values indicate whether the function successfully determines the user’s disabled state:

Return 0 if the function successfully determines the user’s disabled state.
Return -1 if the function fails to determine the user’s disabled state.

Return values do not indicate the disabled state, which is stored in the parameter pnDisabledReason.

Remarks

This function is called in the following circumstances:

When searching for a user, after calling SmDirLookup() to perform the lookup.
After calling SmDirSetUserDisabledState() to change the disabled state of a user.
After calling SmDirAuthenticateUser() to authenticate a user. If the disabled flag is set for a user, SiteMinder does not authenticate the user—even if the user supplies valid credentials.

Sample Code Information

If you are managing users, when you lookup the user, SiteMinder checks the disabled state for that user by checking lpszDisabledAttr. To indicate the name of the directory attribute that holds this information, in the SiteMinder Administrative UI, in the User Directory Dialog box, on the User Attributes tab, complete the Disabled Flag field. To use the sample, type Disabled in this field.

If the user is enabled, then running the sample code results in a value of Sm_Api_Disabled_Enabled for pnDisabledReason. If the SiteMinder administrator has used the Disable button to disable the user, then running the sample code results in a value of Sm_Api_Disabled_AdminDisabled for pnDisabledReason.