»
Symbian OS v9.3 »
Symbian OS reference »
C++ component reference »
Base E32_EKA2 »
RSessionBase
Location:
e32std.h
Link against: euser.lib
class RSessionBase : public RHandleBase;
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
RSessionBase - Client-side handle to a session with a server
Members
Defined in RSessionBase:
CreateSession(), CreateSession(), CreateSession(), CreateSession(), CreateSession(), CreateSession(), CreateSession(), EAutoAttach, EExplicitAttach, Open(), Open(), Open(), Open(), Send(), Send(), SendReceive(), SendReceive(), SendReceive(), SendReceive(), SetReturnedHandle(), SetReturnedHandle(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode
Inherited from RHandleBase:
Attributes(),
Close(),
Duplicate(),
FullName(),
Handle(),
HandleInfo(),
Name(),
SetHandle(),
SetHandleNC(),
iHandle
Member functions
inline TInt ShareAuto();
Description
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.
Return value
TInt
|
KErrNone, if the session is successfully shared; KErrNoMmemory, if the attempt fails for lack of memory.
|
|
Panic codes
KERN-EXEC |
23 The session cannot be shared.
|
|
See also:
inline TInt ShareProtected();
Description
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.
Return value
TInt
|
KErrNone, if the session is successfully shared; KErrNoMmemory, if the attempt fails for lack of memory.
|
|
Panic codes
KERN-EXEC |
23 The session cannot be shared.
|
|
See also:
IMPORT_C TInt Open(RMessagePtr2 aMessage, TInt aParam, TOwnerType aType=EOwnerProcess);
Description
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 |
An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is
taken as default.
|
|
Return value
TInt
|
KErrNone, if successful; KErrArgument, if the value of aParam is outside the range 0-3; KErrBadHandle, if not a valid handle;
otherwise one of the other system-wide error codes.
|
|
IMPORT_C TInt Open(RMessagePtr2 aMessage, TInt aParam, const TSecurityPolicy &aServerPolicy, TOwnerType aType=EOwnerProcess);
Description
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 |
An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is
taken as default.
|
|
Return value
TInt
|
KErrNone, if successful; KErrArgument, if the value of aParam is outside the range 0-3; KErrBadHandle, if not a valid handle;
KErrServerTerminating, if the session is no longer connected to a server; KErrPermissionDenied, if the session's server does
not pass the given security policy; otherwise one of the other system-wide error codes.
|
|
IMPORT_C TInt Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);
Description
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 |
An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is
taken as default.
|
|
Return value
TInt
|
KErrNone, if successful; KErrNotFound, if the slot indicated by aArgumentIndex is empty; KErrArgument, if the slot does not
contain a session handle; otherwise one of the other system-wide error codes.
|
|
IMPORT_C TInt Open(TInt aArgumentIndex, const TSecurityPolicy &aServerPolicy, TOwnerType aType=EOwnerProcess);
Description
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 |
An enumeration whose enumerators define the ownership of this session handle. If not explicitly specified, EOwnerProcess is
taken as default.
|
|
Return value
TInt
|
KErrNone, if successful; KErrNotFound, if the slot indicated by aArgumentIndex is empty; KErrArgument, if the slot does not
contain a session handle; KErrServerTerminating, if the session is no longer connected to a server; KErrPermissionDenied,
if the session's server does not pass the given security policy; otherwise one of the other system-wide error codes.
|
|
inline TInt SetReturnedHandle(TInt aHandleOrError);
Description
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.
|
|
Return value
TInt
|
KErrNone, if aHandle is a handle-number; the value of aHandleOrError, otherwise.
|
|
IMPORT_C TInt SetReturnedHandle(TInt aHandleOrError, const TSecurityPolicy &aServerPolicy);
Description
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.
|
|
Return value
TInt
|
KErrNone, if aHandle is a handle-number; KErrPermissionDenied, if the session's server does not pass the security policy;
the value of aHandleOrError, otherwise.
|
|
protected: inline TInt CreateSession(const TDesC &aServer, const TVersion &aVersion);
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 other system-wide error codes.
|
|
protected: IMPORT_C TInt CreateSession(const TDesC &aServer, const TVersion &aVersion, TInt aAsyncMessageSlots);
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. If aAsyncMessageSlots==-1 then this indicates that the
session should use messages from the global free pool of messages.
|
|
Return value
TInt
|
KErrNone if successful; KErrArgument, if an attempt is made to specify more than 255 message slots; otherwise one of the other
system-wide error codes.
|
|
protected: IMPORT_C TInt CreateSession(const TDesC &aServer, const TVersion &aVersion, TInt aAsyncMessageSlots, TIpcSessionType
aType, const TSecurityPolicy *aPolicy=0, TRequestStatus *aStatus=0);
Description
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 |
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 |
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.
|
|
Return value
TInt
|
KErrNone if successful; KErrArgument, if an attempt is made to specify more than 255 message slots; otherwise one of the other
system-wide error codes.
|
|
protected: inline TInt CreateSession(RServer2 aServer, const TVersion &aVersion);
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
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
|
|
Return value
TInt
|
KErrNone if successful, otherwise one of the other system-wide error codes.
|
|
protected: IMPORT_C TInt CreateSession(RServer2 aServer, const TVersion &aVersion, TInt aAsyncMessageSlots);
Description
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.
|
|
Return value
TInt
|
KErrNone if successful; KErrArgument, if an attempt is made to specify more than 255 message slots; otherwise one of the other
system-wide error codes.
|
|
protected: IMPORT_C TInt CreateSession(RServer2 aServer, const TVersion &aVersion, TInt aAsyncMessageSlots, TIpcSessionType
aType, const TSecurityPolicy *aPolicy=0, TRequestStatus *aStatus=0);
Description
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
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 |
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 |
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.
|
|
Return value
TInt
|
KErrNone if successful; KErrArgument, if an attempt is made to specify more than 255 message slots; otherwise one of the other
system-wide error codes.
|
|
protected: static inline TInt SetReturnedHandle(TInt aHandleOrError, RHandleBase &aHandle);
Description
Parameters
Return value
protected: inline TInt CreateSession(const TDesC &aServer, const TVersion &aVersion, TInt aAsyncMessageSlots, TRequestStatus
*aStatus);
Description
Parameters
Return value
protected: inline TInt Send(TInt aFunction, const TIpcArgs &aArgs) const;
Description
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
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.
|
|
Return value
TInt
|
KErrNone, if the send operation is successful; KErrServerTerminated, if the server no longer present; KErrServerBusy, if there
are no message slots available; KErrNoMemory, if there is insufficient memory available.
|
|
Panic codes
USER |
72 if the function number is negative.
|
|
protected: inline void SendReceive(TInt aFunction, const TIpcArgs &aArgs, TRequestStatus &aStatus) const;
Description
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
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.
|
|
Panic codes
USER |
72 if the function number is negative.
|
|
protected: inline TInt SendReceive(TInt aFunction, const TIpcArgs &aArgs) const;
Description
Issues a synchronous request to the server with the specified function number and arguments.
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.
|
|
Return value
TInt
|
KErrNone, if the send operation is successful; KErrServerTerminated, if the server no longer present; KErrServerBusy, if there
are no message slots available; KErrNoMemory, if there is insufficient memory available.
|
|
Panic codes
USER |
72 if the function number is negative.
|
|
protected: inline TInt Send(TInt aFunction) const;
Description
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
TInt aFunction |
The function number identifying the request.
|
|
Return value
TInt
|
KErrNone, if the send operation is successful; KErrServerTerminated, if the server no longer present; KErrServerBusy, if there
are no message slots available; KErrNoMemory, if there is insufficient memory available.
|
|
Panic codes
USER |
72 if the function number is negative.
|
|
protected: inline void SendReceive(TInt aFunction, TRequestStatus &aStatus) const;
Description
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
TInt aFunction |
The function number identifying the request.
|
TRequestStatus &aStatus |
The request status object used to contain the completion status of the request.
|
|
Panic codes
USER |
72 if the function number is negative.
|
|
protected: inline TInt SendReceive(TInt aFunction) const;
Description
Issues a synchronous request to the server with the specified function number, but with no arguments.
Parameters
TInt aFunction |
The function number identifying the request.
|
|
Return value
TInt
|
KErrNone, if the send operation is successful; KErrServerTerminated, if the server no longer present; KErrServerBusy, if there
are no message slots available; KErrNoMemory, if there is insufficient memory available.
|
|
Panic codes
USER |
72 if the function number is negative.
|
|
TAttachMode
Description
Indicates whether or not threads in the process are automatically attached to the session when passed as a parameter to the
Share() function.
![[Index]](../../../../a_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../a_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../a_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../a_stock/btn_next_wt.gif){kind=small}
![[Top]](../../../../a_stock/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../a_stock/btn_prev.gif){kind=small}
![[Top]](../../../../a_stock/btn_top.gif)
![[Next]](../../../../a_stock/btn_next.gif){kind=small}