ISecurityCallContext::IsCallerInRole method (comsvcs.h)

Article
10/13/2021

Determines whether the direct caller is in the specified role.

Syntax

HRESULT IsCallerInRole(
  [in]  BSTR         bstrRole,
  [out] VARIANT_BOOL *pfInRole
);

Parameters

[in] bstrRole

The name of the role.

[out] pfInRole

TRUE if the caller 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 caller 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.

IsCallerInRole only applies to the direct caller of the currently executing method. IsCallerInRole does not apply to any other caller in the call sequence from which the current method was called. However, you can obtain information about other callers in the sequence by using the get_Item property method to get the Callers property of the security call context object.

Because IsCallerInRole is TRUE when role-based security is not enabled, it is a good idea to call IsSecurityEnabled before calling IsCallerInRole to ensure that IsCallerInRole 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