1 mmsclient.h

     1 /*

     2 * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  

    15 *     Client Mtm for multimedia messaging.

    16 *     This is the API for accessing multimedia messaging engine.

    17 *

    18 */

    19 

    20 

    21 

    22 #ifndef MMSCLIENT_H

    23 #define MMSCLIENT_H

    24 

    25 //  INCLUDES

    26 #include  <mtclbase.h> // base client mtm

    27 #include  <e32std.h>   // TTimeInterval & TTime

    28 #include  "mmsconst.h" // common constants

    29 

    30 // CONSTANTS

    31 

    32 // MACROS

    33 

    34 // DATA TYPES

    35 typedef struct

    36     {

    37     const TUint SymbianCharsetUID;

    38     const TUint IANAMIBEnum;

    39     }TMmsCharacterSetLookup;

    40 

    41 // FUNCTION PROTOTYPES

    42 

    43 // FORWARD DECLARATIONS

    44 class CMmsSettings;

    45 class CMmsHeaders;

    46 class CMsvMimeHeaders;

    47 class CMsvFindText;

    48 class CMmsAttachmentWaiter;

    49 

    50 // CLASS DECLARATION

    51 

    52 /**

    53 *  Client Mtm for multimedia messaging subsystem. 

    54 *

    55 *  This class will be the interface to the UI component and other 

    56 *  messaging component that might want to handle multimedia messages 

    57 *  (For example SendAs interface).

    58 * 

    59 *  This class provides access to MMS specific headers in the message.

    60 *

    61 *  Note: new functions are added as the last virtual functions in order

    62 *  not to to break the vtable

    63 *

    64 * @code

    65 *  // Example of getting access to this class:

    66 *

    67 *  // Called by an application that implements

    68 *  // MMsvSessionObserver interface

    69 *

    70 *  iSession = CMsvSession::OpenSyncL(*this);

    71 *  CleanupStack::PushL(iSession);

    72 *  iClientMtmRegistry = CClientMtmRegistry::NewL(*iSession);

    73 *  CleanupStack::PushL(iClientMtmRegistry);

    74 *  iMmsClient = (CMmsClientMtm *) iClientMtmRegistry->

    75 *               NewMtmL(KUidMsgTypeMultimedia);

    76 *  CleanupStack::PushL(iMmsClient);

    77 *

    78 *  // - do other initialization

    79 *

    80 *  CleanupStack::Pop(3); //iSession, iClientMtmRegistry, iMmsClient

    81 *

    82 *  // - call any public functions in CMmsClientMtm

    83 *

    84 *  // When the application finishes,

    85 *  // it must delete the objects in reverse order:

    86 *  delete iMmsClient;

    87 *  delete iClientMtmRegistry;

    88 *  delete iSession;

    89 * @endcode

    90 */

    91 

    92 class CMmsClientMtm :public CBaseMtm

    93     {

    94     public:  // Constructors and destructor

    95 

    96         /**

    97         * Factory function. 

    98         *

    99         * The only function exported by this polymorphic interface dll. 

   100         * This function is not directly called by the application that needs 

   101         * access, it is called by an instance of CClientMtmRegistry class.

   102         *

   103         * @param[in] aRegisteredMtmDll Mtm Dll registry class

   104         * @param[in] aSession Message Server session.

   105         * @return Pointer to CMmsClientMtm class.

   106         */

   107         IMPORT_C static CMmsClientMtm* NewL(

   108             CRegisteredMtmDll& aRegisteredMtmDll,

   109             CMsvSession& aSession );

   110 

   111         /**

   112         * Destructor.

   113         */

   114         virtual ~CMmsClientMtm();

   115 

   116     public:  // New functions

   117 

   118         // ----------------------------------------------------------

   119         // Functions to create and modify message entries

   120 

   121         /**

   122         * Create a new message entry.

   123         *

   124         * @param[in] aDestination Target folder.

   125         * @param[in] aCompletionStatus Reference to the status of an active object. 

   126         *     This status will contain the relevant error code when the operation 

   127         *     completes.

   128         * @return Pointer to a message server operation (active object). 

   129         *     When the message has been created the progress information of the 

   130         *     operation provides the id of the created message in an 8-bit package 

   131         *     buffer. While the operation is in progress the package will contain a 

   132         *     null id (KMsvNullIndexEntryId). If there is an error while 

   133         *     creating the message the message will be deleted and the 

   134         *     package will contain a null id.

   135         *

   136         * This function is suitable when the caller is an active object or the 

   137         * caller does not want to immediately change current context to the 

   138         * new message entry.

   139         *

   140         * If the caller is not an active object and the caller wants the context 

   141         * of CMmsClientMtm to be immediately set to the new entry, it is simpler 

   142         * to call CreateMessageL.

   143         * @see CMmsClientMtm::CreateMessageL

   144         *

   145         * @code

   146         * // This example shows usage with a caller that is not an active object,

   147         * // so a separate waiter is needed. If the caller is an active object,

   148         * // the caller gives its own status to the function and continues 

   149         * // execution in RunL function.

   150         *

   151         * CMsvOperation* myOperation = NULL;

   152         * CMsvOperationActiveSchedulerWait* wait = 

   153         *     CMsvOperationActiveSchedulerWait::NewLC();

   154         *

   155         * // destinationId specifies the destination folder.

   156         * myOperation = iMmsClient->CreateNewEntryL( destinationId, wait->iStatus );

   157         *

   158         * CleanupStack::PushL( myOperation );

   159         *

   160         * wait->Start();

   161         *

   162         * if ( wait->iStatus.Int() != KErrNone )

   163         *     { 

   164         *     // error handling, e.g. leave

   165         *     }

   166         *

   167         * // Get the message id

   168         * TPckgBuf<TMsvId> pkg;

   169         * pkg.Copy( myOperation->ProgressL() );

   170         * TMsvId progress = pkg();

   171         * CleanupStack::PopAndDestroy(2); // myOperation, wait;

   172         *

   173         * // Load the new message

   174         * iMmsClient->SwitchCurrentEntryL( progress );

   175         *

   176         * // load the default values that were already intialized

   177         * // when the message was created 

   178         * iMmsClient->LoadMessageL();

   179         * 

   180         * // continue adding data to the message

   181         * // ...

   182         * @endcode

   183         */

   184         virtual CMsvOperation* CreateNewEntryL(

   185             TMsvId aDestination,

   186             TRequestStatus& aCompletionStatus);

   187 

   188 

   189         // -------------------------------------------------------------------

   190         // FUNCTIONS TO HANDLE MMSC SETTINGS

   191         //

   192         // Only one MMS service entry may be created!

   193         //

   194         // The Client MTM maintains cached MMS service settings, referred to 

   195         // as current service below. Some of those cached settings are used 

   196         // as template values when a new multimedia message is created. 

   197         //

   198         // Use Base MTM functions to get default service id.

   199 

   200 // <DEPRECATED>

   201         /**

   202         * Create new service entry.

   203         *

   204         * Context is set to the new service entry. 

   205         * Currently a maximum of one service is created, and further requests 

   206         * do not create a new service entry.

   207         * @deprecated Only one MMS service is supported and it is automatically created. 

   208         * Use DefaultServiceL() to get the id for the default service.

   209         */

   210         virtual void CreateServiceL();

   211 // </DEPRECATED>

   212 

   213         // Functions to load, save, and access MMS Settings.

   214         // There is no need to change the context when these functions are used.

   215         //

   216 

   217         /**

   218         * Get a reference to CMmsSettings class.

   219         *

   220         * This method should be used by MMS UI only. Other applications should 

   221         * not touch the MMS settings. The methods are needed in MMS Client API 

   222         * to allow MMS UI to inform MMS Client MTM about changed settings. 

   223         *

   224         * The contents of the class are those used by MMS Client MTM 

   225         * when constructing a message. If the settings must be changed, 

   226         * a copy must be made, and SetSettingsL function used to deliver 

   227         * the settings to MMS Client MTM.

   228         *

   229         * @return constant reference to iMmsSettings member of CMmsClientMtm.

   230         *

   231         * @code

   232         * // Usage:

   233         * 

   234         * CMmsSettings* settings = CMmsSettings::NewL();

   235         * CleanupStack::PushL( settings );

   236         * iMmsClient->RestoreSettingsL();

   237         * settings->CopyL( iMmsClient->MmsSettings() );

   238         * 

   239         * // change settings here...

   240         * // The settings are changed using CMmsSettings API

   241         * 

   242         * iMmsClient->SetSettingsL( *settings );

   243         * iMmsClient->StoreSettingsL();

   244         * CleanupStack::PopAndDestroy(); // settings

   245         *

   246         * @endcode

   247         */

   248         virtual const CMmsSettings& MmsSettings();

   249 

   250         /**

   251         * Copy the values from aSettings to CMmsClientMtm.

   252         *

   253         * This method should be used by MMS UI only. Other applications should 

   254         * not touch the MMS settings. 

   255         *

   256         * Used to provide new settings to MMS Client MTM when settings have 

   257         * been changed. Will affect only messages created after the settings  

   258         * have been changed. 

   259         *

   260         * Use function StoreSettingsL to save the settings on disk.

   261         *

   262         * @param[in] aSettings New values for CMmsSettings

   263         */

   264         virtual void SetSettingsL( const CMmsSettings& aSettings );

   265 

   266         /**

   267         * Save settings to disk.

   268         *

   269         * This method should be used by MMS UI only. Other applications should 

   270         * not touch the MMS settings. 

   271         */

   272         virtual void StoreSettingsL();

   273 

   274         /**

   275         * Load settings from disk.

   276         *

   277         * This method should be used by MMS UI only. Other applications should 

   278         * not touch the MMS settings.

   279         */

   280         virtual void RestoreSettingsL();

   281 

   282 // <DEPRECATED>

   283         /**

   284         * Restore factory settings.

   285         *

   286         * Restore settings from ROM to the default service entry and select it 

   287         * as the current service entry.

   288         * @param aLevel Defines the operations to be done. 

   289         * @deprecated MMS UI should restore the factory settings directly.

   290         */

   291         virtual void RestoreFactorySettingsL(

   292             TMmsFactorySettingsLevel aLevel = EMmsFactorySettingsLevelNormal );

   293 // </DEPRECATED>

   294 

   295         /**

   296         * Validate service.

   297         *

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

   299         *

   300         * @param[in] aServiceId Id of the MMS service

   301         * @return Error code. 

   302         * - KErrNone: The service is OK.

   303         * - KErrNotFound: The service id is incorrect.

   304         * - KMmsErrorInvalidSettings: The settings contain invalid values. 

   305         * This error is possible only if the settings file has been corrupted.

   306         * - KMmsErrorNoWAPAccessPoint: No access point has been defined.

   307         * - KMmsErrorAP1Invalid: MMS access point refers to an invalid entry in comms 

   308         * database.

   309         * - KMmsErrorNoURI1: Home page has not been defined for MMS access point

   310         */

   311         virtual TInt ValidateService( TMsvId aServiceId );

   312 

   313         // -------------------------------------------------------------------

   314         // FUNCTIONS TO HANDLE MMS HEADERS

   315 

   316         // Accessors and mutators (getters and setters) for header fields.

   317         // Some of these header fields have default values that are assigned

   318         // from cached service settings when a new header is allocated.

   319         // Some header fields are needed by protocol only.

   320         // Those headers don't have accessors and mutators here,

   321         // as they are used by Server MTM who accesses them directly

   322         // through functions offered by CMmsHeaders.

   323 

   324         /**

   325         * Set the sender of the message.

   326         *

   327         * If the sender of the message is not explicitly defined, the Proxy-Relay 

   328         *     or MMS Service Centre will add the sender's phone number.

   329         *

   330         * @param[in] aAlias The phone number of the sender of the message. 

   331         *     Maximum length 256 characters. This string will be included 

   332         *     as the sender of the message when the message is sent, but 

   333         *     the MMS Service Centre will check the validity of the 

   334         *     value and replace it with the actual phone number of the 

   335         *     sender if it is not correct.

   336         */

   337         virtual void SetSenderL( const TDesC& aAlias );

   338 

   339         /**

   340         * Get the sender of the message.

   341         *

   342         * @return Address of the sender of the message (for example phone number). 

   343         *     If the sender has not been defined, returns an empty string.

   344         */

   345         virtual const TPtrC Sender() const;

   346 

   347         /**

   348         * Set the message class.

   349         *

   350         * If message class is not explicitly set, the message will have 

   351         *     class "Personal" by default.

   352         *

   353         * @param [in] aMessageClass Message class code. Possible values: 

   354         * - EMmsClassPersonal: Message is a normal person-to-person message (default).

   355         * - EMmsClassAdvertisement: Message contains an advertisement.

   356         * - EMmsClassInformational: Message contains data from an information service.

   357         * - EMmsClassAuto: Message has been automatically generated by the phone. 

   358         *   This class is only valid for a message that is a read report to another message.

   359         */

   360         virtual void SetMessageClass( TMmsMessageClass aMessageClass );

   361 

   362         /**

   363         * Get the message class.

   364         *

   365         * @return Message class. Possible values: 

   366         * - EMmsClassPersonal: Message is a normal person-to-person message (default).

   367         * - EMmsClassAdvertisement: Message contains an advertisement.

   368         * - EMmsClassInformational: Message contains data from an information service.

   369         * - EMmsClassAuto: Message has been automatically generated by the phone. 

   370         *   This class is only valid for a message that is a read report to another message.

   371         * - 0: Message class has not been defined. Handle as EMmsClassPersonal.

   372         */

   373         virtual TInt MessageClass() const;

   374 

   375         /**

   376         * Set the validity period of the message.

   377         *

   378         * If the validity period is not defined for the message, default 

   379         * validity period from MMS settings or MMS Service Centre will be used.

   380         *

   381         * @param[in] aInterval The length of time in seconds after which the 

   382         *     message will be discarded by MMS Service Centre. 

   383         *     MMSC may limit the maximum length of the validity period. 

   384         */

   385         virtual void SetExpiryInterval( TTimeIntervalSeconds aInterval );

   386 

   387         /**

   388         * Get the validity period of the message.

   389         *

   390         * @return Storage time of the message in MMS Service Centre (in seconds). 

   391         *     If the message cannot be delivered to the recipient within the 

   392         *     validity period, it will be discarded. If the validity period is 0, 

   393         *     it has not been defined.

   394         */

   395         virtual TTimeIntervalSeconds ExpiryInterval() const;

   396 

   397         /**

   398         * Set the expiration date of the message.

   399         *

   400         * @param[in] aDate The date and time when the message will expire 

   401         *     (In UTC time). The date must be later than 1970-01-01, 00:00:00 GMT 

   402         *     If the MMS Service Centre cannot deliver the message to the recipient 

   403         *     before the expiration date, the message will be discarded. If expiration 

   404         *     date or validity period have not been defined, default is used.

   405         */

   406         virtual void SetExpiryDate( TTime aDate );

   407 

   408         /**

   409         * Get the expiration date of the message.

   410         *

   411         * @return The date and time when the message will expire. (in UTC time). 

   412         *      If the expiration date has not been defined, TTime(0) will be 

   413         *      returned.

   414         */

   415         virtual TTime ExpiryDate() const;

   416 

   417         /**

   418         * Set the delivery time interval for the message.

   419         *

   420         * @param[in] aInterval The length of time in seconds after which the message 

   421         *     will be delivered to the recipient by the MMS Service Centre. 

   422         *     If neither delivery time interval or delivery date have been defined,

   423         *     MMS Service Centre will deliver the message immediately.

   424         */

   425         virtual void SetDeliveryTimeInterval( TTimeIntervalSeconds aInterval );

   426 

   427         /**

   428         * Get the delivery time interval of the message.

   429         *

   430         * @return The length of time in seconds after which the message will be 

   431         *     delivered to the recipient by MMS Service Centre. If the delivery 

   432         *     time interval is 0, it has not been defined.

   433         */

   434         virtual TTimeIntervalSeconds DeliveryTimeInterval() const;

   435 

   436         /**

   437         * Set the delivery date for the message.

   438         *

   439         * @param[in] aDate The date and time when the message will be delivered 

   440         *     to the recipient by the MMSC (in UTC time). The date must be 

   441         *     later than 1970-01-01, 00:00:00 GMT. If neither delivery time 

   442         *     interval or delivery date have been defined, MMS Service Centre 

   443         *     will deliver the message immediately.

   444         */

   445         virtual void SetDeliveryDate( TTime aDate );

   446 

   447         /**

   448         * Get the delivery date of the message.

   449         *

   450         * @return The date and time when the message will be (or was) delivered 

   451         *     to the  recipient by the MMSC (in UTC time). If the delivery date 

   452         *     has not been defined, TTime(0) is returned.

   453         */

   454         virtual TTime DeliveryDate() const;

   455 

   456         /**

   457         * Set the priority of the message. 

   458         *

   459         * If the priority of the message is not set, the default priority will be 

   460         *     "normal".

   461         *

   462         * @param[in] aPriority Message priority, possible values:

   463         * - EMmsPriorityLow:     Low priority.

   464         * - EMmsPriorityNormal:  Normal priority.

   465         * - EMmsPriorityHigh:    High priority.

   466         */

   467         virtual void SetMessagePriority( TMmsMessagePriority aPriority );

   468 

   469         /**

   470         * Get the priority of the message.

   471         *

   472         * @return Message priority, possible values:

   473         * - EMmsPriorityLow:     Low priority.

   474         * - EMmsPriorityNormal:  Normal priority.

   475         * - EMmsPriorityHigh:    High priority.

   476         * - 0: Priority has not been defined, treat as EMmsPriorityNormal

   477         */

   478         virtual TInt MessagePriority() const;

   479 

   480         /**

   481         * Set the sender visibility setting for the message.

   482         *

   483         * Indicates whether the MMS Service Centre should hide the sender's phone 

   484         *     number from the recipient. If the value is not defined, default is 

   485         *     used. The default is to show the sender's number unless the sender 

   486         *     has a secret number.

   487         *

   488         * @param[in] aVisibility Visibility of the sender's phone number to the 

   489         *    recipient. Possible values:

   490         * - EMmsSenderVisibilityDefault: Use default visibility.

   491         * - EMmsSenderVisibilityHide: Hide the sender's number.

   492         * - EMmsSenderVisibilityShow: Show the sender's number even if it is a 

   493         *     secret number.

   494         */

   495         virtual void SetSenderVisibility(

   496             TMmsMessageSenderVisibility aVisibility );

   497 

   498         /**

   499         * Get the sender visibility setting of the message.

   500         *

   501         * Indicates whether the MMS Service Centre should hide the sender's phone 

   502         *     number from the recipient. The default is show the sender's number 

   503         *     unless the server has a secret number.

   504         *

   505         * @return visibility setting. Possible values:

   506         * - EMmsSenderVisibilityDefault: Default visibility.

   507         * - EMmsSenderVisibilityHide: Hide the sender's number.

   508         * - EMmsSenderVisibilityShow: Show the sender's number even if it is a 

   509         *     secret number.

   510         * - 0: Sender visibilty has not been defined, use default.

   511         */

   512         virtual TInt SenderVisibility() const;

   513 

   514         /**

   515         * Set the delivery report request setting value for the message.

   516         *

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

   518         *

   519         * @param[in] aRequest tells if the user wants a delivery report for this 

   520         *    message. Possible values: 

   521         * - EMmsYes: The user wants a delivery report.

   522         * - EMmsNo:  The user does not want a delivery report.

   523         */

   524         virtual void SetDeliveryReport(

   525             TMmsYesNo aRequest );

   526 

   527         /**

   528         * Get the delivery report request setting of the message.

   529         *

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

   531         *

   532         * @return delivery report request setting. Possible values: 

   533         * - EMmsYes: The user wants a delivery report.

   534         * - EMmsNo:  The user does not want a delivery report.

   535         * - 0: Setting has not been defined.

   536         */

   537         virtual TInt DeliveryReport() const;

   538 

   539         /**

   540         * Set the read report request setting value for the message.

   541         *

   542         * Specifies if the user wants a read report for the current message. 

   543         * If this value is Yes, the recipient phone should send a read report  

   544         *    when the user opens the message for the first time.

   545         *

   546         * @param[in] aRequest read report request setting. Possible values:

   547         * - EMmsYes: The user wants a read report.

   548         * - EMmsNo:  The user does not want a read report.

   549         */

   550         virtual void SetReadReply( TMmsYesNo aRequest );

   551 

   552         /**

   553         * Get the read report request setting of the message.

   554         *

   555         * Specifies if the sender wants a read report for current message. 

   556         * If this value is yes and the message has been received by the phone 

   557         *     (has "KMmsMessageMobileTerminated" flag) a read report should be 

   558         *     sent to the sender of this message when the message is opened 

   559         *     for the first time.

   560         *

   561         * @return read report request setting. Possible values:

   562         * - EMmsYes: The user wants a read report.

   563         * - EMmsNo:  The user does not want a read report.

   564         * - 0: Setting has not been defined. Do not send a read report.

   565         */

   566         virtual TInt ReadReply() const;

   567 

   568         /**

   569         * Get the sending date and time of the message. 

   570         * Valid only for messages received by the phone.

   571         * @return the time when MMS Service Centre has received the message  

   572         *     from sender (in UTC time). 

   573         *     If the time has not been defined, returns TTime(0).

   574         */

   575         virtual TTime SendingDate() const;

   576 

   577         /**

   578         * Get the response text from the message.

   579         *

   580         * Valid only in cases a response text has been obtained from MMS Service 

   581         *     Centre. Possible cases are received messages and messages whose 

   582         *     senging has failed. The text may explain the cause of the failure.

   583         *

   584         * @return Response text string. If text is not defined, returns an empty 

   585         *     string.

   586         * @since 2.0

   587         */

   588         virtual TPtrC ResponseText() const;

   589 

   590         /**

   591         * Get the response status value from the message.

   592         *

   593         * This function returns the status MMS Service Centre has sent with a 

   594         *     retrieved message or as a response to a failure to send a message. 

   595         * The status code may be used in case of permanent failures to retrieve 

   596         *     or failures to send to indicate the reason of the failure.

   597         *

   598         * @return Status code sent by MMS Service Centre. Possible values are 

   599         *     defined in OMA MMS Encapsulations specifications, and depend on 

   600         *     the version of the MMS Service Centre sending the response. 

   601         * - Error codes 128 - 136 denote legacy errors from MMS encapsulation 

   602         *     version 1.0

   603         * - Error codes 192 - 223 denote transient failures.

   604         * - Error codes 224 - 255 denote permanent failures.

   605         * - 0 means the response status has not been set. Either the operation was 

   606         *     successful or the cause of the failure was not set by MMS Service Centre.

   607         * @since 3.0

   608         */

   609         virtual TInt ResponseStatus() const;

   610 

   611         /**

   612         * Get number of times the message has been forwarded.

   613         *

   614         * Returns the number of previous senders in case of a message that 

   615         *     has been forwarded from one terminal to another based on the 

   616         *     MMS notification only without retrieving the actual message to 

   617         *     the terminal first.

   618         *

   619         * @return Number of times the message has been forwarded.

   620         * @since 3.0

   621         */

   622         virtual TInt NumberOfPreviousSenders() const;

   623 

   624         /**

   625         * Get the address of a previous sender.

   626         *

   627         * The addresses of the previous senders are defined for messages that 

   628         *     have been forwarded without fetching them to the terminal first.

   629         *

   630         * @param[in] aSequenceNumber Indicates the number of the sender in the 

   631         *     sequence. 1 is the first sender, a higher number indicates a later 

   632         *     sender.

   633         * @return Address of the specified previous sender. If the sequence number 

   634         *     exceeds the number of senders or is less than 1, an empty string is 

   635         *     returned.

   636         * @since 3.0

   637         */

   638         virtual TPtrC PreviousSender( TInt aSequenceNumber ) const;

   639 

   640         /**

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

   642         *

   643         * The function is valid only for messages that have been forwarded 

   644         *     without fetching them to the terminal first.

   645         *

   646         * @param[in] aSequenceNumber Indicates the number of the sender in the 

   647         *     sequence. 1 is the first sender, a higher number indicates a later 

   648         *     sender.

   649         * @return Time of the previous sending (in UTC time). If the sequence 

   650         *     number exceeds the number of senders or is less than 1, TTime(0)  

   651         *     is returned.

   652         * @since 3.0

   653         */

   654         virtual TTime PreviousSendingDate( TInt aSequenceNumber ) const;

   655 

   656         /**

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

   658         *

   659         * @return Time of the arrival of the message (in UTC time). 

   660         *    If the time has not been defined, TTime(0) is returned.

   661         * @since 3.0

   662         */

   663         virtual TTime MessageReceiveTime() const;

   664 

   665         /**

   666         * Get the incoming message size.

   667         *

   668         * This is valid only for a notification.

   669         *

   670         * @return Message size in octets as specified in MMS Notification.

   671         */

   672         virtual TInt MessageTransferSize() const;

   673 

   674         /**

   675         * Get the Uri from which the message can be fetched.

   676         *

   677         * This is valid only for a nofification.

   678         *

   679         * @return Content location of the actual message, the Uri from which 

   680         *    the message is fetched from MMS Service Centre.

   681         */

   682         virtual TPtrC8 MessageContentLocation() const;

   683 

   684         /**

   685         * Set id of the root part of the message.

   686         *

   687         * @param[in] aId Attachment Id of the message part which controls the 

   688         *     display of the message. Should point to the SMIL part if present.

   689         */

   690         virtual void SetMessageRootL( const TMsvAttachmentId aId );

   691 

   692         /**

   693         * Get the id of the root part of the message.

   694         *

   695         * @return Id of the attachment that starts the message display, 

   696         * KMsvNullIndexEntryId if the root part has not been defined.

   697         */

   698         virtual TMsvAttachmentId MessageRootAttachment() const;

   699 

   700         /**

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

   702         *

   703         * @param[in] aHeight Image height in pixels.

   704         * @param[in] aWidth Image width in pixels.

   705         */

   706         virtual void SetMaximumImage( TInt aWidth, TInt aHeight );

   707 

   708         /**

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

   710         *

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

   712         * @param[out] aHeight image height in pixels

   713         * @param[out] aWidth image width in pixels

   714         */

   715         virtual void GetMaximumImage( TInt& aWidth, TInt& aHeight ) const;

   716 

   717         // -------------------------------------------------------------------

   718         // GENERAL MESSAGE INFORMATION METHODS

   719 

   720         /**

   721         * Get the message size. 

   722         *

   723         * SaveMessageL and LoadMessageL updates the value. This function returns 

   724         * the total amount of disk space the message takes. The actual message 

   725         * size in transmission is smaller due to binary encoding of the headers.

   726         *

   727         * @return size of all message parts in bytes including both attachments 

   728         *     and internal header structures.

   729         */

   730         virtual TInt32 MessageSize();

   731 

   732         /**

   733         * Set the message description string.

   734         * 

   735         * This provides a method to override the default message description. 

   736         * The next SaveMessageL saves the description text in the 

   737         * TMsvEntry::iDescription field. This field is shown in Message Centre  

   738         * message lists to describe the contents of the message. Normally it is  

   739         * the message subject, but if there is no subject in the message, the 

   740         * caller may set some text from a text part of the message as the 

   741         * description. 

   742         *

   743         * Note that this method does not check the text length, so avoid long 

   744         * descriptions to minimize memory usage.

   745         *

   746         * @param[in] aText Message description

   747         */

   748         virtual void SetMessageDescriptionL( const TDesC& aText );

   749 

   750         // ---------------------------------------------------------------------

   751         // FUNCTIONS TO HANDLE EXTRA MESSAGE ATTRIBUTES (FOR UI USE ONLY)

   752 

   753         /**

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

   755         *

   756         * No duplicates are allowed. If an attribute exists, its value is changed. 

   757         * The attributes and their values can be arbitrary strings. There are no 

   758         * restrictions. The purpose is to allow the UI to store some extra 

   759         * information with the message. The values of the attibutes are not included 

   760         * when the message is sent.

   761         * @param[in] aName Name of the attribute (case sensitive).

   762         * @param[in] aValue Value of the attribute.

   763         *

   764         * @leave KErrArgument if length of aName or aValue is 0.

   765         * @leave KErrNoMemory if memory runs out while adding the attribute.

   766         */

   767         virtual void AddAttributeL( const TDesC& aName, const TDesC& aValue );

   768 

   769         /**

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

   771         *

   772         * @param[in] aName Name of the attribute (case sensitive).

   773         * @return Value of the attribute.

   774         * @leave KErrNotFound if attribute not found or the length of aName is 0.

   775         */

   776         virtual TPtrC GetAttributeL( const TDesC& aName );

   777 

   778         /**

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

   780         *

   781         * @param[in] aName Name of the attribute (case sensitive).

   782         * @return ETrue if the attribute is found, EFalse otherwise.

   783         */

   784         virtual TBool FindAttribute( const TDesC& aName );

   785 

   786         /**

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

   788         *

   789         * @param[in] aName Name of the attribute (case sensitive).

   790         */

   791         virtual void DeleteAttribute( const TDesC& aName );

   792 

   793         /**

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

   795         *

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

   797         */

   798         virtual void ResetAttributes();

   799 

   800         // -------------------------------------------------------------------

   801         // FUNCTIONS TO HANDLE MESSAGE ATTACHMENTS

   802 

   803         /**

   804         * Create attachment entry and copy specified file to message store.

   805         *

   806         * The user should call SaveMessageL after having added all attachments 

   807         *     to update TMsvEntry of the message entry.

   808         *

   809         * @param[in] aStore An open edit store for the message entry. 

   810         *     Caller must commit and close the store when ready. (Several 

   811         *     attachments can be added before committing the store.)

   812         * @param[in] aFile Open file handle, source of the attachment. 

   813         *     Caller must close the file afterwards.

   814         * @param[in] aMimeType Mime type (content type) of the attachmet 

   815         *     in format type/subtype, for example image/jpeg.

   816         * @param[in] aMimeHeaders Mime headers for the attachment. If the content 

   817         *     type is not defined in aMimeHeaders, the function adds the mime type 

   818         *     and subtype from aMimeType. Suggested filename in aMimeHeaders is 

   819         *     used as attachment name.

   820         * @param[in] aAttachmentInfo Attachment into structure, must be 

   821         *     initialized to CMsvAttachment::EMsvFile. If mime type is added 

   822         *     into the attachment info, it must be of format type/subtype, 

   823         *     for example image/jpeg. On return AttachmentInfo contains data 

   824         *     about the attachment. Ownership of attachmentinfo is transferred 

   825         *     to attachment manager, it must not be deleted by caller. It must 

   826         *     not be put on cleanup stack either. MMS engine keeps it safe until 

   827         *     the ownership has been transferred.

   828         * @param[out] aAttaId Attachment id of the newly created attachment.

   829         *

   830         * @pre A message entry must exist. It may be a new entry or an old entry 

   831         *     to be edited.

   832         * @pre CMsvMimeHeaders structure must have been filled in advantage. 

   833         *     The following values should be set:

   834         * - Content type, for example image 

   835         * - Content subtype, for example jpeg

   836         * - Character set IANA MIBEnum value, for example 106 (utf-8). Should be 

   837         *      defined only if the content type is text.

   838         * - Content-id if the presentation part refers to the attachments by 

   839         *      content-ids.

   840         * - Suggested filename (name only, no path), the name that should be 

   841         *      used to store the attachment and used as suggested filename 

   842         *      when sending the message. If the suggested filename is not set, the

   843         *      name of the attachment file will be used.

   844         * - Content-location if the presentation part refers to the attachments by 

   845         *      using content-location. The content-location string must contain only 

   846         *      us-ascii characters.

   847         * - X-type parameters (if needed). These are always handled as pairs of a 

   848         *      parameter name and parameter value. A descriptor at an even idex 

   849         *      in the array (0, 2, 4, ...) represents the parameter name and a 

   850         *      descriptor at an odd index (1, 3, 5, ...) represents the parameter 

   851         *      value. If a parameter has no value, it must be indicated by an empty 

   852         *      descriptor. The X-type parameter array must always contain an even 

   853         *      number of elements.

   854         *

   855         * @code

   856         * // The following code shows a short example of how the attachement

   857         * // creation proceeds.

   858         *

   859         * // Assume that the client entry is set to the message entry.

   860         * // Attachments are added to the message entry one by one

   861         * CMsvStore* store = iMmsClient->Entry().EditStoreL();

   862         * CleanupStack::PushL(store);

   863         *

   864         * CMsvAttachment* attaInfo = NULL;

   865         * TMsvAttachmentId attaId = 0;

   866         *

   867         * RFile attaFile;

   868         * // Set filename of attachment

   869         * TFileName name( _L("C:\\pictures\\picture123.jpg") );

   870         *

   871         * CMsvMimeHeaders* mimeHeaders = CMsvMimeHeaders::NewL();

   872         * CleanupStack::PushL( mimeHeaders );

   873         *

   874         * // Set values to mime headers

   875         * mimeHeaders->SetContentTypeL( _L8( "image") );

   876         * mimeHeaders->SetContentSubTypeL( _L8( "jpeg" ) );

   877         *

   878         * _LIT8(KMimeType, "image/jpeg");

   879         * // CreateAttachment2L will set the content type to attachment Info

   880         *

   881         * // Open the attachment file for reading

   882         * attaFile.Open( iFs, name, EFileShareReadersOnly | EFileRead );

   883         * CleanupClosePushL(attaFile);

   884         *

   885         * attaInfo = CMsvAttachment::NewL(CMsvAttachment::EMsvFile);

   886         * // attaInfo ownerhip will be transferred to Attachment Manager.

   887         * // It must not be pushed onto the cleanupStack before calling 

   888         * // CreateAttachment2L.

   889         *

   890         * TMsvAttachmentId attaId = 0;

   891         *

   892         * iMmsClient->CreateAttachment2L(

   893         *     *store,   // edit store

   894         *     attaFile, // open file handle

   895         *     KMimeType, // combination type like image/jpeg

   896         *     *mimeHeaders,

   897         *     attaInfo,

   898         *     attaId);

   899         * // Now Attachment Manager owns the attaInfo

   900         * attaInfo = NULL;

   901         *

   902         * CleanupStack::PopAndDestroy(); // attaFile.Close()

   903         * CleanupStack::PopAndDestroy(); // mimeHeaders

   904         *

   905         * // Several attachments can be added before committing the store

   906         *

   907         * // Store must be committed before it is destroyed

   908         * store->CommitL();

   909         * CleanupStack::PopAndDestroy(); // store

   910         * @endcode

   911         */

   912         virtual void CreateAttachment2L(

   913             CMsvStore& aStore,

   914             RFile& aFile,

   915             TDesC8& aMimeType,

   916             CMsvMimeHeaders& aMimeHeaders,

   917             CMsvAttachment* aAttachmentInfo,

   918             TMsvAttachmentId& aAttaId);

   919 

   920         /**

   921         * Create a text/plain attachment.

   922         *

   923         * Creates a text attachment from text in a descriptor. 

   924         * Has option to convert all unicode paragraph separator marks to 

   925         *     line feeds. 

   926         * Converts text from unicode (ucs-2) to utf-8 before storing it.

   927         *

   928         * @param[in] aStore An open edit store. Caller must commit and close the 

   929         *     store (several attachments can be added before committing store).

   930         * @param[out] aAttachmentId Attachment id of the new attachment entry.

   931         * @param[in] aText Unicode text to be added as a text/plain attachment.

   932         * @param[in] aFile Suggested filename for the attachment.

   933         * @param[in] aConvertParagraphSeparator Flag that tells the function  

   934         *     to search for all 0x2029 characters (Unicode paragraph 

   935         *     separator) and to replace them with 0x000d 0x000a (carriage return, 

   936         *     line feed). 

   937         * Possible values:

   938         * - ETrue: Convert paragraph separators (default).

   939         * - EFalse: Do not convert paragraph separators.

   940         *

   941         * @pre A message entry must exist. It may be a new entry or an old entry 

   942         *     to be edited.

   943         *

   944         * @code

   945         *

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

   947         *

   948         * CMsvStore* store = iMmsClient->Entry().EditStoreL();

   949         * CleanupStack::PushL(store);

   950         * TMsvAttachmentId attaId = 0;

   951         *

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

   953         *

   954         * iMmsClient->CreateTextAttachmentL(

   955         *     *store,

   956         *     attaId,

   957         *     story,

   958         *     attachmentFile,

   959         *     ETrue )

   960         *

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

   962         *

   963         * // caller must commit the store as several attachments could be added berore

   964         * // committing the store.

   965         * store->CommitL();

   966         * CleanupStack::PopAndDestroy(); // store

   967         *

   968         * @endcode

   969         */

   970         virtual void CreateTextAttachmentL(

   971             CMsvStore& aStore,

   972             TMsvAttachmentId& aAttachmentId,

   973             const TDesC& aText,

   974             const TDesC& aFile,

   975             TBool aConvertParagraphSeparator = ETrue );

   976 

   977         // -------------------------------------------------------------------

   978         // MESSAGE HANDLING FUNCTIONS

   979 

   980         // NOTE: these are asynchronous functions

   981 

   982         /**

   983         * Send current message in the background.

   984         *

   985         * The message is automatically moved to Outbox folder before the 

   986         *     sending starts.

   987         *

   988         * @param[in] aCompletionStatus iStatus member of an active object. 

   989         *     It will be set as completed when the operating system has relayed 

   990         *     the request to the server side of Symbian Messaging System.

   991         * @param[in] aSendingTime Time at which the message is to be sent 

   992         *     given as UTC time. If aSending time is zero or in the past, the 

   993         *     message is scheduled to be sent as soon as possible.

   994         * @return Pointer to an operation active object. 

   995         *     The operation will complete when the sending has been successfully 

   996         *     scheduled. The actual sending will happen in the background. 

   997         *     If scheduling the send fails, the status of CMsvOperation will 

   998         *     contain the relevant error code. The operation object must not 

   999         *     be deleted before it completes.

  1000         *

  1001         * @leave KErrNoMemory or other Symbian error code. If the function leaves  

  1002         *     the owner of aCompletionStatus must not be set active because there 

  1003         *     will be no pending request.

  1004         */

  1005         virtual CMsvOperation* SendL( TRequestStatus& aCompletionStatus,

  1006             const TTime aSendingTime = TTime( 0 ) );

  1007 

  1008         /**

  1009         * Send a selection of messages in the background.

  1010         *

  1011         * The messages are moved to Outbox folder before the sending starts. 

  1012         *     All messages must be in the same place originally 

  1013         *     (all in drafts, or all in outbox, for example).

  1014         *

  1015         * @param[in] aSelection List of messages to be sent.

  1016         * @param[in] aCompletionStatus iStatus member of an active object. 

  1017         *     It will be set as completed when the operating system has relayed 

  1018         *     the request to the server side of Symbian Messaging System. 

  1019         * @param aSendingTime Time at which the message selection is to be sent 

  1020         *     given as UTC time. If aSending time is zero or in the past, the 

  1021         *     message is scheduled to be sent as soon as possible.

  1022         * @return Pointer to an operation active object. 

  1023         *     The operation will complete when the sending has been successfully 

  1024         *     scheduled. The actual sending will happen in the background. 

  1025         *     If scheduling the send fails, the status of CMsvOperation will 

  1026         *     contain the relevant error code. The operation object must not 

  1027         *     be deleted before it completes.

  1028         *

  1029         * @leave KErrNotFound if aSelection is empty, or other Symbian error code. 

  1030         *     If the function leaves the owner of aCompletionStatus must not be set  

  1031         *     active because there will be no pending request.

  1032         */

  1033         virtual CMsvOperation* SendL(

  1034             CMsvEntrySelection& aSelection,

  1035             TRequestStatus& aCompletionStatus,

  1036             TTime aSendingTime = TTime( 0 ) );

  1037 

  1038         /**

  1039         * Fetch pending MMS messages from MMS Service Centre to inbox.

  1040         *

  1041         * If there are notifications in postponed state they are all fetched. 

  1042         * If there are notification in inbox, they are not touched.

  1043         *

  1044         * @param[in] aCompletionStatus iStatus member of an active object. 

  1045         *     It will be set as completed when the operating system has relayed 

  1046         *     the request to the server side of Symbian Messaging System.

  1047         * @param[in] aForced indicates if the messages should be fetched 

  1048         *     regardless of current mode settings.

  1049         * - ETrue: User initiated fetch, use override.

  1050         * - EFalse: Event triggered fetch, fetch only if settings allow.

  1051         * @return Pointer to an operation active object. 

  1052         *     The operation will complete when the retrieving has been successfully 

  1053         *     scheduled. The actual retrieving will happen in the background. 

  1054         *     If scheduling the fetch fails, the status of CMsvOperation will 

  1055         *     contain the relevant error code. The operation object must not 

  1056         *     be deleted before it completes.

  1057         *

  1058         * @leave KErrNoMemory or other Symbian error code. If the function leaves 

  1059         *     the owner of aCompletionStatus must not be set active because there 

  1060         *     will be no pending request.

  1061         *

  1062         * @deprecated Postponed fetching mode is no longer supported by UI. In most 

  1063         *     cases this function would not have any effect.

  1064         */

  1065         virtual CMsvOperation* FetchAllL( TRequestStatus& aCompletionStatus,

  1066             TBool aForced = ETrue );

  1067             

  1068         /**

  1069         * Send a read report to the sender of a message.

  1070         *

  1071         * This function should be called when a new message is opened and the 

  1072         * sender of the message has specified that he wants a read report

  1073         * for the message in question. This function should not be called 

  1074         * if the settings indicate that sending read reports is not allowed.

  1075         *

  1076         * @param[in] aReadMessageId Id of the message for which a read report 

  1077         *     should be sent. The message must not be locked and the caller 

  1078         *     should not have CMsvStore open for the message as MMS Client Mtm 

  1079         *     must be able to read header fields from the original message.

  1080         * @param[in] aCompletionStatus iStatus member of an active object. 

  1081         *     It will be set as completed when the operating system has relayed  

  1082         *     the request to the server side of Symbian Messaging System.

  1083         * @param[in] aReadStatus indicates if the message was read 

  1084         *     Possible values:

  1085         * - EMmsReadStatusRead: The message was read.

  1086         * - EMmsReadStatusDeletedWithoutBeingRead: The message was deleted 

  1087         *         without being read.

  1088         * @return Pointer to an operation active object. 

  1089         *     The operation will complete when the sending of the read report 

  1090         *     has been successfully scheduled. The actual sending will happen 

  1091         *     in the background. If scheduling the send fails, the status of 

  1092         *     CMsvOperation will contain the relevant error code. 

  1093         *     If the sender of the message has not requested a read report or 

  1094         *     read report sending is not allowed, the operation completes 

  1095         *     with error code KErrGeneral. 

  1096         *     The operation object must not be deleted before it completes.

  1097         *

  1098         * @leave KErrLocked if the message entry cannot be accessed.

  1099         */

  1100         virtual CMsvOperation* SendReadReportL( TMsvId aReadMessageId,

  1101             TRequestStatus& aCompletionStatus,

  1102             TMmsReadStatus aReadStatus = EMmsReadStatusRead );

  1103             

  1104     public:  // FUNCTIONS FROM BASE CLASSES

  1105 

  1106         /**

  1107         * From CBaseMtm: Return type of this Mtm.

  1108         * @return Registered Mtm type.

  1109         */

  1110         inline TUid Type() const;

  1111 

  1112 

  1113         // Context specific functions

  1114 

  1115         /**

  1116         * From CBaseMtm: Set current context.

  1117         * @param[in] aEntry Pointer to entry instance.

  1118         */

  1119         inline void SetCurrentEntryL( CMsvEntry* aEntry );

  1120 

  1121         /**

  1122         * From CBaseMtm: Switch context to entry defined by aId.

  1123         * @param[in] aId Entry id in message store.

  1124         */

  1125         inline void SwitchCurrentEntryL( TMsvId aId );

  1126 

  1127         /**

  1128         * From CBaseMtm: Get reference to current entry.

  1129         * @return Reference to entry instance.

  1130         */

  1131         inline CMsvEntry& Entry() const;

  1132 

  1133         /**

  1134         * From CBaseMtm: Query if entry context has been set.