#include <e32std.h>
class RSessionBase : public RHandleBase |
Public Member Enumerations | |
---|---|
enum | TAttachMode { EExplicitAttach, EAutoAttach } |
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 &) |
Inherited Attributes | |
---|---|
RHandleBase::iHandle |
Inherited Enumerations | |
---|---|
RHandleBase:TAttributes |
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.
Indicates whether or not threads in the process are automatically attached to the session when passed as a parameter to the Share() function.
Enumerator | Value | Description |
---|---|---|
EExplicitAttach | ||
EAutoAttach |
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 |
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 | |
---|---|
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. |
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 | |
---|---|
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. |
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 |
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 | |
---|---|
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. |
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.
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. |
TInt | CreateSession | ( | const TDesC & | aServer, |
const TVersion & | aVersion, | |||
TInt | aAsyncMessageSlots, | |||
TRequestStatus * | aStatus | |||
) | [protected, inline] |
DeprecatedUse CreateSession(const TDesC& aServer,const TVersion& aVersion,TInt aAsyncMessageSlots,TIpcSessionType aType,const TSecurityPolicy* aPolicy=0, TRequestStatus* aStatus=0);
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 | |
---|---|
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. |
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 | |
---|---|
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. |
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 | |
---|---|
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. |
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 | |
---|---|
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. |
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 Codes | |
---|---|
USER | 72 if the function number is negative. |
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 Codes | |
---|---|
USER | 72 if the function number is negative. |
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.
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 Codes | |
---|---|
USER | 72 if the function number is negative. |
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 Codes | |
---|---|
USER | 72 if the function number is negative. |
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.
Parameters | |
---|---|
aFunction | The function number identifying the request. |
aStatus | The request status object used to contain the completion status of the request. |
Panic Codes | |
---|---|
USER | 72 if the function number is negative. |
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 Codes | |
---|---|
USER | 72 if the function number is negative. |
Reimplemented from RHandleBase::SetReturnedHandle(TInt)
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. |
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 | |
---|---|
aHandleOrError | A handle-number, if zero or positive; an error value, if negative. |
aServerPolicy | The policy to validate the session's server against. |
TInt | SetReturnedHandle | ( | TInt | aHandleOrError, |
RHandleBase & | aHandle | |||
) | [protected, static, inline] |
Reimplemented from RHandleBase::SetReturnedHandle(TInt,RHandleBase &)
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.
See also: CServer2 RSessionBase::ShareProtected() CServer2::TServerType
Panic Codes | |
---|---|
KERN-EXEC | 23 The session cannot be shared. |
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.
See also: CServer2 RSessionBase::ShareAuto() CServer2::TServerType
Panic Codes | |
---|---|
KERN-EXEC | 23 The session cannot be shared. |