IsCallerInRole

Description

Indicates whether the direct caller of a COM object running on COM+ is in a specified role (either individually or as part of a group).

Applies to

TransactionServer objects

Syntax

transactionserver.IsCallerInRole ( role )

Argument

Description

transactionserver

Reference to the TransactionServer service instance

role

A string expression containing the name of a role


Return value

Boolean.

Returns true if the direct caller is in the specified role and false if it is not.

Usage

In COM+, a role is a name that represents the set of access permissions for a specific user or group of users. For example, a component that provides access to a sales database might have different roles for managers and salespersons.

In your code, you use IsCallerInRole to determine whether the caller of the current method is associated with a specific role before you execute code that performs a task restricted to users in that role.

IsCallerInRole only determines whether the direct caller of the current method is in the specified role. The direct caller may be either a client process or a server process.

Package must run in a dedicated server process

To support role-checking, the COM+ package must be activated as a Server package, not a Library package. Server packages run in a dedicated server process. Library packages run in the creator's process and are used primarily for debugging.

IsCallerInRole only returns a meaningful value when security checking is enabled. Security checking can be enabled in the COM/COM+ Project wizard or the Project painter

Examples

The following example shows a call to a function (f_checkrole) that takes the name of a role as an argument and returns an integer. In this example only managers can place orders with a value over $20,000:

integer rc
long ordervalue
IF ordervalue > 20,000 THEN
    rc = f_checkrole("Manager")
    IF rc <> 1
    // handle negative values and exit
    ELSE
    // continue processing
    END IF 
END IF

The f_checkrole function checks whether a component is running on COM+ and if security checking is enabled. Then it checks whether the direct caller is in the role passed in as an argument. If any of the checks fail, the function returns a negative value:

TransactionServer ts
integer li_rc
string str_role 
 
li_rc = GetContextService( "TransactionServer", ts)
// handle error if necessary
 
// Find out if running on COM+
IF ts.which() <> 2 THEN RETURN -1
 
// Find out if security is enabled
IF NOT ts.IsSecurityEnabled() THEN RETURN -2
 
// Find out if the caller is in the role
IF NOT ts.IsCallerInRole(str_role) THEN
    RETURN -3
ELSE
    RETURN 1
END IF  

See also

ImpersonateClient

IsImpersonating

IsSecurityEnabled

RevertToSelf