CMmsClientMtm Class Reference

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.

 // 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.

 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.

 // 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.

This function is suitable when the caller is an active object or the caller does not want to immediately change current context to the new message entry.

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. DeprecatedOnly 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.

 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.

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

Get the delivery date of the message.

Get the delivery report request setting of the message.

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

Get the delivery time interval of the message.

From CBaseMtm: Get reference to current entry.

Get the expiration date of the message.

Get the validity period of the message.

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.

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

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

From CBaseMtm: Forward current message to new recipient.

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

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.

From CBaseMtm: React to changes

From CBaseMtm: Query if entry context has 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.

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.

From CBaseMtm: Restore current entry data.

Get the message class.

Get the Uri from which the message can be fetched.

This is valid only for a nofification.

Get the priority of the message.

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

Get the id of the root part of the message.

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.

Get the incoming message size.

This is valid only for a 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.

 // 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.

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.

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.

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.

From CBaseMtm: Query capabilities of MTM.

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.

From CBaseMtm: Removes an entry from addressee list.

Cannot distinguish To, Cc and Bcc.

From CBaseMtm: Remove default service.

Does nothing. Deletion of service not supported.

From CBaseMtm: Send a reply to current message.

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.

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.

Restore factory settings.

Restore settings from ROM to the default service entry and select it as the current service entry. DeprecatedMMS 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.

Send current message in the background.

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

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).

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.

Get the sender of the message.

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.

Get the sending date and time of the message. Valid only for messages received by the phone.

From CBaseMtm: Return session that was set at initialization.

From CBaseMtm: Set current context.

Set the delivery date for the message.

Set the delivery report request setting value for the message.

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

Set the delivery time interval for the message.

Set the expiration date of the message.

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.

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

Set the message class.

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

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.

Set the priority of the message.

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

Set id of the root part of the message.

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.

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.

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.

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.

From CBaseMtm: Set 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.

From CBaseMtm: Switch context to entry defined by aId.

From CBaseMtm: Return type of this Mtm.

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

Validate service.

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