Collapse all Symbian^3 Product Developer Library

RSessionBase Class Reference

class RSessionBase : public RHandleBase

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.

Inherits from

RSessionBase
- RHandleBase

Public Member Functions
IMPORT_C TInt	Open(RMessagePtr2, TInt, TOwnerType)
IMPORT_C TInt	Open(RMessagePtr2, TInt, const TSecurityPolicy &, TOwnerType)
IMPORT_C TInt	Open(TInt, TOwnerType)
IMPORT_C TInt	Open(TInt, const TSecurityPolicy &, TOwnerType)
TInt	SetReturnedHandle(TInt)
IMPORT_C TInt	SetReturnedHandle(TInt, const TSecurityPolicy &)
TInt	ShareAuto()
TInt	ShareProtected()

Protected Member Functions
TInt	CreateSession(const TDesC &, const TVersion &)
IMPORT_C TInt	CreateSession(const TDesC &, const TVersion &, TInt)
IMPORT_C TInt	CreateSession(const TDesC &, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy , TRequestStatus )
TInt	CreateSession(RServer2, const TVersion &)
IMPORT_C TInt	CreateSession(RServer2, const TVersion &, TInt)
IMPORT_C TInt	CreateSession(RServer2, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy , TRequestStatus )
TInt	CreateSession(const TDesC &, const TVersion &, TInt, TRequestStatus *)
TInt	Send(TInt, const TIpcArgs &)
TInt	Send(TInt)
void	SendReceive(TInt, const TIpcArgs &, TRequestStatus &)
TInt	SendReceive(TInt, const TIpcArgs &)
void	SendReceive(TInt, TRequestStatus &)
TInt	SendReceive(TInt)
TInt	SetReturnedHandle(TInt, RHandleBase &)

Private Member Functions
TInt	DoConnect(const TVersion &, TRequestStatus *)
IMPORT_C TInt	DoSend(TInt, const TIpcArgs *)
IMPORT_C void	DoSendReceive(TInt, const TIpcArgs *, TRequestStatus &)
IMPORT_C TInt	DoSendReceive(TInt, const TIpcArgs *)
IMPORT_C TInt	DoShare(TInt)
TInt	SendAsync(TInt, const TIpcArgs , TRequestStatus )
TInt	SendSync(TInt, const TIpcArgs *)

Inherited Functions
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::Close()
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)

Public Member Enumerations
enum	TAttachMode { EExplicitAttach, EAutoAttach }

Inherited Enumerations
	RHandleBase:TAttributes

Inherited Attributes
	RHandleBase::iHandle

Member Functions Documentation

CreateSession(const TDesC &, const TVersion &)

TInt	CreateSession	(	const TDesC &	aServer,
			const TVersion &	aVersion
		)	[protected, inline]

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

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

CreateSession(const TDesC &, const TVersion &, TInt)

IMPORT_C TInt	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

const TDesC & aServer	The name of the server with which a session is to be established.
const TVersion & aVersion	The lowest version of the server with which this client is compatible.
TInt 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.

CreateSession(const TDesC &, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy , TRequestStatus )

IMPORT_C TInt	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

const TDesC & aServer	The name of the server with which a session is to be established.
const TVersion & aVersion	The lowest version of the server with which this client is compatible.
TInt 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.
TIpcSessionType aType	The type of session to create. See TIpcSessionType.
const TSecurityPolicy * aPolicy = 0	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.
TRequestStatus * aStatus = 0	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.

CreateSession(RServer2, const TVersion &)

TInt	CreateSession	(	RServer2	aServer,
			const TVersion &	aVersion
		)	[protected, inline]

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

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

Parameters

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

CreateSession(RServer2, const TVersion &, TInt)

IMPORT_C TInt	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

RServer2 aServer	A handle to a server with which a session is to be established.
const TVersion & aVersion	The lowest version of the server with which this client is compatible.
TInt 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.

CreateSession(RServer2, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy , TRequestStatus )

IMPORT_C TInt	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.

Parameters

RServer2 aServer	A handle to a server with which a session is to be established.
const TVersion & aVersion	The lowest version of the server with which this client is compatible.
TInt 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.
TIpcSessionType aType	The type of session to create. See TIpcSessionType.
const TSecurityPolicy * aPolicy = 0	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.
TRequestStatus * aStatus = 0	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.

CreateSession(const TDesC &, const TVersion &, TInt, TRequestStatus *)

TInt	CreateSession	(	const TDesC &	aServer,
			const TVersion &	aVersion,
			TInt	aAsyncMessageSlots,
			TRequestStatus *	aStatus
		)	[protected, inline]

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

Parameters

const TDesC & aServer
const TVersion & aVersion
TInt aAsyncMessageSlots
TRequestStatus * aStatus

DoConnect(const TVersion &, TRequestStatus *)

TInt	DoConnect	(	const TVersion &	aVersion,
			TRequestStatus *	aStatus
		)	[private]

Parameters

const TVersion & aVersion
TRequestStatus * aStatus

DoSend(TInt, const TIpcArgs *)

IMPORT_C TInt	DoSend	(	TInt	aFunction,
			const TIpcArgs *	aArgs
		)	const [private]

Parameters

TInt aFunction
const TIpcArgs * aArgs

DoSendReceive(TInt, const TIpcArgs *, TRequestStatus &)

IMPORT_C void	DoSendReceive	(	TInt	aFunction,
			const TIpcArgs *	aArgs,
			TRequestStatus &	aStatus
		)	const [private]

Parameters

TInt aFunction
const TIpcArgs * aArgs
TRequestStatus & aStatus

DoSendReceive(TInt, const TIpcArgs *)

IMPORT_C TInt	DoSendReceive	(	TInt	aFunction,
			const TIpcArgs *	aArgs
		)	const [private]

Parameters

TInt aFunction
const TIpcArgs * aArgs

DoShare(TInt)

IMPORT_C TInt

DoShare

(

TInt

aAttachMode

)

[private]

Parameters

TInt aAttachMode

Open(RMessagePtr2, TInt, TOwnerType)

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.

This function is called by the server.

Parameters

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

Open(RMessagePtr2, TInt, const TSecurityPolicy &, TOwnerType)

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.

This function is called by the server.

Parameters

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

Open(TInt, TOwnerType)

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.

Note that this function can only be called successfully once.

Parameters

TInt 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.
TOwnerType aType = EOwnerProcess	An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is taken as default.

Open(TInt, const TSecurityPolicy &, TOwnerType)

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.

Note that this function can only be called successfully once.

Parameters

TInt 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.
const TSecurityPolicy & aServerPolicy	The policy to validate the session's server against.
TOwnerType aType = EOwnerProcess	An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is taken as default.

Send(TInt, const TIpcArgs &)

TInt	Send	(	TInt	aFunction,
			const TIpcArgs &	aArgs
		)	const [protected, inline]

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.

panic: USER 72 if the function number is negative.

Parameters

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

Send(TInt)

TInt

Send

(

TInt

aFunction

)

const [protected, inline]

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.

panic: USER 72 if the function number is negative.

Parameters

TInt aFunction

The function number identifying the request.

SendAsync(TInt, const TIpcArgs , TRequestStatus )

TInt	SendAsync	(	TInt	aFunction,
			const TIpcArgs *	aArgs,
			TRequestStatus *	aStatus
		)	const [private]

Parameters

TInt aFunction
const TIpcArgs * aArgs
TRequestStatus * aStatus

SendReceive(TInt, const TIpcArgs &, TRequestStatus &)

void	SendReceive	(	TInt	aFunction,
			const TIpcArgs &	aArgs,
			TRequestStatus &	aStatus
		)	const [protected, inline]

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.

panic: USER 72 if the function number is negative.

Parameters

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

SendReceive(TInt, const TIpcArgs &)

TInt	SendReceive	(	TInt	aFunction,
			const TIpcArgs &	aArgs
		)	const [protected, inline]

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

panic: USER 72 if the function number is negative.

Parameters

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

SendReceive(TInt, TRequestStatus &)

void	SendReceive	(	TInt	aFunction,
			TRequestStatus &	aStatus
		)	const [protected, inline]

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.

panic: USER 72 if the function number is negative.

Parameters

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

SendReceive(TInt)

TInt

SendReceive

(

TInt

aFunction

)

const [protected, inline]

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

panic: USER 72 if the function number is negative.

Parameters

TInt aFunction

The function number identifying the request.

SendSync(TInt, const TIpcArgs *)

TInt	SendSync	(	TInt	aFunction,
			const TIpcArgs *	aArgs
		)	const [private]

Parameters

TInt aFunction
const TIpcArgs * aArgs

SetReturnedHandle(TInt)

TInt

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

TInt aHandleOrError

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

SetReturnedHandle(TInt, const TSecurityPolicy &)

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.

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

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

SetReturnedHandle(TInt, RHandleBase &)

TInt	SetReturnedHandle	(	TInt	aHandleOrError,
			RHandleBase &	aHandle
		)	[protected, static, inline]

Parameters

TInt aHandleOrError
RHandleBase & aHandle

ShareAuto()

TInt

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.

panic: KERN-EXEC 23 The session cannot be shared.

CServer2 RSessionBase::ShareProtected() CServer2::TServerType

ShareProtected()

TInt

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.

panic: KERN-EXEC 23 The session cannot be shared.

CServer2 RSessionBase::ShareAuto() CServer2::TServerType

Member Enumerations Documentation

Enum TAttachMode

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

Enumerators

EExplicitAttach
EAutoAttach

RSessionBase Class Reference

Inherits from

Member Functions Documentation

CreateSession(const TDesC &, const TVersion &)

Parameters

CreateSession(const TDesC &, const TVersion &, TInt)

Parameters

CreateSession(const TDesC &, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy *, TRequestStatus *)

Parameters

CreateSession(RServer2, const TVersion &)

Parameters

CreateSession(RServer2, const TVersion &, TInt)

Parameters

CreateSession(RServer2, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy *, TRequestStatus *)

Parameters

CreateSession(const TDesC &, const TVersion &, TInt, TRequestStatus *)

Parameters

DoConnect(const TVersion &, TRequestStatus *)

Parameters

DoSend(TInt, const TIpcArgs *)

Parameters

DoSendReceive(TInt, const TIpcArgs *, TRequestStatus &)

Parameters

DoSendReceive(TInt, const TIpcArgs *)

Parameters

DoShare(TInt)

Parameters

Open(RMessagePtr2, TInt, TOwnerType)

Parameters

Open(RMessagePtr2, TInt, const TSecurityPolicy &, TOwnerType)

Parameters

Open(TInt, TOwnerType)

Parameters

Open(TInt, const TSecurityPolicy &, TOwnerType)

Parameters

Send(TInt, const TIpcArgs &)

Parameters

Send(TInt)

Parameters

SendAsync(TInt, const TIpcArgs *, TRequestStatus *)

Parameters

SendReceive(TInt, const TIpcArgs &, TRequestStatus &)

Parameters

SendReceive(TInt, const TIpcArgs &)

Parameters

SendReceive(TInt, TRequestStatus &)

Parameters

SendReceive(TInt)

Parameters

SendSync(TInt, const TIpcArgs *)

Parameters

SetReturnedHandle(TInt)

Parameters

SetReturnedHandle(TInt, const TSecurityPolicy &)

Parameters

SetReturnedHandle(TInt, RHandleBase &)

Parameters

ShareAuto()

ShareProtected()

Member Enumerations Documentation

Enum TAttachMode

Enumerators

CreateSession(const TDesC &, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy , TRequestStatus )

CreateSession(RServer2, const TVersion &, TInt, TIpcSessionType, const TSecurityPolicy , TRequestStatus )

SendAsync(TInt, const TIpcArgs , TRequestStatus )