Client-side handle to a session with a server. More...

#include <e32std.h>

Inheritance diagram for RSessionBase:

Public Types
enum	TAttachMode { EExplicitAttach , EAutoAttach }
	Indicates whether or not threads in the process are automatically attached to the session when passed as a parameter to the Share() function. More...

Public Types inherited from RHandleBase
enum	TAttributes { EReadAccess =0x1 , EWriteAccess =0x2 , EDirectReadAccess =0x4 , EDirectWriteAccess =0x8 }
	Read/Write attributes for the handle. More...

Public Member Functions
TInt	ShareAuto ()
	Creates a session that can be shared by other threads in the current process.

TInt	ShareProtected ()
	Creates a session handle that can be be passed via IPC to another process as well as being shared by other threads in the current process.

IMPORT_C TInt	Open (RMessagePtr2 aMessage, TInt aParam, TOwnerType aType=EOwnerProcess)
	Opens a handle to a session using a handle number sent by a client to a server.

IMPORT_C TInt	Open (RMessagePtr2 aMessage, TInt aParam, const TSecurityPolicy &aServerPolicy, TOwnerType aType=EOwnerProcess)
	Opens a handle to a session using a handle number sent by a client to a server, and validate that the session's server passes a given security policy.

IMPORT_C TInt	Open (TInt aArgumentIndex, TOwnerType aType=EOwnerProcess)
	Opens a handle to a session using a handle number passed as an environment data item to the child process during the creation of that child process.

IMPORT_C TInt	Open (TInt aArgumentIndex, const TSecurityPolicy &aServerPolicy, TOwnerType aType=EOwnerProcess)
	Opens a handle to a session using a handle number passed as an environment data item to the child process during the creation of that child process, after validating that the session's server passes the given security policy.

TInt	SetReturnedHandle (TInt aHandleOrError)
	Sets the handle-number of this handle to the specified value.

IMPORT_C TInt	SetReturnedHandle (TInt aHandleOrError, const TSecurityPolicy &aServerPolicy)
	Sets the handle-number of this session handle to the specified value after validating that the session's server passes a given security policy.

Public Member Functions inherited from RHandleBase
	RHandleBase ()
	Default constructor.

TInt	Handle () const
	Retrieves the handle-number of the object associated with this handle.

void	SetHandle (TInt aHandle)
	Sets the handle-number of this handle to the specified value.

TInt	SetReturnedHandle (TInt aHandleOrError)
	Sets the handle-number of this handle to the specified value.

IMPORT_C void	Close ()
	Closes the handle.

IMPORT_C TName	Name () const
	Gets the name of the handle.

IMPORT_C TFullName	FullName () const
	Gets the full name of the handle.

IMPORT_C void	FullName (TDes &aName) const
	Gets the full name of the handle.

IMPORT_C void	SetHandleNC (TInt aHandle)
	Sets the handle-number of this handle to the specified value, and marks it as not closable.

IMPORT_C TInt	Duplicate (const RThread &aSrc, TOwnerType aType=EOwnerProcess)
	Creates a valid handle to the kernel object for which the specified thread already has a handle.

IMPORT_C void	HandleInfo (THandleInfo *anInfo)
	Gets information about the handle.

IMPORT_C TUint	Attributes () const

IMPORT_C TInt	BTraceId () const
	Returns a unique object identifier for use with BTrace.

IMPORT_C void	NotifyDestruction (TRequestStatus &aStatus)
	Internal technology API.

Protected Member Functions
TInt	CreateSession (const TDesC &aServer, const TVersion &aVersion)
	Creates a session with a server, specifying no message slots.

IMPORT_C TInt	CreateSession (const TDesC &aServer, const TVersion &aVersion, TInt aAsyncMessageSlots)
	Creates a session with a server.

IMPORT_C TInt	CreateSession (const TDesC &aServer, const TVersion &aVersion, TInt aAsyncMessageSlots, TIpcSessionType aType, const TSecurityPolicy aPolicy=0, TRequestStatus aStatus=0)
	Creates a session with a server.

TInt	CreateSession (RServer2 aServer, const TVersion &aVersion)
	Creates a session with a server, specifying no message slots.

IMPORT_C TInt	CreateSession (RServer2 aServer, const TVersion &aVersion, TInt aAsyncMessageSlots)
	Creates a session with a server.

IMPORT_C TInt	CreateSession (RServer2 aServer, const TVersion &aVersion, TInt aAsyncMessageSlots, TIpcSessionType aType, const TSecurityPolicy aPolicy=0, TRequestStatus aStatus=0)
	Creates a session with a server.

TInt	CreateSession (const TDesC &aServer, const TVersion &aVersion, TInt aAsyncMessageSlots, TRequestStatus *aStatus)

TInt	Send (TInt aFunction, const TIpcArgs &aArgs) const
	Issues a blind request to the server with the specified function number, and arguments.

void	SendReceive (TInt aFunction, const TIpcArgs &aArgs, TRequestStatus &aStatus) const
	Issues an asynchronous request to the server with the specified function number and arguments.

TInt	SendReceive (TInt aFunction, const TIpcArgs &aArgs) const
	Issues a synchronous request to the server with the specified function number and arguments.

TInt	Send (TInt aFunction) const
	Issues a blind request to the server with the specified function number, but with no arguments.

void	SendReceive (TInt aFunction, TRequestStatus &aStatus) const
	Issues an asynchronous request to the server with the specified function number, but with no arguments.

TInt	SendReceive (TInt aFunction) const
	Issues a synchronous request to the server with the specified function number, but with no arguments.

Protected Member Functions inherited from RHandleBase
	RHandleBase (TInt aHandle)
	Copy constructor.

IMPORT_C TInt	Open (const TFindHandleBase &aHandle, TOwnerType aType)
	Opens a handle to a kernel side object found using a find-handle object.

TInt	OpenByName (const TDesC &aName, TOwnerType aOwnerType, TInt aObjectType)
	Implementation for RXxxxx::Open/OpenGlocbal(const TDesC &aName,,TOwnerType aType) functions.

Static Protected Member Functions
static TInt	SetReturnedHandle (TInt aHandleOrError, RHandleBase &aHandle)

Static Protected Member Functions inherited from RHandleBase
static TInt	SetReturnedHandle (TInt aHandleOrError, RHandleBase &aHandle)

Friends
class	RSubSessionBase

Additional Inherited Members
Static Public Member Functions inherited from RHandleBase
static void	DoExtendedClose ()

Protected Attributes inherited from RHandleBase
TInt	iHandle

Detailed Description

Client-side handle to a session with a server.

This is the client-side interface through which communication with the server is channelled.

Clients normally define and implement a derived class to provide a richer interface.

API status: Published to all clients. Released API.

Definition at line 4610 of file e32std.h.

Member Enumeration Documentation

◆ TAttachMode

enum RSessionBase::TAttachMode

Indicates whether or not threads in the process are automatically attached to the session when passed as a parameter to the Share() function.

Enumerator
EExplicitAttach
EAutoAttach

Definition at line 4618 of file e32std.h.

Member Function Documentation

◆ CreateSession() [1/7]

TInt RSessionBase::CreateSession	(	const TDesC &	aServer,
		const TVersion &	aVersion
	)

inlineprotected

Creates a session with a server, specifying no message slots.

It should be called as part of session initialisation in the derived class.

Message slots are not pre-allocated for the session but are taken from a system-wide pool allowing up to 255 asynchronous messages to be outstanding. This raises a risk of failure due to lack of memory and, therefore, this mode of operation is not viable for sessions that make guarantees about the failure modes of asynchonous services.

Parameters

aServer	The name of the server with which a session is to be established.
aVersion	The lowest version of the server with which this client is compatible

(generated from Symbian Developer Library)

◆ CreateSession() [2/7]

IMPORT_C TInt RSessionBase::CreateSession	(	const TDesC &	aServer,
		const TVersion &	aVersion,
		TInt	aAsyncMessageSlots
	)

protected

Creates a session with a server.

It should be called as part of session initialisation in the derived class.

Parameters

aServer	The name of the server with which a session is to be established.
aVersion	The lowest version of the server with which this client is compatible.
aAsyncMessageSlots	The number of message slots available to this session. This determines the number of outstanding requests the client may have with the server at any one time. The maximum number of slots is 255. If aAsyncMessageSlots==-1 then this indicates that the session should use messages from the global free pool of messages.

(generated from Symbian Developer Library)

◆ CreateSession() [3/7]

IMPORT_C TInt RSessionBase::CreateSession	(	const TDesC &	aServer,
		const TVersion &	aVersion,
		TInt	aAsyncMessageSlots,
		TIpcSessionType	aType,
		const TSecurityPolicy *	aPolicy = `0`,
		TRequestStatus *	aStatus = `0`
	)

protected

Creates a session with a server.

It should be called as part of session initialisation in the derived class.

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

Parameters

aServer	The name of the server with which a session is to be established.
aVersion	The lowest version of the server with which this client is compatible.
aAsyncMessageSlots	The number of message slots available to this session. This determines the number of outstanding requests the client may have with the server at any one time. The maximum number of slots is 255. If aAsyncMessageSlots==-1 then this indicates that the session should use messages from the global free pool of messages.
aType	The type of session to create. See TIpcSessionType.
aPolicy	A pointer to a TSecurityPolicy object. If this pointer is not 0 (zero) then the policy is applied to the process in which the server is running. If that process doesn't pass this security policy check, then the session creation will fail with the error KErrPermissionDenied. This security check allows clients to verify that the server has the expected Platform Security attributes.
aStatus	A pointer to TRequestStatus object which will be signalled when the session has been created, or in the event of an error. If aStatus==0 then session creation is done synchronously.

(generated from Symbian Developer Library)

◆ CreateSession() [4/7]

TInt RSessionBase::CreateSession	(	const TDesC &	aServer,
		const TVersion &	aVersion,
		TInt	aAsyncMessageSlots,
		TRequestStatus *	aStatus
	)

inlineprotected

Deprecated:: Use CreateSession(const TDesC& aServer,const TVersion& aVersion,TInt aAsyncMessageSlots,TIpcSessionType aType,const TSecurityPolicy* aPolicy=0, TRequestStatus* aStatus=0);

Definition at line 4682 of file e32std.h.

◆ CreateSession() [5/7]

TInt RSessionBase::CreateSession	(	RServer2	aServer,
		const TVersion &	aVersion
	)

inlineprotected

Creates a session with a server, specifying no message slots.

It should be called as part of session initialisation in the derived class.

Message slots are not pre-allocated for the session but are taken from a system-wide pool allowing up to 255 asynchronous messages to be outstanding. This raises a risk of failure due to lack of memory and, therefore, this mode of operation is not viable for sessions that make guarantees about the failure modes of asynchonous services.

Parameters

aServer	A handle to a server with which a session is to be established.
aVersion	The lowest version of the server with which this client is compatible

(generated from Symbian Developer Library)

◆ CreateSession() [6/7]

IMPORT_C TInt RSessionBase::CreateSession	(	RServer2	aServer,
		const TVersion &	aVersion,
		TInt	aAsyncMessageSlots
	)

protected

Creates a session with a server.

It should be called as part of session initialisation in the derived class.

Parameters

aServer	A handle to a server with which a session is to be established.
aVersion	The lowest version of the server with which this client is compatible.
aAsyncMessageSlots	The number of message slots available to this session. This determines the number of outstanding requests the client may have with the server at any one time. The maximum number of slots is 255. If aAsyncMessageSlots==-1 then this indicates that the session should use messages from the global free pool of messages.

(generated from Symbian Developer Library)

◆ CreateSession() [7/7]

IMPORT_C TInt RSessionBase::CreateSession	(	RServer2	aServer,
		const TVersion &	aVersion,
		TInt	aAsyncMessageSlots,
		TIpcSessionType	aType,
		const TSecurityPolicy *	aPolicy = `0`,
		TRequestStatus *	aStatus = `0`
	)

protected

Creates a session with a server.

It should be called as part of session initialisation in the derived class.

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

Parameters

aServer	A handle to a server with which a session is to be established.
aVersion	The lowest version of the server with which this client is compatible.
aAsyncMessageSlots	The number of message slots available to this session. This determines the number of outstanding requests the client may have with the server at any one time. The maximum number of slots is 255. If aAsyncMessageSlots==-1 then this indicates that the session should use messages from the global free pool of messages.
aType	The type of session to create. See TIpcSessionType.
aPolicy	A pointer to a TSecurityPolicy object. If this pointer is not 0 (zero) then the policy is applied to the process in which the server is running. If that process doesn't pass this security policy check, then the session creation will fail with the error KErrPermissionDenied. This security check allows clients to verify that the server has the expected Platform Security attributes.
aStatus	A pointer to TRequestStatus object which will be signalled when the session has been created, or in the event of an error. If aStatus==0 then session creation is done synchronously.

(generated from Symbian Developer Library)

◆ Open() [1/4]

IMPORT_C TInt RSessionBase::Open	(	RMessagePtr2	aMessage,
		TInt	aParam,
		const TSecurityPolicy &	aServerPolicy,
		TOwnerType	aType = `EOwnerProcess`
	)

Opens a handle to a session using a handle number sent by a client to a server, and validate that the session's server passes a given security policy.

This function is called by the server.

Parameters

aMessage	The message pointer.
aParam	An index specifying which of the four message arguments contains the handle number.
aServerPolicy	The policy to validate the session's server against.
aType	An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [2/4]

IMPORT_C TInt RSessionBase::Open	(	RMessagePtr2	aMessage,
		TInt	aParam,
		TOwnerType	aType = `EOwnerProcess`
	)

Opens a handle to a session using a handle number sent by a client to a server.

This function is called by the server.

Parameters

aMessage	The message pointer.
aParam	An index specifying which of the four message arguments contains the handle number.
aType	An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [3/4]

IMPORT_C TInt RSessionBase::Open	(	TInt	aArgumentIndex,
		const TSecurityPolicy &	aServerPolicy,
		TOwnerType	aType = `EOwnerProcess`
	)

Opens a handle to a session using a handle number passed as an environment data item to the child process during the creation of that child process, after validating that the session's server passes the given security policy.

Note that this function can only be called successfully once.

Parameters

aArgumentIndex	An index that identifies the slot in the process environment data that contains the handle number. This is a value relative to zero, i.e. 0 is the first item/slot. This can range from 0 to 15.
aServerPolicy	The policy to validate the session's server against.
aType	An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [4/4]

IMPORT_C TInt RSessionBase::Open	(	TInt	aArgumentIndex,
		TOwnerType	aType = `EOwnerProcess`
	)

Opens a handle to a session using a handle number passed as an environment data item to the child process during the creation of that child process.

Note that this function can only be called successfully once.

Parameters

aArgumentIndex	An index that identifies the slot in the process environment data that contains the handle number. This is a value relative to zero, i.e. 0 is the first item/slot. This can range from 0 to 15.
aType	An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Send() [1/2]

TInt RSessionBase::Send ( TInt aFunction ) const

inlineprotected

Issues a blind request to the server with the specified function number, but with no arguments.

A blind request is one where the server does not issue a response to the client.

Parameters

aFunction The function number identifying the request.

Panic condition: USER 72 if the function number is negative.

(generated from Symbian Developer Library)

◆ Send() [2/2]

TInt RSessionBase::Send	(	TInt	aFunction,
		const TIpcArgs &	aArgs
	)		const

inlineprotected

Issues a blind request to the server with the specified function number, and arguments.

A blind request is one where the server does not issue a response to the client.

Parameters

aFunction	The function number identifying the request.
aArgs	A set of up to 4 arguments and their types to be passed to the server.

Panic condition: USER 72 if the function number is negative.

(generated from Symbian Developer Library)

◆ SendReceive() [1/4]

TInt RSessionBase::SendReceive ( TInt aFunction ) const

inlineprotected

Issues a synchronous request to the server with the specified function number, but with no arguments.

Parameters

aFunction The function number identifying the request.

Panic condition: USER 72 if the function number is negative.

(generated from Symbian Developer Library)

◆ SendReceive() [2/4]

TInt RSessionBase::SendReceive	(	TInt	aFunction,
		const TIpcArgs &	aArgs
	)		const

inlineprotected

Issues a synchronous request to the server with the specified function number and arguments.

Parameters

aFunction	The function number identifying the request.
aArgs	A set of up to 4 arguments and their types to be passed to the server.

Panic condition: USER 72 if the function number is negative.

(generated from Symbian Developer Library)

◆ SendReceive() [3/4]

void RSessionBase::SendReceive	(	TInt	aFunction,
		const TIpcArgs &	aArgs,
		TRequestStatus &	aStatus
	)		const

inlineprotected

Issues an asynchronous request to the server with the specified function number and arguments.

The completion status of the request is returned via the request status object, aStatus.

Parameters

aFunction	The function number identifying the request.
aArgs	A set of up to 4 arguments and their types to be passed to the server.
aStatus	The request status object used to contain the completion status of the request.

Panic condition: USER 72 if the function number is negative.

(generated from Symbian Developer Library)

◆ SendReceive() [4/4]

void RSessionBase::SendReceive	(	TInt	aFunction,
		TRequestStatus &	aStatus
	)		const

inlineprotected

Issues an asynchronous request to the server with the specified function number, but with no arguments.

The completion status of the request is returned via the request status object, aStatus.

Parameters

aFunction	The function number identifying the request.
aStatus	The request status object used to contain the completion status of the request.

Panic condition: USER 72 if the function number is negative.

(generated from Symbian Developer Library)

◆ SetReturnedHandle() [1/3]

TInt RSessionBase::SetReturnedHandle ( TInt aHandleOrError )

inline

Sets the handle-number of this handle to the specified value.

The function can take a (zero or positive) handle-number, or a (negative) error number.

If aHandleOrError represents a handle-number, then the handle-number of this handle is set to that value. If aHandleOrError represents an error number, then the handle-number of this handle is set to zero and the negative value is returned.

Parameters

aHandleOrError A handle-number, if zero or positive; an error value, if negative.

(generated from Symbian Developer Library)

◆ SetReturnedHandle() [2/3]

IMPORT_C TInt RSessionBase::SetReturnedHandle	(	TInt	aHandleOrError,
		const TSecurityPolicy &	aServerPolicy
	)

Sets the handle-number of this session handle to the specified value after validating that the session's server passes a given security policy.

The function can take a (zero or positive) handle-number, or a (negative) error number.

If aHandleOrError represents a handle-number, then the handle-number of this handle is set to that value, as long as the session's server passes the security policy. If aHandleOrError represents an error number, then the handle-number of this handle is set to zero and the negative value is returned.

Parameters

aHandleOrError	A handle-number, if zero or positive; an error value, if negative.
aServerPolicy	The policy to validate the session's server against.

(generated from Symbian Developer Library)

◆ SetReturnedHandle() [3/3]

static TInt RSessionBase::SetReturnedHandle	(	TInt	aHandleOrError,
		RHandleBase &	aHandle
	)

inlinestaticprotected

◆ ShareAuto()

TInt RSessionBase::ShareAuto ( )

inline

Creates a session that can be shared by other threads in the current process.

After calling this function the session object may be used by threads other than than the one that created it.

Note that this can only be done with servers that mark their sessions as sharable.

Returns: KErrNone, if the session is successfully shared; KErrNoMmemory, if the attempt fails for lack of memory.

Panic condition: KERN-EXEC 23 The session cannot be shared.

See also: CServer2; RSessionBase::ShareProtected(); CServer2::TServerType

Definition at line 4639 of file e32std.h.

◆ ShareProtected()

TInt RSessionBase::ShareProtected ( )

inline

Creates a session handle that can be be passed via IPC to another process as well as being shared by other threads in the current process.

After calling this function the session object may be used by threads other than than the one that created it.

Note that this can only be done with servers that mark their sessions as globally sharable.

Returns: KErrNone, if the session is successfully shared; KErrNoMmemory, if the attempt fails for lack of memory.

Panic condition: KERN-EXEC 23 The session cannot be shared.

See also: CServer2; RSessionBase::ShareAuto(); CServer2::TServerType

Definition at line 4661 of file e32std.h.

Friends And Related Symbol Documentation

◆ RSubSessionBase

friend class RSubSessionBase

friend

Definition at line 4612 of file e32std.h.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ TAttachMode

Member Function Documentation

◆ CreateSession() [1/7]

◆ CreateSession() [2/7]

◆ CreateSession() [3/7]

◆ CreateSession() [4/7]

◆ CreateSession() [5/7]

◆ CreateSession() [6/7]

◆ CreateSession() [7/7]

◆ Open() [1/4]

◆ Open() [2/4]

◆ Open() [3/4]

◆ Open() [4/4]

◆ Send() [1/2]

◆ Send() [2/2]

◆ SendReceive() [1/4]

◆ SendReceive() [2/4]

◆ SendReceive() [3/4]

◆ SendReceive() [4/4]

◆ SetReturnedHandle() [1/3]

◆ SetReturnedHandle() [2/3]

◆ SetReturnedHandle() [3/3]

◆ ShareAuto()

◆ ShareProtected()

Friends And Related Symbol Documentation

◆ RSubSessionBase