Edit

Share via

ISecurityCallContext::IsUserInRole method (comsvcs.h)

  • Article

Determines whether the specified user is in the specified role.

Syntax

HRESULT IsUserInRole(
  [in]  VARIANT      *pUser,
  [in]  BSTR         bstrRole,
  [out] VARIANT_BOOL *pfInRole
);

Parameters

[in] pUser

A pointer to value holding the User ID of the user whose role membership is to be checked. If you intend to pass the security identifier (SID) to IsUserInRole, this parameter should meet the following requirements: V_VT(pUser) == (VT_ARRAY|VT_UI1) && V_ARRAY(pUser)->cDims == 1.

[in] bstrRole

The name of the role.

[out] pfInRole

TRUE if the user is in the specified role; FALSE if not. If the specified role is not defined for the application, FALSE is returned. This parameter is set to TRUE if role-based security is not enabled.

Return value

This method can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following values.

Return code Description
S_OK
 The role specified in the bstrRole parameter is a recognized role, and the Boolean result returned in the pfIsInRole parameter indicates whether the user is in that role.
CONTEXT_E_ROLENOTFOUND
 The role specified in the bstrRole parameter does not exist.

Remarks

Use this method to limit access to sections of code that should not be executed unless the caller is a member of the specified role. Windows groups and users are assigned to an application's roles using the Component Services administration tool. For more information about roles, see Role-Based Security.

Because IsUserInRole is TRUE when role-based security is not enabled, it is a good idea to call IsSecurityEnabled before calling IsUserInRole to ensure that IsUserInRole returns useful information.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header comsvcs.h

See also

ISecurityCallContext

Programmatic Component Security