![[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}
|
|
|
|
|
|
||
Location:
SMSCLNT.H
Link against: smcm.lib
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.
MMsvEntryObserver - Provides the interface for notification of events associated with an entry
CBase - Base class for all classes to be instantiated on the heap
CBaseMtm - Provides a high-level interface for accessing and manipulating a Message Server entry
CSmsClientMtm - The SMS client MTM interface
Defined in CSmsClientMtm:
AddAddresseeL(), AddAddresseeL(), AddAddresseeL(), AddAddresseeL(), BioTypeChangedL(), BioTypeChangedL(), ContextEntrySwitched(), ContextEntrySwitched(), CreateMessageL(), CreateMessageL(), Find(), Find(), ForwardL(), ForwardL(), InvokeAsyncFunctionL(), InvokeAsyncFunctionL(), InvokeSyncFunctionL(), LoadMessageL(), LoadMessageL(), NewL(), QueryCapability(), QueryCapability(), ReadSimParamsL(), ReadSimParamsL(), RemoveAddressee(), RemoveAddressee(), ReplyL(), ReplyL(), RestoreServiceAndSettingsL(), RestoreServiceAndSettingsL(), SaveMessageL(), SaveMessageL(), ServiceId(), ServiceId(), ServiceSettings(), ServiceSettings(), ServiceSettings(), ServiceSettings(), SmsHeader(), SmsHeader(), SmsHeader(), SmsHeader(), ValidateMessage(), ValidateMessage(), WriteSimParamsL(), WriteSimParamsL(), ~CSmsClientMtm(), ~CSmsClientMtm()
Inherited from CBase:
Delete(),
Extension_(),
operator new()
Inherited from CBaseMtm:
AddAttachmentL(),
AddEntryAsAttachmentL(),
AddLinkedAttachmentL(),
AddresseeList(),
Body(),
CancelAttachmentOperation(),
ChangeDefaultServiceL(),
CreateAttachmentL(),
DefaultServiceL(),
Entry(),
Filler1(),
Filler2(),
GetInterface(),
HandleEntryEventL(),
HasContext(),
RemoveDefaultServiceL(),
RestoreBodyL(),
Session(),
SetCurrentEntryL(),
SetSubjectL(),
StoreBodyL(),
SubjectL(),
SwitchCurrentEntryL(),
Type(),
iAddresseeList,
iCharFormatLayer,
iMsvEntry,
iParaFormatLayer
Inherited from MMsvEntryObserver:
EMsvChildrenChanged,
EMsvChildrenInvalid,
EMsvChildrenMissing,
EMsvContextInvalid,
EMsvDeletedChildren,
EMsvEntryChanged,
EMsvEntryDeleted,
EMsvEntryMoved,
EMsvNewChildren,
TMsvEntryEvent
static IMPORT_C CSmsClientMtm *NewL(CRegisteredMtmDll &aRegisteredMtmDll, CMsvSession &aSession);
|
|
|
|
inline CSmsHeader &SmsHeader();
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.
|
|
inline const CSmsHeader &SmsHeader() const;
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.
|
|
inline CSmsSettings &ServiceSettings();
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.
|
|
inline const CSmsSettings &ServiceSettings() const;
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.
|
|
inline TInt ServiceId() const;
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.
|
IMPORT_C void RestoreServiceAndSettingsL();
Restores the SMS service ID and SMS service settings.
The SMS service ID is obtained. The service settings for the obtained ID are restored from the message server. The SMS service
ID can be obtained using the CSmsClientMtm::ServiceId API and the SMS settings are accessed via the two CSmsClientMtm::ServiceSettings API overloads.
This API should be used before using any of the other APIs that required the SMS service ID and SMS service settings to be set.
IMPORT_C CSmsSimParamOperation *ReadSimParamsL(TRequestStatus &aObserverRequestStatus);
Reads SMS parameters from the SIM.
It starts a new CSmsSimParamOperation, which uses the SMS Server MTM to read the SMS parameters from the SIM.
If the phone is unable to supply the SMS parameters from the SIM, then the progress information of the CSmsSimParamOperation operation will contain an error.
|
|
IMPORT_C CSmsSimParamOperation *WriteSimParamsL(const CMobilePhoneSmspList &aList, TRequestStatus &aObserverRequestStatus);
Writes SMS parameters to the SIM.
It starts a new CSmsSimParamOperation, which uses the SMS Server to write the specified SIM parameters to the SIM.
If the phone is unable to write the SMS parameters to the SIM, then the progress information of the CSmsSimParamOperation operation will contain an error.
|
|
IMPORT_C CSmsSimParamOperation *ReadSimParamsL(TRequestStatus &aObserverRequestStatus);
|
|
virtual void SaveMessageL();
Commits cached changes to the current message context to the message store.
The current context must be set to a message entry with type KUidMsvServiceEntryValue, KUidMsvFolderEntryValue or KUidMsvMessageEntryValue. If the current context is not set, or is set to an entry with a type that is not supported by this function then a panic will occur.
Both the SMS service ID and SMS service settings must have been set or a panic will occur. The CSmsClientMtm::RestoreServiceAndSettingsL API can restore both of these items.
|
IMPORT_C CSmsSimParamOperation *WriteSimParamsL(const CMobilePhoneSmspList &aList, TRequestStatus &aObserverRequestStatus);
|
|
virtual void LoadMessageL();
Loads the cache with the message data for the current context.
The current context must be set to a message entry with type KUidMsvServiceEntryValue, KUidMsvFolderEntryValue or KUidMsvMessageEntryValue. If the current context is not set, or is set to an entry with a type that is not supported by this function then a panic will occur.
If the current context is of type KUidMsvServiceEntryValue then the SMS service settings are restore from the context. The
SMS service settings can be accessed using the overloaded CSmsClientMtm::ServiceSettings APIs .
If the current context is of type KUidMsvMessageEntryValue then the SMS message object is restore from the context. This can
be accessed using the overloaded CSmsClientMtm::SmsHeader APIs.
If the current context is of type KUidMsvFolderEntryValue then this function does nothing.
|
virtual TMsvPartList ValidateMessage(TMsvPartList aPartList);
Validates the current message context.
The addresses for the message are checked to be well-formed SMS addresses.
The current context must be set. If the current context is not set then a panic will occur.
|
|
|
virtual TMsvPartList Find(const TDesC &aTextToFind, TMsvPartList aPartList);
Searches the specified message part(s) for the plain-text version of the text to be found.
|
|
virtual CMsvOperation *ReplyL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus &aCompletionStatus);
Creates a new SMS message as a reply to the current message context.
The SMS in the current context must be of type SMS-DELIVER, indicating a mobile terminated message.
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 new SMS message has the recipient set to the sender of the message in the current context. It has a type SMS-SUBMIT, indicating
a mobile originated meesage. If the SMS service settings CSmsSettings::ReplyQuoted is true then the reply message will contain the body of the original message, including any EMS elements.
|
|
|
|
virtual void SaveMessageL();
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.
virtual CMsvOperation *ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus &aCompletionStatus);
Creates a SMS forwarded message from the current message context.
The SMS in the current context must be of type SMS-DELIVER, a mobile terminated message, or SMS-SUBMIT, a mobile originated message.
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 new SMS message will have type SMS-SUBMIT, a mobile originated message. The recipient is left blank. The contents that are copied to the new message include the message body, iBioType and description. Also, any EMS components are also copied.
|
|
|
|
virtual void LoadMessageL();
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.
virtual void AddAddresseeL(const TDesC &aRealAddress);
Adds an addressee to the current context.
The current context must be an SMS messge of type SMS-SUBMIT, indicating a mobile originated message. The address is added to the recipient list for the message.
For SMS an address is a telephone number. There is no validation done on the input argument aRealAddress to ensure that it is a valid telephone number.
The TSmsUtilities::GetDetails API can be used prior to this API to find the if a unique alias exists in the contacts database for this particular telephone
number.
The current context must be set to a message entry with type KUidMsvMessageEntryValue. If the current context is set to an entry not of type KUidMsvMessageEntryValuethen a panic will occur.
The SMS MTM maintains an addressee list that matches the recipient list in the SMS message header object. If the two list cannot be maintained together then this function will leave and both lists are unchanged.
|
|
|
virtual TMsvPartList ValidateMessage(TMsvPartList aPartList);
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.
|
|
virtual void AddAddresseeL(const TDesC &aRealAddress, const TDesC &aAlias);
Adds an addressee with an alias to the current context.
The SMS message in the current context must be of type SMS-SUBMIT, indicating a mobile originated message. The address is added to the recipient list for the message.
For SMS an address is a telephone number. There is no validation done on the input argument aRealAddress to ensure that it is a valid telephone number.
The TSmsUtilities::GetDetails API can be used prior to this API to find the if a unique alias exists in the contacts database for this particular telephone
number.
The current context must be set to a message entry with type KUidMsvMessageEntryValue. If the current context is set to an entry not of type KUidMsvMessageEntryValuethen a panic will occur.
The SMS MTM maintains an addressee list that matches the recipient list in the SMS message header object. If the two list cannot be maintained together then this function will leave and both lists are unchanged.
|
|
|
virtual TMsvPartList Find(const TDesC &aTextToFind, TMsvPartList aPartList);
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.
|
|
virtual void RemoveAddressee(TInt aIndex);
Removes a recipient from the current address list.
The recipient to be removed is specified by its index in the list of recipients. This function can only be used when the current context is a mobile-originated message (is a SMS-SUBMIT type message).
The index must be valid or a panic will occur. A valid index is not negative and does not exceed the upper bounds of the list.
The current context must be set to a message entry with type KUidMsvMessageEntryValue. If the current context is set to an entry not of type KUidMsvMessageEntryValuethen a panic will occur.
The SMS MTM maintains an addressee list that matches the recipient list in the SMS message header object. The address is removed from both lists.
|
|
virtual CMsvOperation *ReplyL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus &aCompletionStatus);
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.
|
|
|
virtual TInt QueryCapability(TUid aCapability, TInt &aResponse);
Queries if the MTM supports the capability specified by the supplied UID.
|
|
virtual CMsvOperation *ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus &aCompletionStatus);
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.
|
|
|
virtual void AddAddresseeL(const TDesC &aRealAddress);
Adds an addressee for the current context.
Addresses are not validated by checking their format by this function. Usually that is performed by calling Validate().
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.
|
|
virtual CMsvOperation *InvokeAsyncFunctionL(TInt aFunctionId, const CMsvEntrySelection &aSelection, TDes8 &aParameter, TRequestStatus
&aCompletionStatus);
Invokes asynchronous SMS-specific operations.
The specified operation is performed by the SMS server MTM.
If the requested command is not supported then a panic will occur. The list of supported commands is given by TSmsMtmCommand.
The current context must be set. If the current context is not set then a panic will occur.
|
|
|
virtual void AddAddresseeL(const TDesC &aRealAddress, const TDesC &aAlias);
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 Validate().
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.
|
|
virtual void RemoveAddressee(TInt aIndex);
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.
|
virtual IMPORT_C void CreateMessageL(TMsvId aServiceId);
Creates a new outgoing SMS message entry as a child of the current context.
Used by CSendAs::CreateMessageL to create an outgoing SMS message.
|
virtual TInt QueryCapability(TUid aCapability, TInt &aResponse);
|
|
virtual IMPORT_C void BioTypeChangedL(TUid aBioTypeUid);
Informs the MTM that the context's BIO field is being changed.
The change is as a result of a call to CSendAs::SetBioTypeL(). This function is used by CSendAs::CreateMessageL to create a new outgoing SMS message
|
|
virtual void InvokeSyncFunctionL(TInt aFunctionId, const CMsvEntrySelection &aSelection, TDes8 &aParameter);
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.
|
|
virtual CMsvOperation *InvokeAsyncFunctionL(TInt aFunctionId, const CMsvEntrySelection &aSelection, TDes8 &aParameter, TRequestStatus
&aCompletionStatus);
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.
|
|
|
private: virtual void ContextEntrySwitched();
Resets the current SMS message.
The recipient list in the SMS message header object is emptied. As the SMS MTM maintains an addressee list that matches the recipient list in the SMS message header object, this addressee list is also emptied.
private: virtual void ContextEntrySwitched();
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.
|
Copyright ©2008 Symbian Software Ltd. |
|
![[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}