#include <e32cmn.h>
class RMessagePtr2 |
Protected Attributes | |
---|---|
TInt | iHandle |
A handle to a message sent by the client to the server.
A server's interaction with its clients is channelled through an RMessagePtr2 object, which acts as a handle to a message sent by the client. The details of the original message are kept by the kernel allowing it enforce correct usage of the member functions of this class.
See also: RMessage2
TInt | iHandle | [protected] |
IMPORT_C TInt | Client | ( | RThread & | aClient, |
TOwnerType | aOwnerType = EOwnerProcess | |||
) | const |
Opens a handle on the client thread.
Parameters | |
---|---|
aClient | On successful return, the handle to the client thread. |
aOwnerType | An enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as default. |
IMPORT_C TBool | ClientIsRealtime | ( | ) | const |
void | ClientL | ( | RThread & | aClient, |
TOwnerType | aOwnerType = EOwnerProcess | |||
) | const [inline] |
Opens a handle on the client thread.
Parameters | |
---|---|
aClient | On successful return, the handle to the client thread. |
aOwnerType | An enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as default. |
IMPORT_C TUint | ClientProcessFlags | ( | ) | const |
IMPORT_C const TRequestStatus * | ClientStatus | ( | ) | const |
Returns the pointer to the clients TRequestStatus associated with the message.
The return value is intended to be used as a unique identifier (for example, to uniquely identify an asynchronous message when cancelling the request). The memory must never be accessed directly or completed.
IMPORT_C void | Complete | ( | RHandleBase | aHandle | ) | const |
Duplicates the specified handle in the client thread, and returns this handle as a message completion code
Parameters | |
---|---|
aHandle | The handle to be duplicated. |
Gets the length of a descriptor argument in the client's process.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
Gets the length of a descriptor argument in the client's process, leaving on failure.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
Leave Codes | |
---|---|
KErrArgument | if aParam has a value outside the valid range. |
KErrBadDescriptor, | if the message argument is not a descriptor type. |
Gets the maximum length of a descriptor argument in the client's process.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
Gets the maximum length of a descriptor argument in the client's process, leaving on failure.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
Leave Codes | |
---|---|
KErrArgument | if aParam has a value outside the valid range. |
KErrBadDescriptor, | if the message argument is not a descriptor type. |
TBool | HasCapability | ( | TCapability | aCapability, |
const char * | aDiagnostic = 0 | |||
) | const [inline] |
Check if the process which sent this message has a given capability.
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 ETrue even though the check failed.
Parameters | |
---|---|
aCapability | The capability to test. |
aDiagnostic | A string that will be emitted along with any diagnostic message that may be issued if the test finds the capability is not present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system. |
TBool | HasCapability | ( | TCapability | aCapability1, |
TCapability | aCapability2, | |||
const char * | aDiagnostic = 0 | |||
) | const [inline] |
Check if the process which sent this message has both of the given capabilities.
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 ETrue even though the check failed.
Parameters | |
---|---|
aCapability1 | The first capability to test. |
aCapability2 | The second capability to test. |
aDiagnostic | A string that will be emitted along with any diagnostic message that may be issued if the test finds a capability is not present. This string should be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system. |
void | HasCapabilityL | ( | TCapability | aCapability, |
const char * | aDiagnosticMessage = 0 | |||
) | const [inline] |
Check if the process which sent this message has a given capability.
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 not leave even though the check failed.
Parameters | |
---|---|
aCapability | The capability to test. |
aDiagnosticMessage | A string that will be emitted along with any diagnostic message that may be issued if the test finds the capability is not present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system. |
Leave Codes | |
---|---|
KErrPermissionDenied, | if the process does not have the capability. |
void | HasCapabilityL | ( | TCapability | aCapability1, |
TCapability | aCapability2, | |||
const char * | aDiagnosticMessage = 0 | |||
) | const [inline] |
Check if the process which sent this message has both of the given capabilities.
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 not leave even though the check failed.
Parameters | |
---|---|
aCapability1 | The first capability to test. |
aCapability2 | The second capability to test. |
aDiagnosticMessage | A string that will be emitted along with any diagnostic message that may be issued if the test finds a capability is not present. This string should be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system. |
Leave Codes | |
---|---|
KErrPermissionDenied, | if the process does not have the capabilities. |
TBool | IsNull | ( | ) | const [inline] |
Tests whether this message handle is empty.
IMPORT_C void | Kill | ( | TInt | aReason | ) | const |
Kills the client.
Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
Parameters | |
---|---|
aReason | The reason code associated with killing the client. |
Panics the client.
The length of the category name should be no greater than 16; any name with a length greater than 16 is truncated to 16.
Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
Parameters | |
---|---|
aCategory | The panic category. |
aReason | The panic code. |
Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The target descriptor into which the client data is to be written. |
aOffset | The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero. |
Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The target descriptor into which the client data is to be written. |
aOffset | The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero. |
Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor, and leaving on failure.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The target descriptor into which the client data is to be written. |
aOffset | The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero. |
Leave Codes | |
---|---|
KErrArgument | if aParam has a value outside the valid range, or if aOffset is negative. |
KErrBadDescriptor, | if the message argument is not an 8-bit descriptor. |
Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor, and leaving on failure.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The target descriptor into which the client data is to be written. |
aOffset | The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero. |
Leave Codes | |
---|---|
KErrArgument | if aParam has a value outside the valid range, or if aOffset is negative. |
KErrBadDescriptor, | if the message argument is not a 16-bit descriptor. |
IMPORT_C TSecureId | SecureId | ( | ) | const |
Return the Secure ID of the process which sent this message.
If an intended use of this method is to check that the Secure ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:
RMessagePtr2& message; TInt error = message.SecureId()==KRequiredSecureId ? KErrNone : KErrPermissionDenied;
this could be used;
RMessagePtr2& message; static _LIT_SECURITY_POLICY_S0(mySidPolicy, KRequiredSecureId); TBool pass = mySidPolicy().CheckPolicy(message);
This has the benefit that the TSecurityPolicy::CheckPolicy methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages when a check fails and/or the check can be forced to always pass.
See also: TSecurityPolicy::CheckPolicy(RMessagePtr2 aMsgPtr, const char* aDiagnostic) const _LIT_SECURITY_POLICY_S0
IMPORT_C TInt | SetProcessPriority | ( | TProcessPriority | aPriority | ) | const |
Sets the priority of the client's process.
Parameters | |
---|---|
aPriority | The priority value. |
void | SetProcessPriorityL | ( | TProcessPriority | aPriority | ) | const [inline] |
Sets the priority of the client's process.
Parameters | |
---|---|
aPriority | The priority value. |
IMPORT_C void | Terminate | ( | TInt | aReason | ) | const |
Terminates the client.
Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
Parameters | |
---|---|
aReason | The reason code associated with terminating the client. |
IMPORT_C TVendorId | VendorId | ( | ) | const |
Return the Vendor ID of the process which sent this message.
If an intended use of this method is to check that the Vendor ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:
RMessagePtr2& message; TInt error = message.VendorId()==KRequiredVendorId ? KErrNone : KErrPermissionDenied;
this could be used;
RMessagePtr2& message; static _LIT_SECURITY_POLICY_V0(myVidPolicy, KRequiredVendorId); TBool pass = myVidPolicy().CheckPolicy(message);
This has the benefit that the TSecurityPolicy::CheckPolicy methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages when a check fails and/or the check can be forced to always pass.
See also: TSecurityPolicy::CheckPolicy(RMessagePtr2 aMsgPtr, const char* aDiagnostic) const _LIT_SECURITY_POLICY_V0
Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The source descriptor containing the data to be written. |
aOffset | The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero. |
Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The source descriptor containing the data to be written. |
aOffset | The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero. |
Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument, and leaving on failure.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The source descriptor containing the data to be written. |
aOffset | The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero. |
Leave Codes | |
---|---|
KErrArgument | if aParam has a value outside the valid range, or if aOffset is negative. |
KErrBadDescriptor, | if the message argument is not an 8-bit descriptor. |
Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument, and leaving on failure.
Parameters | |
---|---|
aParam | The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive. |
aDes | The source descriptor containing the data to be written. |
aOffset | The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero. |
Leave Codes | |
---|---|
KErrArgument | if aParam has a value outside the valid range, or if aOffset is negative. |
KErrBadDescriptor, | if the message argument is not a 16-bit descriptor. |