Class RSessionBase

RSessionBase

Support

Supported from 5.0

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.

Derivation

RHandleBase Handle to an object RSessionBase Client-side handle to a session with a server

Defined in RSessionBase:
Attach(), CreateSession(), EAutoAttach, EExplicitAttach, Send(), SendReceive(), SetRetry(), Share(), TAttachMode

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

TInt Share(TAttachMode aAttachMode=EExplicitAttach);

Support

Supported from 6.0

Description

Makes the session shared among all threads in the process. A session is thread specific until this function is called.

If the session is with a server that does not support the sharing of sessions, a KERN-SVR 23 panic is raised.

If the session is already shared. the function has no effect.

Notes:

• If explicit attach mode is specified, then a client thread must call Attach() before attempting to send a message, otherwise it is panicked KERN-SVR 0.

Parameters

TAttachMode Indicates whether threads in the process are automatically attached to the session, or whether they must make an explict attach. The default is an explicit attach.

Return value

TInt KErrNone, if successful; otherwise one of the other system -wide error codes.

TInt Attach() const;

Support

Supported from 6.0

Description

Explicitly attaches a thread to the session.

Calling this function ensures that the necessary Kernel resources are allocated to allow the thread to send messages.

Notes:

• If a thread is required to explicitly attach to the session, then this function must be called before that thread can use the session.

• A prior call to RSessionBase::Share() must have been made before this function is called, otherwise a KERN_SVR 0 panic is raised.

Return value

TInt KErrNone, if successful or if the thread has already attached to the session; KErrNotSupported, if attempting to attach more than 255 threads to the session; otherwise one of the other system-wide error codes.

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

Support

Supported from 6.0

Description

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.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

protected: TInt CreateSession(const TDesC& aServer,const TVersion& aVersion,TInt aAsyncMessageSlots);

Support

Supported from 6.0

Description

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

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes; KErrArgument, if an attempt is made to specify more than 255 message slots.

protected: TInt CreateSession(const TDesC& aServer,const TVersion& aVersion,TInt aMessageSlots,TTimeIntervalMicroSeconds32 aDelayTime=KSendDelayTime,TInt aRetryCount=KSendRetryCount);

Support

Withdrawn in 6.0

Description

Creates a session with a server.

It should be called as part of session initialisation in the derived class. A number of attributes governing the session are specified here.

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 aMessageSlots 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. TTimeIntervalMicroSeconds32 aDelayTime The interval to wait before retrying to send the message if the server is busy. If no explicit value is passed, the default value KSendDelayTime is supplied. This value must not be negative otherwise the function raises a USER 103 panic. TInt aRetryCount The number of retries that should be made when sending a message. If no explicit value is passed, the default value KSendRetryCount is supplied. This value must not be negative otherwise the function raises a USER 104 panic

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

protected: void SetRetry(TTimeIntervalMicroSeconds32 aDelayTime,TInt aRetryCount);

Support

Withdrawn in 6.0

Description

Changes the retry parameters used to resend a message if the server is busy.

Parameters

TTimeIntervalMicroSeconds32 aDelayTime The interval to wait before retrying to send the message if the server is busy. This value must not be negative otherwise the function raises a USER 71 panic. TInt aRetryCount The number of retries that should be made when sending a message. This value must not be negative otherwise the function raises a USER 70 panic

protected: TInt Send(TInt aFunction,TAny* aPtr) const;

Description

Sends a blind message to the server — no reply is expected. A message argument array is passed; this may be used to specify client addresses which the server can use to read from and write to the client address space.

Parameters

TInt aFunction The opcode specifying the requested service. TAny* aPtr A pointer to the message argument array - an array of four 32 bit parameters.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

protected: void SendReceive(TInt aFunction,TAny* aPtr,TRequestStatus& aStatus) const;

Description

Sends a message to the server and waits asynchronously for the reply. An opcode specifies the service required. A message argument array is passed; this may be used to specify client addresses which the server can use to read from and write to the client address space.

Parameters

TInt aFunction The opcode specifying the requested service. TAny* aPtr A pointer to the message argument array - an array of four 32 bit parameters. TRequestStatus& aStatus A request status which indicates the completion status of the asynchronous request. Attempting to send a message when all message slots are in use, results in a KErrServerBusy completion status.

protected: TInt SendReceive(TInt aFunction,TAny* aPtr) const;

Description

Sends a message to the server and waits synchronously for the reply. An opcode specifies the service required. A message argument array is passed; this may be used to specify client addresses which the server can use to read from and write to the client address space.

Parameters

TInt aFunction The opcode specifying the requested service. TAny* aPtr A pointer to the message argument array - an array of four 32 bit parameters.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TAttachMode

Support

Supported from 6.0

Description

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

EExplicitAttach Client threads explicitly attach to the session EAutoAttach Client threads are auto-attached to the session.