| class CSmsClientMtm : public CBaseMtm |
The SMS client MTM interface.
Most of the functions in this class are implementations of the virtual functions defined by the base class CBaseMtm.
An object of this class can be obtained from the Client MTM registry. The message server provides the necessary information required by the registry to provide the SMS client MTM.
All client MTM objects have a current context. This is an entry in the message store that will be manipulated by certain APIs supplied by the MTM. If the current context is not set then certain APIs will panic.
The CBaseMtm::HasContext API can be used to check that the current context has been set. It can be set using either the CBaseMtm::SwitchCurrenEntryL API or the CBaseMtm::SetCurrentEntryL API.
CBaseMtm::SwitchCurrenEntryL
| Protected Member Functions | |
|---|---|
| IMPORT_C TInt | Extension_(TUint, TAny *&, TAny *) |
| Private Member Functions | |
|---|---|
| CSmsClientMtm(CRegisteredMtmDll &, CMsvSession &) | |
| void | AddRecipientL(const TDesC &, const TDesC &) |
| void | BasicReplyForwardEntry(TMsvEntry &) |
| void | ConstructL() |
| void | ContextEntrySwitched() |
| CMsvOperation * | CreateNewEntryL(TMsvEntry &, TMsvId, CSmsHeader &, const CRichText &, TRequestStatus &) |
| void | DoAddAddresseeL(const TDesC &, const TDesC &) |
| void | DoAddRecipientL(CSmsHeader *, const TDesC &, const TDesC &) |
| TMsvPartList | DoFindL(const TDesC &, TMsvPartList) |
| void | FindInBodyL(const TDesC &, const TMsvPartList &, TMsvPartList &) |
| void | FindL(const TDesC &, const TMsvPartList, TMsvPartList &) |
| HBufC * | ReadEmailSubjectFormatL(RResourceFile &, TInt, const TDesC &) |
| void | ResetHeader() |
| TBool | ValidNumber(const TDesC &) |
| TBool | ValidRecipients() |
| Inherited Attributes | |
|---|---|
| CBaseMtm::iAddresseeList | |
| CBaseMtm::iCharFormatLayer | |
| CBaseMtm::iMsvEntry | |
| CBaseMtm::iParaFormatLayer | |
| CSmsClientMtm | ( | CRegisteredMtmDll & | aRegisteredMtmDll, |
| CMsvSession & | aSession | ||
| ) | [private] | ||
| CRegisteredMtmDll & aRegisteredMtmDll | |
| CMsvSession & aSession |
| void | AddAddresseeL | ( | const TDesC & | aRealAddress | ) | [virtual] |
Adds an addressee for the current context.
Addresses are not validated by checking their format by this function. Usually that is performed by calling ValidateMessage().
Requirements:
Implementations should append the address to the object's address cache in the protected iAddresseeList data member. Some implementations may also wish to store addresses in an internal data structure appropriate for the protocol, for example, a class holding message header information.
leave
KErrNotSupported The message already has the maximum number of addressees
leave
Other leave codes Dependent on implementation
| const TDesC & aRealAddress | String representing an address to be added to the list for the current message |
| void | AddAddresseeL | ( | const TDesC & | aRealAddress, |
| const TDesC & | aAlias | |||
| ) | [virtual] | |||
Adds an addressee for the current context, and enables the client to specify an alias, which may be useful for some protocols. For example, for fax, if the address is the fax number, the alias could supply the recipient's name.
Addresses are not validated by checking their format by this function. Usually that is performed by calling ValidateMessage().
Requirements:
Implementations should append the address to the object's address cache in the protected iAddresseeList data member. Some implementations may also wish to store addresses in an internal data structure appropriate for the protocol, for example, a class holding message header information.
leave
KErrNotSupported The message already has the maximum number of addressees
leave
Other leave codes Dependent on implementation
| void | AddRecipientL | ( | const TDesC & | aRealAddress, |
| const TDesC & | aAlias | |||
| ) | [private] | |||
| void | BasicReplyForwardEntry | ( | TMsvEntry & | aNewEntry | ) | const [private] |
| TMsvEntry & aNewEntry |
| IMPORT_C void | BioTypeChangedL | ( | TUid | aBioTypeUid | ) | [virtual] |
| TUid aBioTypeUid |
| void | ContextEntrySwitched | ( | ) | [private, virtual] |
Called by the base class functions SwitchCurrentEntryL() and SetCurrentEntryL() when the context is changed to another entry.
Client applications do not use this function. It is relevant only to implementers of derived classes.
Requirements:
An implementation should clear:
1. address data stored in iAddresseeList
2. any caches of MTM-specific entry data relating to a previous context. For example, if the implementation has a private buffer storing a message subject, for access through Subject(), this buffer should be cleared.
| IMPORT_C void | CreateMessageL | ( | TMsvEntry & | aEntry | ) |
| TMsvEntry & aEntry |
| IMPORT_C void | CreateMessageL | ( | TMsvId | aServiceId | ) | [virtual] |
| TMsvId aServiceId |
| CMsvOperation * | CreateNewEntryL | ( | TMsvEntry & | aNewEntry, |
| TMsvId | aDestination, | |||
| CSmsHeader & | aSmsHeader, | |||
| const CRichText & | aBody, | |||
| TRequestStatus & | aCompletionStatus | |||
| ) | [private] | |||
| TMsvEntry & aNewEntry | |
| TMsvId aDestination | |
| CSmsHeader & aSmsHeader | |
| const CRichText & aBody | |
| TRequestStatus & aCompletionStatus |
| void | DoAddAddresseeL | ( | const TDesC & | aRealAddress, |
| const TDesC & | aAlias | |||
| ) | [private] | |||
| void | DoAddRecipientL | ( | CSmsHeader * | aSmsHeader, |
| const TDesC & | aRealAddress, | |||
| const TDesC & | aAlias | |||
| ) | [private] | |||
| CSmsHeader * aSmsHeader | |
| const TDesC & aRealAddress | |
| const TDesC & aAlias |
| TMsvPartList | DoFindL | ( | const TDesC & | aTextToFind, |
| TMsvPartList | aPartList | |||
| ) | [private] | |||
| const TDesC & aTextToFind | |
| TMsvPartList aPartList |
| IMPORT_C TInt | Extension_ | ( | TUint | aExtensionId, |
| TAny *& | a0, | |||
| TAny * | a1 | |||
| ) | [protected, virtual] | |||
Methods from CBaseMtm, The implementation of this function assumes that the new service for setting the charset encoding value for a SMS message is supported.
| TMsvPartList | Find | ( | const TDesC & | aTextToFind, |
| TMsvPartList | aPartList | |||
| ) | [virtual] | |||
Searches the specified message part(s) for the plain-text version of the text to be found.
If the specified part list indicates a part that is not supported, or is not present in the current message, the function behaves as if the specified part exists but does not contain the required text.
Requirements:
The parts of the entry for which searching is allowed is implementation specific. If no searching is supported, always return 0.
If the text was not found, or searching is unsupported, 0. If the text was found, a bitmask of the TMsvPartList IDs for each part in which the text was present.
| const TDesC & aTextToFind | The plain-text version of the text to be found. |
| TMsvPartList aPartList | Indicates the message parts which should be searched. |
| void | FindInBodyL | ( | const TDesC & | aTextToFind, |
| const TMsvPartList & | aFoundList, | |||
| TMsvPartList & | aResult | |||
| ) | [private] | |||
| const TDesC & aTextToFind | |
| const TMsvPartList & aFoundList | |
| TMsvPartList & aResult |
| void | FindL | ( | const TDesC & | aTextToFind, |
| const TMsvPartList | aPartList, | |||
| TMsvPartList & | aFoundList | |||
| ) | [private] | |||
| const TDesC & aTextToFind | |
| const TMsvPartList aPartList | |
| TMsvPartList & aFoundList |
| CMsvOperation * | ForwardL | ( | TMsvId | aDestination, |
| TMsvPartList | aPartList, | |||
| TRequestStatus & | aCompletionStatus | |||
| ) | [virtual] | |||
Creates a forwarded message from the current message context.
Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the forwarded message. The parent for the new entry is specified in aDestination. The returned CMsvOperation object completes when editing the forwarded message is complete. On completion, the context is set to the forwarded message.
Requirements:
A typical implementation for this function would include the following steps:
1. create a new message in the specified destination by calling CMsvEntry::CreateL()
2. set the entry index values as appropriate
3. set message content as required. The normal minimum is to include the text of the original message. An implementation may also follow the options specified in aPartlist to include other properties of the original message.
4. set the context to the reply
5. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
If forwarded messages are not supported, implementations should leave with KErrNotSupported.
The implementation of this function may be similar to that of ReplyL(), allowing opportunities for code sharing.
leave
KErrNotSupported The Client-side MTM does not support creation of forwarded messages
leave
Other leave codes Dependent on implementation
If successful, this is an asynchronously completing forward message operation. If failed, this is a completed operation, with status set to the relevant error code.
| TMsvId aDestination | The entry to which to assign the forwarded message |
| TMsvPartList aPartList | Defines the parts that are to be copied from the original message into the forwarded message |
| TRequestStatus & aCompletionStatus | The request status to be completed when the operation has finished |
| void | HandleEntryEvent | ( | enum MMsvEntryObserver::TMsvEntryEvent | , |
| TAny * | , | |||
| TAny * | , | |||
| TAny * | ||||
| ) | ||||
| enum MMsvEntryObserver::TMsvEntryEvent | |
| TAny * | |
| TAny * | |
| TAny * |
| CMsvOperation * | InvokeAsyncFunctionL | ( | TInt | aFunctionId, |
| const CMsvEntrySelection & | aSelection, | |||
| TDes8 & | aParameter, | |||
| TRequestStatus & | aCompletionStatus | |||
| ) | [virtual] | |||
Invokes asynchronous protocol-specific operations. For synchronous operations, a similar function, InvokeSyncFunctionL(), is available.
aSelection and aParameter allow data to be passed to the operation. The TRequestStatus and CMsvOperation objects are used as normal to control and monitor the operation.
Requirements:
For functionality that requires message transport access, such as making a connection, the implementation should pass the request onto the corresponding Server-side MTM. This is done through calling CMsvSession::TransferCommandL(). Implementations may also provide protocol-specific functions themselves if this is useful.
InvokeAsyncFunctionL() should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation. If CMsvSession::TransferCommandL() is called, this should be the CMsvOperation object returned by that function.
leave
KErrNotSupported aFunctionId is not a recognised operation ID
leave
Other leave codes Dependent on implementation
If successful, this is an asynchronously completing operation. If failed, this is a completed operation, with status set to the relevant error code.
| TInt aFunctionId | ID of the requested operation |
| const CMsvEntrySelection & aSelection | Selection of message entries. This is used if the operation requires message entries to work on. |
| TDes8 & aParameter | Buffer containing input and output parameters. The format of this is specific to the operation. |
| TRequestStatus & aCompletionStatus | The request status to be completed when the operation has finished |
| void | InvokeSyncFunctionL | ( | TInt | aFunctionId, |
| const CMsvEntrySelection & | aSelection, | |||
| TDes8 & | aParameter | |||
| ) | [virtual] | |||
Invokes synchronous protocol-specific operations. For asynchronous operations, a similar function, InvokeAsyncFunctionL(), is available.
aSelection and aParameter allow data to be passed to the operation.
Requirements:
For functionality that requires message transport access, such as making a connection, the implementation should pass the request onto the corresponding Server-side MTM. This is done through calling CMsvSession::TransferCommandL(). Implementations may also provide protocol-specific functions themselves if this is useful.
leave
KErrNotSupported aFunctionId is not a recognised operation ID
leave
Other leave codes Dependent on implementation
| TInt aFunctionId | ID of the requested operation |
| const CMsvEntrySelection & aSelection | Selection of message entries. This is used if the operation requires message entries to work on. |
| TDes8 & aParameter | Buffer containing input and output parameters. The format of this is specific to the operation. |
| void | LoadMessageL | ( | ) | [virtual] |
Loads the cache with the message data for the current context.
It can only be called on message contexts.
It is typically used after the context has been set with SetCurrentEntryL() or SwitchCurrentEntryL(). CBaseMtm functions to manipulate the entry can only be called after this function has been called.
Requirements:
An implementation must restore the store and index entry relating to the message context. Typically, the message store should be opened for reading with CMsvEntry::ReadStoreL(). It should be then be read to set the following:
1. body text: call RestoreBodyL() to update the cached body text
2. address list: read the appropriate MTM-specific area of the store to update iAddresseeList
3. subject: if supported, read the appropriate MTM-specific area of the store and update the cache with SetSubjectL()
The function should panic for non-message contexts.
| IMPORT_C CSmsClientMtm * | NewL | ( | CRegisteredMtmDll & | aRegisteredMtmDll, |
| CMsvSession & | aSession | |||
| ) | [static] | |||
| CRegisteredMtmDll & aRegisteredMtmDll | |
| CMsvSession & aSession |
| HBufC * | ReadEmailSubjectFormatL | ( | RResourceFile & | aResourceFile, |
| TInt | aResourceId, | |||
| const TDesC & | aDefaultFormat | |||
| ) | [private] | |||
| RResourceFile & aResourceFile | |
| TInt aResourceId | |
| const TDesC & aDefaultFormat |
| IMPORT_C CSmsSimParamOperation * | ReadSimParamsL | ( | TRequestStatus & | aObserverRequestStatus | ) |
| TRequestStatus & aObserverRequestStatus |
| void | RemoveAddressee | ( | TInt | aIndex | ) | [virtual] |
Removes an address from the current address list. The address is specified by a zero-based index into the address list. If the index is not known, applications can use AddresseeList() to retrieve the entire list to find the item.
Requirements:
Implementations should call iAddresseeList->Delete(aIndex) to remove the address from in the address list protected data member.
| TInt aIndex | Index of address to be removed |
| CMsvOperation * | ReplyL | ( | TMsvId | aDestination, |
| TMsvPartList | aPartlist, | |||
| TRequestStatus & | aCompletionStatus | |||
| ) | [virtual] | |||
Creates a reply message to the current message context.
Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the reply. The parent for the new entry is specified in aDestination.
The returned CMsvOperation object completes when creating the reply is complete. On completion, the context is set to the reply message.
Requirements:
A typical implementation for this function would include the following steps:
1. create a new message in the specified destination by calling CMsvEntry::CreateL()
2. set the entry index values as appropriate
3. set the properties of the message as required. The normal minimum is to set the address to the sender of the original message. An implementation may also follow the options specified in aPartlist to set other properties, for example, to include the original message text.
4. set the context to the reply
5. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
If message replies are not supported, implementations should leave with KErrNotSupported.
The implementation of this function may be similar to that of ForwardL(), allowing opportunities for code sharing.
leave
KErrNotSupported The Client-side MTM does not support reply operations
leave
Other leave codes Dependent on implementation
If successful, this is an asynchronously completing reply operation. If failed, this is a completed operation, with status set to the relevant error code.
| TMsvId aDestination | The entry to which to assign the reply |
| TMsvPartList aPartlist | Defines the parts that are to be copied from the original message into the reply |
| TRequestStatus & aCompletionStatus | The request status to be completed when the operation has finished |
| IMPORT_C void | SaveMessageL | ( | CMsvStore & | aEditStore, |
| TMsvEntry & | aEntry | |||
| ) | ||||
| void | SaveMessageL | ( | ) | [virtual] |
Commits cached changes to the storage controlled by the Message Server.
It can only be called on message contexts. It should be called in the following circumstances:
1. to preserve changes when the context is changed, or when the Client-side MTM object is deleted
2. to enable other parts of the Messaging to access the updated entry, as required, for example, before sending a message
Requirements:
An implementation must update the store and index entry relating to the message context. Typically, the message store should be opened for editing with CMsvEntry::EditStoreL(). It should be updated as follows:
1. body text: call StoreBodyL() to update the store's body text stream
2. address list: update the appropriate MTM-specific area of the store from the data in iAddresseeList
3. subject: if supported, update the appropriate MTM-specific area of the store from the private cache set by SetSubjectL()
Changes can then be committed to the store with CMsvStore::CommitL().
The index entry should also be updated to reflect changes. Possible fields that may need updating include: Description (for subject changes); Details and Multiple Recipients (for recipient changes); and Size. Index entry changes are committed using CMsvEntry::ChangeL().
The function should panic for non-message contexts.
| TInt | ServiceId | ( | ) | const [inline] |
Gets the ID of the current SMS service.
If there is no current SMS service, the ID will be a value of 0. The CSmsClientMtm::RestoreServiceAndSettingsL API can set the SMS service IS. This also restores the SMS service settings.
The ID for the current SMS service
| CSmsSettings & | ServiceSettings | ( | ) | [inline] |
Gets the current SMS service settings.
The current context must be set. If the current context is not set then a panic will occur.
The SMS service settings must have been set or a panic will occur. The CSmsClientMtm::RestoreServiceAndSettingsL API can restore the SMS service settings. This also sets the SMS service ID.
The current (non-const) SMS service settings.
panic
SMCM 1 The current context has not been set (debug only).
panic
SMCM 11 The SMS Service settings have not been set (debug only).
| const CSmsSettings & | ServiceSettings | ( | ) | const [inline] |
Gets the current (const) SMS service settings.
The current context must be set. If the current context is not set then a panic will occur.
The SMS service settings must have been set or a panic will occur. The CSmsClientMtm::RestoreServiceAndSettingsL API can restore the SMS service settings. This also sets the SMS service ID.
The current (const) SMS service settings.
panic
SMCM 1 The current context has not been set (debug only).
panic
SMCM 11 The SMS Service settings have not been set (debug only).
| void | SetMessageCharacterSetL | ( | TSmsDataCodingScheme::TSmsAlphabet | aTsmsAlphabet | ) |
Sets the character encoding value. The character encoding value options are 7-bit, 8-bit and 16-Bit Unicode. By default the character set encoding is 7 bit encoding.
| TSmsDataCodingScheme::TSmsAlphabet aTsmsAlphabet |
| CSmsHeader & | SmsHeader | ( | ) | [inline] |
Gets the message header for a message context.
The current context must be set to a message entry with type KUidMsvMessageEntryValue. If the current context is not set, or is set to an entry not of type KUidMsvMessageEntryValuethen a panic will occur.
The message header object is the SMS MTM encapsulation of an SMS message. The contents of the message header has been extracted from the current context.
The (non-const) message header object.
panic
SMCM 1 The current context has not been set (debug only).
panic
SMCM 2 The current context was not of type KUidMsvMessageEntry (debug only).
| const CSmsHeader & | SmsHeader | ( | ) | const [inline] |
Gets the (const) message header for a message context.
The current context must be set to a message entry with type KUidMsvMessageEntryValue. If the current context is not set, or is set to an entry not of type KUidMsvMessageEntryValuethen a panic will occur.
The message header object is the SMS MTM encapsulation of an SMS message. The contents of the message header has been extracted from the current context.
The (const) message header object.
panic
SMCM 1 The current context has not been set (debug only).
panic
SMCM 2 The current context was not of type KUidMsvMessageEntry (debug only).
| TBool | ValidNumber | ( | const TDesC & | aNumber | ) | const [private] |
| const TDesC & aNumber |
| TMsvPartList | ValidateMessage | ( | TMsvPartList | aPartList | ) | [virtual] |
Validates the current message context.
The precise validation performed is specific to the MTM, but, typically, checks that the specified message parts are well-formed.
Requirements:
Implementation of this function is highly protocol-specific. A minimum step is to check that the current context is a message.
If valid, KErrNone If invalid, identifies the invalid part(s). The error value is the bitmask of the TMsvPartList IDs for each invalid part
| TMsvPartList aPartList | Indicates the message parts for which validation is requested |
| IMPORT_C CSmsSimParamOperation * | WriteSimParamsL | ( | const CMobilePhoneSmspList & | aList, |
| TRequestStatus & | aObserverRequestStatus | |||
| ) | ||||
| const CMobilePhoneSmspList & aList | |
| TRequestStatus & aObserverRequestStatus |