CMmsClientMtm Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Destructor.

By default Symbian OS constructor is private.

Parameters:

[in]	aRegisteredMtmDll	Reference to Mtm Dll registry class
[in]	aSession	Reference to a Message Server session.

From CBaseMtm: Adds a typed addressee (To, Cc or Bcc).

Parameters:

[in]	aType	recipient type. Possible values: EMsvRecipientTo: Normal recipient. EMsvRecipientCc: Recipient of a carbon copy. EMsvRecipientBcc: Recipient of a blind carbon copy.
[in]	aRealAddress	Address string without alias.
[in]	aAlias	Descriptive name for the recipient.

From CBaseMtm: Adds a typed addressee (To, Cc or Bcc).

Parameters:

[in]	aType	recipient type. Possible values: EMsvRecipientTo: Normal recipient. EMsvRecipientCc: Recipient of a carbon copy. EMsvRecipientBcc: Recipient of a blind carbon copy.
[in]	aRealAddress	Address string without alias.

From CBaseMtm: Adds an addressee, cannot distiguish To, Cc, and Bcc.

New addresses are handled as To type of addresses.

Parameters:

[in]	aRealAddress	Recipient address.
[in]	aAlias	Descriptive name for the recipient.

From CBaseMtm: Adds an addressee, cannot distiguish To, Cc, and Bcc.

New addresses are handled as To type of addresses.

Parameters:

[in]

aRealAddress

Recipient address without alias.

From CBaseMtm: Add a file attachment to the current message entry.

The attachment is referenced by an open file handle and is copied into the message store. This function needs an edit store for the current entry. The caller should not keep the store open. The store is committed and closed after each attachment operation.

If the file is a plain text file with ucs-2 character set MMS Engine will convert the character set to utf-8 and create a text attachment using this character set. The original file is not affected. This must be done because MMS text attachments should be sent using utf-8 character set.

Only one asynchronous operation can be running at any one time.

Parameters:

[in]	aFile	An open file handle for the file attachment. The handle is closed when the function completes.
[in]	aMimeType	Mime type of the attachment file.
[in]	aCharset	IANA MIBEnum of the character set of the attachment. If character set is not relevant for current attachment type, aCharset should be 0.
[in]	aStatus	The request status to complete.

Leave:

System-wide error codes.

 TFileName attachmentFile( _L("c:\\private\\privatedir\\picture123.jpg") );
 RFile fileHandle;
 TBufC8<20> mimeType = _L8( "image/jpeg" );
 TUint charset = 0; // no character set needed for images

 fileHandle.Open( iFs, attachmentFile, EFileShareReadersOnly | EFileRead );
 CleanupClosePush(fileHandle);

 CMsvOperationActiveSchedulerWait* wait = 
     CMsvOperationActiveSchedulerWait::NewLC();

 iMmsClient->AddAttachmentL(
     fileHandle,
     mimeType,
     charset,
     wait->iStatus);

 wait->Start();

 if ( wait->iStatus.Int() != KErrNone )
     { 
     // error handling, e.g. leave
     }

 CleanupStack::PopAndDestroy(); // wait
 CleanupStack::Pop(); // file handle was closed if function did not leave

From CBaseMtm: Add a file attachment to the current message entry.

The attachment is referenced by its file path and is copied into the message store. This function needs an edit store for the current entry. The caller should not keep the store open. The store is committed and closed after each attachment operation. Only one asynchronous operation can be running at any one time.

If the file is a plain text file with ucs-2 character set MMS Engine will convert the character set to utf-8 and create a text attachment using this character set. The original file is not affected. This must be done because MMS text attachments should be sent using utf-8 character set.

Parameters:

[in]	aFilePath	Full path specification of the attachment file.
[in]	aMimeType	Mime type of the attachment file.
[in]	aCharset	IANA MIBEnum of the character set of the attachment. If character set is not relevant for current attachment type, aCharset should be 0.
[in]	aStatus	The request status to complete.

Leave:

System-wide error codes.

 TFileName attachmentFile( _L("c:\\pictures\\picture123.jpg") );
 TBufC8<20> mimeType = _L8( "image/jpeg" );
 TUint charset = 0; // no character set needed for images

 CMsvOperationActiveSchedulerWait* wait = 
     CMsvOperationActiveSchedulerWait::NewLC();

 iMmsClient->AddAttachmentL(
     attachmentFile,
     mimeType,
     charset,
     wait->iStatus);

 wait->Start();

 if ( wait->iStatus.Int() != KErrNone )
     { 
     // error handling, e.g. leave
     }

 CleanupStack::PopAndDestroy(); // wait

 // The attachment has been added, store has been committed, and attachment data
 // has been copied to the message store.
 // If the original file is now modified, it does not affect the attachment file 
 // in the message store any more.

Add attribute to an attribute array (for the use of MMS UI only).

No duplicates are allowed. If an attribute exists, its value is changed. The attributes and their values can be arbitrary strings. There are no restrictions. The purpose is to allow the UI to store some extra information with the message. The values of the attibutes are not included when the message is sent.

Parameters:

[in]	aName	Name of the attribute (case sensitive).
[in]	aValue	Value of the attribute.

Leave:

KErrArgument if length of aName or aValue is 0.

Leave:

KErrNoMemory if memory runs out while adding the attribute.

From CBaseMtm: Add a message entry as an attachment to the current message entry.

Not supported. No Message attachments allowed in MMS.

Leave:

KErrNotSupported

From CBaseMtm: Add a file attachment to the current message entry as a linked file.

The attachment is referenced by its file path and is not copied into the message store. The attachment file is always used from its original location on disk indicated by the aFilePath parameter.

This function needs an edit store for the current entry. The caller should not keep the store open. The store is committed and closed after each attachment operation. Only one asynchronous operation can be running at any one time.

The file must be in some public directory so that MMS Engine can access the file when it is actually sent. If the file is a plain text attachment the character set cannot be converted to utf-8 as the original file cannot be changed. Text files should not be sent as linked attachmets unless the character set of the file is utf-8.

Parameters:

[in]	aFilePath	Full path specification of the attachment file.
[in]	aMimeType	Mime type of the attachment file.
[in]	aCharset	IANA MIBEnum of the character set of the attachment. If character set is not relevant for current attachment type, aCharset should be 0.
[in]	aStatus	The request status to complete.

Leave:

System-wide error codes.

From CBaseMtm: Inform Client MTM about bio type change.

This function does nothing.

From CBaseMtm: Get rich text body.

MMS does not support separate message body. Body is ignored. All MMS message parts are attachments.

Returns:

Rich text body from CBaseMtm.

From CBaseMtm: Get rich text body of the message.

MMS does not support separate message body. Body is ignored. All MMS message parts are attachments.

Returns:

Rich text body from CBaseMtm.

From CBaseMtm: Cancel the current attachment operation.

From CBaseMtm: Change default service.

Does nothing. Changing of default service not supported.

From CBaseMtm: Called after the context of this instance has been changed to another entry.

Create attachment entry and copy specified file to message store.

The user should call SaveMessageL after having added all attachments to update TMsvEntry of the message entry.

Parameters:

[in]	aStore	An open edit store for the message entry. Caller must commit and close the store when ready. (Several attachments can be added before committing the store.)
[in]	aFile	Open file handle, source of the attachment. Caller must close the file afterwards.
[in]	aMimeType	Mime type (content type) of the attachmet in format type/subtype, for example image/jpeg.
[in]	aMimeHeaders	Mime headers for the attachment. If the content type is not defined in aMimeHeaders, the function adds the mime type and subtype from aMimeType. Suggested filename in aMimeHeaders is used as attachment name.
[in]	aAttachmentInfo	Attachment into structure, must be initialized to CMsvAttachment::EMsvFile. If mime type is added into the attachment info, it must be of format type/subtype, for example image/jpeg. On return AttachmentInfo contains data about the attachment. Ownership of attachmentinfo is transferred to attachment manager, it must not be deleted by caller. It must not be put on cleanup stack either. MMS engine keeps it safe until the ownership has been transferred.
[out]	aAttaId	Attachment id of the newly created attachment.

Precondition:

A message entry must exist. It may be a new entry or an old entry to be edited.

CMsvMimeHeaders structure must have been filled in advantage. The following values should be set:

• Content type, for example image
• Content subtype, for example jpeg
• Character set IANA MIBEnum value, for example 106 (utf-8). Should be defined only if the content type is text.
• Content-id if the presentation part refers to the attachments by content-ids.
• Suggested filename (name only, no path), the name that should be used to store the attachment and used as suggested filename when sending the message. If the suggested filename is not set, the name of the attachment file will be used.
• Content-location if the presentation part refers to the attachments by using content-location. The content-location string must contain only us-ascii characters.
• X-type parameters (if needed). These are always handled as pairs of a parameter name and parameter value. A descriptor at an even idex in the array (0, 2, 4, ...) represents the parameter name and a descriptor at an odd index (1, 3, 5, ...) represents the parameter value. If a parameter has no value, it must be indicated by an empty descriptor. The X-type parameter array must always contain an even number of elements.

 // The following code shows a short example of how the attachement
 // creation proceeds.

 // Assume that the client entry is set to the message entry.
 // Attachments are added to the message entry one by one
 CMsvStore* store = iMmsClient->Entry().EditStoreL();
 CleanupStack::PushL(store);

 CMsvAttachment* attaInfo = NULL;
 TMsvAttachmentId attaId = 0;

 RFile attaFile;
 // Set filename of attachment
 TFileName name( _L("C:\\pictures\\picture123.jpg") );

 CMsvMimeHeaders* mimeHeaders = CMsvMimeHeaders::NewL();
 CleanupStack::PushL( mimeHeaders );

 // Set values to mime headers
 mimeHeaders->SetContentTypeL( _L8( "image") );
 mimeHeaders->SetContentSubTypeL( _L8( "jpeg" ) );

 _LIT8(KMimeType, "image/jpeg");
 // CreateAttachment2L will set the content type to attachment Info

 // Open the attachment file for reading
 attaFile.Open( iFs, name, EFileShareReadersOnly | EFileRead );
 CleanupClosePushL(attaFile);

 attaInfo = CMsvAttachment::NewL(CMsvAttachment::EMsvFile);
 // attaInfo ownerhip will be transferred to Attachment Manager.
 // It must not be pushed onto the cleanupStack before calling 
 // CreateAttachment2L.

 TMsvAttachmentId attaId = 0;

 iMmsClient->CreateAttachment2L(
     *store,   // edit store
     attaFile, // open file handle
     KMimeType, // combination type like image/jpeg
     *mimeHeaders,
     attaInfo,
     attaId);
 // Now Attachment Manager owns the attaInfo
 attaInfo = NULL;

 CleanupStack::PopAndDestroy(); // attaFile.Close()
 CleanupStack::PopAndDestroy(); // mimeHeaders

 // Several attachments can be added before committing the store

 // Store must be committed before it is destroyed
 store->CommitL();
 CleanupStack::PopAndDestroy(); // store

From CBaseMtm: Create an attachment and return an open file handle for it.

This function needs an edit store for the current entry. The caller should not keep the store open. The store is committed and closed after each attachment operation. Only one asynchronous operation can be running at any one time.

Parameters:

[in]	aFileName	Suggested filename.
[out]	aAttachmentFile	An open file handle for read/write attachment file. The caller must close the handle.
[in]	aMimeType	Mime type of the attachment file.
[in]	aCharset	IANA MIBEnum of the character set of the attachment. If character set is not relevant for current attachment type, aCharset should be 0.
[in]	aStatus	The request status to complete.

Leave:

System-wide error codes.

 TFileName attachmentFile( _L("picture123.jpg") );
 RFile fileHandle;
 TBufC8<20> mimeType = _L8( "image/jpeg" );
 TUint charset = 0; // no character set needed for images

 CMsvOperationActiveSchedulerWait* wait = 
     CMsvOperationActiveSchedulerWait::NewLC();

 iMmsClient->CreateAttachmentL(
     attachmentFile,
     fileHandle,
     mimeType,
     charset,
     wait->iStatus);

 wait->Start();

 // When the function returns, the store has been committed

 // The attachment file handle is now open for writing the attachment data
 CleanupClosePush(fileHandle);

 if ( wait->iStatus.Int() != KErrNone )
     { 
     // error handling, e.g. leave
     }

 // write file content to open handle
 // ... 

 CleanupStack::PopAndDestroy(); // close file handle
 CleanupStack::PopAndDestroy(); // wait

From CBaseMtm: Create an empty entry as the child of the current context.

Sets the new entry as current context. The entry will be invisible and under construction.

Parameters:

[in]

aServiceId

Service id for the new entry.

 // Context must be set to parent folder for CreateMessageL
 // This example creates the message to drafts folder

 TMsvId serviceId = iMmsClient->DefaultServiceL();
 iMmsClient->SwitchCurrentEntryL( KMsvDraftEntryId );
 iMmsClient->CreateMessageL( serviceId );

 // The message entry is invisible and in "In Preparation" state.
 // The context of CMmsClientMtm has now been switched to the new message entry.
 // The message entry is still completely empty.
 // Continue by adding data to the message
 // ...

Create a new message entry.

Parameters:

[in]	aDestination	Target folder.
[in]	aCompletionStatus	Reference to the status of an active object. This status will contain the relevant error code when the operation completes.

Returns:

Pointer to a message server operation (active object). When the message has been created the progress information of the operation provides the id of the created message in an 8-bit package buffer. While the operation is in progress the package will contain a null id (KMsvNullIndexEntryId). If there is an error while creating the message the message will be deleted and the package will contain a null id.

If the caller is not an active object and the caller wants the context of CMmsClientMtm to be immediately set to the new entry, it is simpler to call CreateMessageL.

See also:

CMmsClientMtm::CreateMessageL

 // This example shows usage with a caller that is not an active object,
 // so a separate waiter is needed. If the caller is an active object,
 // the caller gives its own status to the function and continues 
 // execution in RunL function.

 CMsvOperation* myOperation = NULL;
 CMsvOperationActiveSchedulerWait* wait = 
     CMsvOperationActiveSchedulerWait::NewLC();

 // destinationId specifies the destination folder.
 myOperation = iMmsClient->CreateNewEntryL( destinationId, wait->iStatus );

 CleanupStack::PushL( myOperation );

 wait->Start();

 if ( wait->iStatus.Int() != KErrNone )
     { 
     // error handling, e.g. leave
     }

 // Get the message id
 TPckgBuf<TMsvId> pkg;
 pkg.Copy( myOperation->ProgressL() );
 TMsvId progress = pkg();
 CleanupStack::PopAndDestroy(2); // myOperation, wait;

 // Load the new message
 iMmsClient->SwitchCurrentEntryL( progress );

 // load the default values that were already intialized
 // when the message was created 
 iMmsClient->LoadMessageL();
 
 // continue adding data to the message
 // ...

Create new service entry.

Context is set to the new service entry. Currently a maximum of one service is created, and further requests do not create a new service entry.

Deprecated:

Only one MMS service is supported and it is automatically created. Use DefaultServiceL() to get the id for the default service.

Create a text/plain attachment.

Creates a text attachment from text in a descriptor. Has option to convert all unicode paragraph separator marks to line feeds. Converts text from unicode (ucs-2) to utf-8 before storing it.

Parameters:

[in]	aStore	An open edit store. Caller must commit and close the store (several attachments can be added before committing store).
[out]	aAttachmentId	Attachment id of the new attachment entry.
[in]	aText	Unicode text to be added as a text/plain attachment.
[in]	aFile	Suggested filename for the attachment.
[in]	aConvertParagraphSeparator	Flag that tells the function to search for all 0x2029 characters (Unicode paragraph separator) and to replace them with 0x000d 0x000a (carriage return, line feed). Possible values: ETrue: Convert paragraph separators (default). EFalse: Do not convert paragraph separators.

Precondition:

A message entry must exist. It may be a new entry or an old entry to be edited.

 TFileName attachmentFile( _L("story.txt") );

 CMsvStore* store = iMmsClient->Entry().EditStoreL();
 CleanupStack::PushL(store);
 TMsvAttachmentId attaId = 0;

 TBufC<12> story = _L( "Hello world!" );

 iMmsClient->CreateTextAttachmentL(
     *store,
     attaId,
     story,
     attachmentFile,
     ETrue )

 // When the call returns the id of the attachment will be strored in attaId

 // caller must commit the store as several attachments could be added berore
 // committing the store.
 store->CommitL();
 CleanupStack::PopAndDestroy(); // store

From CBaseMtm: Return id of default service for this MTM type.

Only one MMS service is supported.

Returns:

default service id.

Delete named attribute from list (for the use of MMS UI only).

Parameters:

[in]

aName

Name of the attribute (case sensitive).

Get the delivery date of the message.

Returns:

The date and time when the message will be (or was) delivered to the recipient by the MMSC (in UTC time). If the delivery date has not been defined, TTime(0) is returned.

Get the delivery report request setting of the message.

If the value is not defined, default value from MMS settings is used.

Returns:

delivery report request setting. Possible values:

• EMmsYes: The user wants a delivery report.
• EMmsNo: The user does not want a delivery report.
• 0: Setting has not been defined.

Get the delivery time interval of the message.

Returns:

The length of time in seconds after which the message will be delivered to the recipient by MMS Service Centre. If the delivery time interval is 0, it has not been defined.

From CBaseMtm: Get reference to current entry.

Returns:

Reference to entry instance.

Get the expiration date of the message.

Returns:

The date and time when the message will expire. (in UTC time). If the expiration date has not been defined, TTime(0) will be returned.

Get the validity period of the message.

Returns:

Storage time of the message in MMS Service Centre (in seconds). If the message cannot be delivered to the recipient within the validity period, it will be discarded. If the validity period is 0, it has not been defined.

Fetch pending MMS messages from MMS Service Centre to inbox.

If there are notifications in postponed state they are all fetched. If there are notification in inbox, they are not touched.

Parameters:

[in]	aCompletionStatus	iStatus member of an active object. It will be set as completed when the operating system has relayed the request to the server side of Symbian Messaging System.
[in]	aForced	indicates if the messages should be fetched regardless of current mode settings. ETrue: User initiated fetch, use override. EFalse: Event triggered fetch, fetch only if settings allow.

Returns:

Pointer to an operation active object. The operation will complete when the retrieving has been successfully scheduled. The actual retrieving will happen in the background. If scheduling the fetch fails, the status of CMsvOperation will contain the relevant error code. The operation object must not be deleted before it completes.

Leave:

KErrNoMemory or other Symbian error code. If the function leaves the owner of aCompletionStatus must not be set active because there will be no pending request.

Deprecated:

Postponed fetching mode is no longer supported by UI. In most cases this function would not have any effect.

From CBaseMtm: Searches for specified text in selected parts of current message.

Parameters:

[in]	aTextToFind	Text to search for.
	aPartList	Flags specifying which parts to search. (defined in MTMDEF.H). Possible values: KMsvMessagePartPartBody: Ignored. KMsvMessagePartRecipient: Supported. KMsvMessagePartOriginator: Supported. KMsvMessagePartDescription: Supported. KMsvMessagePartDate: Ignored. KMsvMessagePartAttachments: Ignored.

Returns:

TMsvPartList bitmask specifies in which of the specified parts the text was found.

Check if attribute is present (for the use of MMS UI only).

Parameters:

[in]

aName

Name of the attribute (case sensitive).

Returns:

ETrue if the attribute is found, EFalse otherwise.

From CBaseMtm: Forward current message to new recipient.

Parameters:

[in]	aDestination	Id of the folder where the new message is generated.
[in]	aPartList	Flags specifying which standard message parts are to be included in the response. Possible values: KMsvMessagePartPartBody: Ignored. KMsvMessagePartRecipient: Ignored. KMsvMessagePartOriginator: Ignored. KMsvMessagePartDescription: Subject field is copied. KMsvMessagePartDate: Ignored. KMsvMessagePartAttachments: Ignored. Attachments are always automatically included when forwarding a message.
[in]	aCompletionStatus	Status of an active object. This status will be set as completed when the operation completes.

Returns:

Pointer to an operation active object. The progress information provides the id of the created message when the operation is complete. If there was an error while creating the message, then the message will be deleted and the result will contain a null id. The operation object must not be deleted before it completes.

Get value of an attribute (for the use of MMS UI only).

Parameters:

[in]

aName

Name of the attribute (case sensitive).

Returns:

Value of the attribute.

Leave:

KErrNotFound if attribute not found or the length of aName is 0.

Get the maximum size of the images that can be inserted in the message.

The returned values are 0 if the maximum values have not been defined.

Parameters:

[out]	aHeight	image height in pixels
[out]	aWidth	image width in pixels

From CBaseMtm: React to changes.

Parameters:

[in]	aEvent	Code that tells which event has occurred. Event codes defined in MSVAPI.H
[in]	arg1	Depends on Event
[in]	arg2	Depends on Event
[in]	arg3	Depends on Event

From CBaseMtm: Query if entry context has been set.

Returns:

Status, possible values:

• ETrue: Context has been set.
• EFalse: Context has not been set.

From CBaseMtm: Pass an asychronous request to Server MTM.

Pass a function code to Server MTM. The operation will run in the background. This function can be used to invoke asynchronous protocol-specific operations. The supported functions are private and this function should be called by MMS UI only.

Parameters:

[in]	aFunctionId	Enumeration constant defining the operation.
[in]	aSelection	Array of message entry ids to be uperated on.
[in]	aParameter	A descriptor that contains any parameters required by function specified by aFunctionId.
[in]	aCompletionStatus	Status of an active object. This status will be set as completed when the operation completes

Returns:

Pointer to a message server operation (active object).

From CBaseMtm: Pass a request to MMS Server MTM.

Pass a function code to Server MTM, wait until the function returns. This function can be used to invoke synchronous protocol-specific operations. The supported functions are private and this function should be called by MMS UI only.

Parameters:

[in]	aFunctionId	Enumeration constant defining the operation.
[in]	aSelection	Array of message entry ids to be operated on.
[in]	aParameter	A descriptor that contains any parameters required by function specified by aFunctionId.

Lists all visible and free MMS Notifications from inbox.

Returns:

selection of Notifications in inbox.

From CBaseMtm: Restore current entry data.

Get the message class.

Returns:

Message class. Possible values:

• EMmsClassPersonal: Message is a normal person-to-person message (default).
• EMmsClassAdvertisement: Message contains an advertisement.
• EMmsClassInformational: Message contains data from an information service.
• EMmsClassAuto: Message has been automatically generated by the phone. This class is only valid for a message that is a read report to another message.
• 0: Message class has not been defined. Handle as EMmsClassPersonal.

Get the Uri from which the message can be fetched.

This is valid only for a nofification.

Returns:

Content location of the actual message, the Uri from which the message is fetched from MMS Service Centre.

Get the priority of the message.

Returns:

Message priority, possible values:

• EMmsPriorityLow: Low priority.
• EMmsPriorityNormal: Normal priority.
• EMmsPriorityHigh: High priority.
• 0: Priority has not been defined, treat as EMmsPriorityNormal

Get the time when the message was received in the terminal.

Returns:

Time of the arrival of the message (in UTC time). If the time has not been defined, TTime(0) is returned.

Get the id of the root part of the message.

Returns:

Id of the attachment that starts the message display, KMsvNullIndexEntryId if the root part has not been defined.

Get the message size.

SaveMessageL and LoadMessageL updates the value. This function returns the total amount of disk space the message takes. The actual message size in transmission is smaller due to binary encoding of the headers.

Returns:

size of all message parts in bytes including both attachments and internal header structures.

Get the incoming message size.

This is valid only for a notification.

Returns:

Message size in octets as specified in MMS Notification.

Get a reference to CMmsSettings class.

This method should be used by MMS UI only. Other applications should not touch the MMS settings. The methods are needed in MMS Client API to allow MMS UI to inform MMS Client MTM about changed settings.

The contents of the class are those used by MMS Client MTM when constructing a message. If the settings must be changed, a copy must be made, and SetSettingsL function used to deliver the settings to MMS Client MTM.

Returns:

constant reference to iMmsSettings member of CMmsClientMtm.

 // Usage:
 
 CMmsSettings* settings = CMmsSettings::NewL();
 CleanupStack::PushL( settings );
 iMmsClient->RestoreSettingsL();
 settings->CopyL( iMmsClient->MmsSettings() );
 
 // change settings here...
 // The settings are changed using CMmsSettings API
 
 iMmsClient->SetSettingsL( *settings );
 iMmsClient->StoreSettingsL();
 CleanupStack::PopAndDestroy(); // settings

Factory function.

The only function exported by this polymorphic interface dll. This function is not directly called by the application that needs access, it is called by an instance of CClientMtmRegistry class.

Parameters:

[in]	aRegisteredMtmDll	Mtm Dll registry class
[in]	aSession	Message Server session.

Returns:

Pointer to CMmsClientMtm class.

Get number of times the message has been forwarded.

Returns the number of previous senders in case of a message that has been forwarded from one terminal to another based on the MMS notification only without retrieving the actual message to the terminal first.

Returns:

Number of times the message has been forwarded.

Get the address of a previous sender.

The addresses of the previous senders are defined for messages that have been forwarded without fetching them to the terminal first.

Parameters:

[in]

aSequenceNumber

Indicates the number of the sender in the sequence. 1 is the first sender, a higher number indicates a later sender.

Returns:

Address of the specified previous sender. If the sequence number exceeds the number of senders or is less than 1, an empty string is returned.

Get the time when the message was previously sent (in UTC time).

The function is valid only for messages that have been forwarded without fetching them to the terminal first.

Parameters:

[in]

aSequenceNumber

Indicates the number of the sender in the sequence. 1 is the first sender, a higher number indicates a later sender.

Returns:

Time of the previous sending (in UTC time). If the sequence number exceeds the number of senders or is less than 1, TTime(0) is returned.

From CBaseMtm: Query capabilities of MTM.

Parameters:

[in]	aCapability	UID specifying which capablity is queried. For the possible Capability UIDs and types of return values see mtmuids.h
[out]	aResponse	The value describing the capability at return.

Returns:

error code, Possible values:

• KErrNone: Specified capability is supported and aResponse contains the value of the capability if available.
• KErrNotSupported: Capability is not supported.

Get the read report request setting of the message.

Specifies if the sender wants a read report for current message. If this value is yes and the message has been received by the phone (has "KMmsMessageMobileTerminated" flag) a read report should be sent to the sender of this message when the message is opened for the first time.

Returns:

read report request setting. Possible values:

• EMmsYes: The user wants a read report.
• EMmsNo: The user does not want a read report.
• 0: Setting has not been defined. Do not send a read report.

From CBaseMtm: Removes an entry from addressee list.

Cannot distinguish To, Cc and Bcc.

Parameters:

[in]

aIndex

Index to the array of addresses from AddresseeList() function.

From CBaseMtm: Remove default service.

Does nothing. Deletion of service not supported.

From CBaseMtm: Send a reply to current message.

Parameters:

[in]	aDestination	Id of the folder where the reply is generated.
[in]	aPartlist	Flags specifying which standard message parts are to be included in the response (defined in MTMDEF.H). Following values are possible: KMsvMessagePartPartBody: Ignored. KMsvMessagePartRecipient: Causes reply-to-all. Otherwise reply-to-sender only. KMsvMessagePartOriginator: Ignored. KMsvMessagePartDescription: Subject field is copied. KMsvMessagePartDate: Ignored. KMsvMessagePartAttachments: Ignored. Attachments are never copied to a reply.
[in]	aCompletionStatus	Status of an active object. This status will be set as completed when the operation completes.

Returns:

Pointer to an operation active object. The progress information provides the id of the created message when the operation is complete. If there was an error while creating the message, then the message will be deleted and the result will contain a null id. The operation object must not be deleted before it completes.

Reset all attributes (for the use of MMS UI only).

Removes all attributes (names and values) from the message.

Get the response status value from the message.

This function returns the status MMS Service Centre has sent with a retrieved message or as a response to a failure to send a message. The status code may be used in case of permanent failures to retrieve or failures to send to indicate the reason of the failure.

Returns:

Status code sent by MMS Service Centre. Possible values are defined in OMA MMS Encapsulations specifications, and depend on the version of the MMS Service Centre sending the response.

• Error codes 128 - 136 denote legacy errors from MMS encapsulation version 1.0
• Error codes 192 - 223 denote transient failures.
• Error codes 224 - 255 denote permanent failures.
• 0 means the response status has not been set. Either the operation was successful or the cause of the failure was not set by MMS Service Centre.

Get the response text from the message.

Valid only in cases a response text has been obtained from MMS Service Centre. Possible cases are received messages and messages whose senging has failed. The text may explain the cause of the failure.

Returns:

Response text string. If text is not defined, returns an empty string.

Restore factory settings.

Restore settings from ROM to the default service entry and select it as the current service entry.

Parameters:

aLevel

Defines the operations to be done.

Deprecated:

MMS UI should restore the factory settings directly.

Load settings from disk.

This method should be used by MMS UI only. Other applications should not touch the MMS settings.

From CBaseMtm: Store current entry data.

Get the sender of the message.

Returns:

Address of the sender of the message (for example phone number). If the sender has not been defined, returns an empty string.

Get the sender visibility setting of the message.

Indicates whether the MMS Service Centre should hide the sender's phone number from the recipient. The default is show the sender's number unless the server has a secret number.

Returns:

visibility setting. Possible values:

• EMmsSenderVisibilityDefault: Default visibility.
• EMmsSenderVisibilityHide: Hide the sender's number.
• EMmsSenderVisibilityShow: Show the sender's number even if it is a secret number.
• 0: Sender visibilty has not been defined, use default.

Get the sending date and time of the message.

Valid only for messages received by the phone.

Returns:

the time when MMS Service Centre has received the message from sender (in UTC time). If the time has not been defined, returns TTime(0).

Send a selection of messages in the background.

The messages are moved to Outbox folder before the sending starts. All messages must be in the same place originally (all in drafts, or all in outbox, for example).

Parameters:

[in]	aSelection	List of messages to be sent.
[in]	aCompletionStatus	iStatus member of an active object. It will be set as completed when the operating system has relayed the request to the server side of Symbian Messaging System.
	aSendingTime	Time at which the message selection is to be sent given as UTC time. If aSending time is zero or in the past, the message is scheduled to be sent as soon as possible.

Returns:

Pointer to an operation active object. The operation will complete when the sending has been successfully scheduled. The actual sending will happen in the background. If scheduling the send fails, the status of CMsvOperation will contain the relevant error code. The operation object must not be deleted before it completes.

Leave:

KErrNotFound if aSelection is empty, or other Symbian error code. If the function leaves the owner of aCompletionStatus must not be set active because there will be no pending request.

Send current message in the background.

The message is automatically moved to Outbox folder before the sending starts.

Parameters:

[in]	aCompletionStatus	iStatus member of an active object. It will be set as completed when the operating system has relayed the request to the server side of Symbian Messaging System.
[in]	aSendingTime	Time at which the message is to be sent given as UTC time. If aSending time is zero or in the past, the message is scheduled to be sent as soon as possible.

Returns:

Pointer to an operation active object. The operation will complete when the sending has been successfully scheduled. The actual sending will happen in the background. If scheduling the send fails, the status of CMsvOperation will contain the relevant error code. The operation object must not be deleted before it completes.

Leave:

KErrNoMemory or other Symbian error code. If the function leaves the owner of aCompletionStatus must not be set active because there will be no pending request.

Send a read report to the sender of a message.

This function should be called when a new message is opened and the sender of the message has specified that he wants a read report for the message in question. This function should not be called if the settings indicate that sending read reports is not allowed.

Parameters:

[in]	aReadMessageId	Id of the message for which a read report should be sent. The message must not be locked and the caller should not have CMsvStore open for the message as MMS Client Mtm must be able to read header fields from the original message.
[in]	aCompletionStatus	iStatus member of an active object. It will be set as completed when the operating system has relayed the request to the server side of Symbian Messaging System.
[in]	aReadStatus	indicates if the message was read Possible values: EMmsReadStatusRead: The message was read. EMmsReadStatusDeletedWithoutBeingRead: The message was deleted without being read.

Returns:

Pointer to an operation active object. The operation will complete when the sending of the read report has been successfully scheduled. The actual sending will happen in the background. If scheduling the send fails, the status of CMsvOperation will contain the relevant error code. If the sender of the message has not requested a read report or read report sending is not allowed, the operation completes with error code KErrGeneral. The operation object must not be deleted before it completes.

Leave:

KErrLocked if the message entry cannot be accessed.

From CBaseMtm: Return session that was set at initialization.

Returns:

Reference to Message Server session object.

From CBaseMtm: Set current context.

Parameters:

[in]

aEntry

Pointer to entry instance.

Set the delivery date for the message.

Parameters:

[in]

aDate

The date and time when the message will be delivered to the recipient by the MMSC (in UTC time). The date must be later than 1970-01-01, 00:00:00 GMT. If neither delivery time interval or delivery date have been defined, MMS Service Centre will deliver the message immediately.

Set the delivery report request setting value for the message.

If the value is not set, default value from MMS settings will be used.

Parameters:

[in]

aRequest

tells if the user wants a delivery report for this message. Possible values: EMmsYes: The user wants a delivery report. EMmsNo: The user does not want a delivery report.

Set the delivery time interval for the message.

Parameters:

[in]

aInterval

The length of time in seconds after which the message will be delivered to the recipient by the MMS Service Centre. If neither delivery time interval or delivery date have been defined, MMS Service Centre will deliver the message immediately.

Set the expiration date of the message.

Parameters:

[in]

aDate

The date and time when the message will expire (In UTC time). The date must be later than 1970-01-01, 00:00:00 GMT If the MMS Service Centre cannot deliver the message to the recipient before the expiration date, the message will be discarded. If expiration date or validity period have not been defined, default is used.

Set the validity period of the message.

If the validity period is not defined for the message, default validity period from MMS settings or MMS Service Centre will be used.

Parameters:

[in]

aInterval

The length of time in seconds after which the message will be discarded by MMS Service Centre. MMSC may limit the maximum length of the validity period.

Set the maximum size of the images that can be inserted in the message.

Parameters:

[in]	aHeight	Image height in pixels.
[in]	aWidth	Image width in pixels.

Set the message class.

If message class is not explicitly set, the message will have class "Personal" by default.

Parameters:

[in]

aMessageClass

Message class code. Possible values: EMmsClassPersonal: Message is a normal person-to-person message (default). EMmsClassAdvertisement: Message contains an advertisement. EMmsClassInformational: Message contains data from an information service. EMmsClassAuto: Message has been automatically generated by the phone. This class is only valid for a message that is a read report to another message.

Set the message description string.

This provides a method to override the default message description. The next SaveMessageL saves the description text in the TMsvEntry::iDescription field. This field is shown in Message Centre message lists to describe the contents of the message. Normally it is the message subject, but if there is no subject in the message, the caller may set some text from a text part of the message as the description.

Note that this method does not check the text length, so avoid long descriptions to minimize memory usage.

Parameters:

[in]

aText

Message description

Set the priority of the message.

If the priority of the message is not set, the default priority will be "normal".

Parameters:

[in]

aPriority

Message priority, possible values: EMmsPriorityLow: Low priority. EMmsPriorityNormal: Normal priority. EMmsPriorityHigh: High priority.

Set id of the root part of the message.

Parameters:

[in]

aId

Attachment Id of the message part which controls the display of the message. Should point to the SMIL part if present.

Set the read report request setting value for the message.

Specifies if the user wants a read report for the current message. If this value is Yes, the recipient phone should send a read report when the user opens the message for the first time.

Parameters:

[in]

aRequest

read report request setting. Possible values: EMmsYes: The user wants a read report. EMmsNo: The user does not want a read report.

Set the sender of the message.

If the sender of the message is not explicitly defined, the Proxy-Relay or MMS Service Centre will add the sender's phone number.

Parameters:

[in]

aAlias

The phone number of the sender of the message. Maximum length 256 characters. This string will be included as the sender of the message when the message is sent, but the MMS Service Centre will check the validity of the value and replace it with the actual phone number of the sender if it is not correct.

Set the sender visibility setting for the message.

Indicates whether the MMS Service Centre should hide the sender's phone number from the recipient. If the value is not defined, default is used. The default is to show the sender's number unless the sender has a secret number.

Parameters:

[in]

aVisibility

Visibility of the sender's phone number to the recipient. Possible values: EMmsSenderVisibilityDefault: Use default visibility. EMmsSenderVisibilityHide: Hide the sender's number. EMmsSenderVisibilityShow: Show the sender's number even if it is a secret number.

Copy the values from aSettings to CMmsClientMtm.

This method should be used by MMS UI only. Other applications should not touch the MMS settings.

Used to provide new settings to MMS Client MTM when settings have been changed. Will affect only messages created after the settings have been changed.

Use function StoreSettingsL to save the settings on disk.

Parameters:

[in]

aSettings

New values for CMmsSettings

From CBaseMtm: Set message subject.

Parameters:

[in]

aSubject

Message subject.

Save settings to disk.

This method should be used by MMS UI only. Other applications should not touch the MMS settings.

From CBaseMtm: Get message subject.

Returns:

Message subject.

From CBaseMtm: Switch context to entry defined by aId.

Parameters:

[in]

aId

Entry id in message store.

From CBaseMtm: Return type of this Mtm.

Returns:

Registered Mtm type.

From CBaseMtm: Checks that selected parts of current message are legal.

Parameters:

[in]

aPartList

Flags specifying which parts to validate. (defined in MTMDEF.H). Possible values: KMsvMessagePartPartBody: Ignored. MMS engine does not support separate message body. KMsvMessagePartRecipient: Supported. KMsvMessagePartOriginator Supported. KMsvMessagePartDescription: Ignored. Description is always valid KMsvMessagePartDate: Ignored. Date is always valid KMsvMessagePartAttachments: Supported.

Returns:

TMsvPartList bitmask identifies each invalid part. If all parts are valid, returned value is 0.

Validate service.

Checks that access point refers to a valid entry in comms database.

Parameters:

[in]

aServiceId

Id of the MMS service

Returns:

Error code.

• KErrNone: The service is OK.
• KErrNotFound: The service id is incorrect.
• KMmsErrorInvalidSettings: The settings contain invalid values. This error is possible only if the settings file has been corrupted.
• KMmsErrorNoWAPAccessPoint: No access point has been defined.
• KMmsErrorAP1Invalid: MMS access point refers to an invalid entry in comms database.
• KMmsErrorNoURI1: Home page has not been defined for MMS access point