Edit

Share via

IObjectContext::IsCallerInRole method (comsvcs.h)

  • Article

Indicates whether the object's direct caller is in a specified role (either directly or as part of a group).

Syntax

HRESULT IsCallerInRole(
  [in]  BSTR bstrRole,
  [out] BOOL *pfIsInRole
);

Parameters

[in] bstrRole

The name of the role.

[out] pfIsInRole

TRUE if the caller is in the specified role; FALSE if not. This parameter is also set to TRUE if security is not enabled.

Return value

This method can return 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 pbIsInRole parameter indicates whether the caller is in that role.
CONTEXT_E_ROLENOTFOUND
 The role specified in the bstrRole parameter does not exist.
E_INVALIDARG
 One or more of the arguments passed in is not valid.
E_UNEXPECTED
 An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object and the other object calls IsCallerInRole using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

Remarks

You use this method to determine whether the direct caller of the currently executing method is associated with a specific role. A role is a symbolic name that represents a user or group of users who have specific access permissions to all components in a given COM+ application. Developers define roles when they create a component, and roles are mapped to individual users or groups at deployment time.

IsCallerInRole applies only to the direct caller of the currently executing method. (The direct caller is the process calling into the current server process. It can be either a base client process or a server process.) IsCallerInRole does not apply to the process that initiated the call sequence from which the current method was called or to any other callers in that sequence.

Because IsCallerInRole returns TRUE when the object that invokes it is executing in a client's process, it's a good idea to call IsSecurityEnabled before calling IsCallerInRole. If security isn't enabled, IsCallerInRole will not return an accurate result.

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

IObjectContext