1 /*

     2 * Copyright (c) 2007-2008 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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  common email part object

    15 *

    16 */

    17 

    18 #ifndef __CFSMAILMESSAGEPART_H

    19 #define __CFSMAILMESSAGEPART_H

    20 

    21 #include <e32std.h>

    22 #include <e32base.h>

    23 #include <f32file.h>

    24 #include <badesca.h>

    25 

    26 //<cmail>

    27 #include "CFSMailMessageBase.h"

    28 #include "mmrinfoobject.h"

    29 //</cmail>

    30 

    31 //<qmail>

    32 #include <QExplicitlySharedDataPointer>

    33 

    34 class NmMessagePartPrivate;

    35 class NmMessagePart;

    36 //</qmail>

    37 

    38 class CFSMailPlugin;

    39 class CFSMailMessage;

    40 class MFSMailRequestObserver;

    41 

    42 const TInt KArrayGranularity = 16;

    43 

    44 /**

    45  *  email parts handling class

    46  *

    47  *  @lib FSFWCommonLib

    48  *  @since S60 v3.1

    49  */

    50 NONSHARABLE_CLASS ( CFSMailMessagePart ) : public CFSMailMessageBase

    51 {

    52  public:

    53 // <qmail>

    54     /**

    55      * Enumeration to indicate data source

    56      */

    57     enum TFSMailMessagePartDataSource

    58         {

    59         EDataSourceMessageStore = 0,    // plugin (data from message store)

    60         EDataSourceLocal                // internal private shared object

    61         };

    62 // </qmail>

    63    

    64  public:

    65 

    66     /**

    67      * Two-phased constructor.

    68      *

    69      * @param aMessageId message id in plugin containing email

    70      * @param aMessagePartId message part id in plugin containing email

    71      */

    72      IMPORT_C static CFSMailMessagePart* NewL( TFSMailMsgId aMessageId, TFSMailMsgId aMessagePartId );

    73 

    74     /**

    75      * Two-phased constructor.

    76      *

    77      * @param aMessageId message id in plugin containing email

    78      * @param aMessagePartId message part id in plugin containing email

    79      */

    80      IMPORT_C static CFSMailMessagePart* NewLC( TFSMailMsgId aMessageId, TFSMailMsgId aMessagePartId );

    81 

    82 // <qmail>

    83      /**

    84       * Two-phased constructor.

    85       *

    86       * @param aMessageId message id in plugin containing email

    87       */

    88       IMPORT_C static CFSMailMessagePart* NewLC( const NmId &aNmMessageId, const NmMessagePart& aNmMessagePart );     

    89 // </qmail>

    90 

    91     /**

    92      * destructor

    93      */  

    94      IMPORT_C virtual ~CFSMailMessagePart();

    95      

    96     /**

    97      * email part id accessor

    98      *

    99      * @return email part id

   100      */

   101      IMPORT_C TFSMailMsgId GetPartId() const;

   102 

   103 // <qmail>

   104     /**

   105      * email part content-type accessor (e.g. "text/plain")

   106      *

   107      * @return email part content type

   108      */

   109      IMPORT_C const TDesC& GetContentType() const;

   110 // </qmail>

   111     

   112     /**

   113      * email part content-type mutator 

   114      *

   115      * @param aContentType new content type value

   116      */

   117      IMPORT_C void SetContentType(const TDesC& aContentType);

   118 

   119     /**

   120      * Returns content-type parameters and their associated values.

   121      * Updating/setting values should be done by first getting the array and

   122      * then modifying it's contents.

   123      * 

   124      * @return content type parameters

   125      */

   126      IMPORT_C CDesCArray& ContentTypeParameters();

   127      

   128     /**

   129      * Returns email Content-Description value, includes also parameters,

   130      * if any.

   131      *

   132      * @return email Content-Description

   133      */

   134      IMPORT_C const TDesC& ContentDescription();

   135      

   136     /**

   137      * Stores email Content-Description value, parameters can be included,

   138      * if any.

   139      *

   140      * @param aContentDescription new email content description value

   141      */

   142      IMPORT_C void SetContentDescription(const TDesC& aContentDesctiption);

   143 

   144     /**

   145      * Returns email Content-Disposition value, includes also parameters,

   146      * if any.

   147      *

   148      * @return email Content-Disposition

   149      */

   150      IMPORT_C const TDesC& ContentDisposition();

   151      

   152     /**

   153      * Stores email Content-Disposition value, parameters can be included,

   154      * if any.

   155      *

   156      * @param aContentDisposition new email content disposition value

   157      */    

   158      IMPORT_C void SetContentDisposition(const TDesC& aContentDesctiption);

   159 

   160     /**

   161      * Returns email Content-Disposition Parameters and their associated values.

   162      * Updating/setting values should be done by first getting the array and

   163      * then modifying it's contents.

   164      *

   165      * @return content disposition parameters

   166      */

   167      IMPORT_C CDesCArray& ContentDispositionParameters();

   168 

   169     /**

   170      * email Content-Id accessor.

   171      *

   172      * @return email Content-Id

   173      */

   174      IMPORT_C const TDesC& ContentID();

   175      

   176     /**

   177      * email Content-Id mutator

   178      *

   179      * @param aContentID new email Content-Id value

   180      */

   181      IMPORT_C void SetContentIDL(const TDesC& aContentID);

   182 

   183     /**

   184      * email Content-Class accessor

   185      *

   186      * @return email Content-Class

   187      */

   188      IMPORT_C const TDesC& GetContentClass();

   189 

   190     /**

   191      * email Content-Class mutator

   192      *

   193      * @param aContentClass new email Content-Class value

   194      */

   195      IMPORT_C void SetContentClass( const TDesC& aContentClass );

   196 

   197     /**

   198      * saves this message part 

   199      */

   200      IMPORT_C void SaveL();

   201 

   202 // <qmail>

   203     /**

   204      * lists all direct child parts of this email part

   205      *

   206      * @param aParts table containing list of child parts owned by user

   207      * @param aDataSource data source: email store/local object

   208      */

   209      IMPORT_C void ChildPartsL(RPointerArray<CFSMailMessagePart>& aParts, 

   210          TFSMailMessagePartDataSource aDataSource = EDataSourceMessageStore);

   211 // </qmail>

   212 

   213     /**

   214      * Returns child part of this part identified by part id.

   215      * 

   216      * @param aPartId defines parent part id

   217      * @return child part object, ownership is transferred to user

   218      */

   219      IMPORT_C CFSMailMessagePart* ChildPartL( const TFSMailMsgId aPartId );

   220 

   221     /**

   222      * Returns ETrue if this email part is actually an email,

   223      * so it's safe to cast this part to CFSMailMessage

   224      * 

   225      * @return ETrue if this email part is email

   226      */        

   227      IMPORT_C virtual TBool IsMessageL() const;

   228 

   229     /**

   230      * Creates and adds a new child part to this email part

   231      * 

   232      * @param aInsertBefore defines place where new child part is created,

   233      *        if aInsertBefore is NULL id then new part is added as last.

   234      * @param aContentType content type of the new child part

   235      *

   236      * @return created child part object, ownership is transferred to user

   237      */

   238      IMPORT_C CFSMailMessagePart* NewChildPartL( const TFSMailMsgId aInsertBefore,

   239                                                  const TDesC& aContentType );

   240 

   241     /**

   242      * Removes child part (and it's children, if any) from this email part

   243      * 

   244      * @param aPartId part id of the email part to be removed

   245      */

   246      IMPORT_C void RemoveChildPartL(TFSMailMsgId aPartId);

   247 

   248 // <qmail>

   249      /**

   250       * Removes child part (and it's children, if any) from this email part

   251       * 

   252       * @param aPartId part id of the email part to be removed

   253       * @param aOperationObserver Observer for the operation 

   254       * 

   255       * @return id of the request, KErrNotSupported if the protocol plugin this

   256       * instance is attached to does not support the async method.

   257       */

   258      IMPORT_C TInt RemoveChildPartL( TFSMailMsgId aPartId,

   259                                      MFSMailRequestObserver& aOperationObserver);

   260 // </qmail>

   261      

   262     /**

   263      * Retrieves a read-only file handle for the content file of this message part.

   264      * The caller must close the file handle.

   265      *

   266      * @return content file handle 

   267      */

   268      IMPORT_C RFile GetContentFileL();

   269        

   270     

   271     /**

   272      * returns email part full content size (in bytes)

   273      *

   274      */

   275      IMPORT_C TUint ContentSize() const;

   276 

   277     /**

   278      * Sets email part full content size (in bytes)

   279      *

   280      * @param aContentSize content size to be set

   281      */

   282      IMPORT_C void SetContentSize(const TUint aContentSize);

   283     

   284     /**

   285      * returns email part currently fetched (local) content size (in bytes).

   286      * 

   287      */

   288      IMPORT_C TUint FetchedContentSize() const;

   289 

   290     /**

   291      * Sets email part currently fetched (local) content size (in bytes).

   292      * 

   293      * @param aContentSize content size to be set

   294      */

   295      IMPORT_C void SetFetchedContentSize(TUint aContentSize);

   296 

   297     /**

   298      * copies email part contents to buffer given by user

   299      *

   300      * @param aBuffer buffer owned by user

   301      * @param aStartOffset offset from content begin

   302      */

   303      IMPORT_C void GetContentToBufferL(TDes16& aBuffer, TUint aStartOffset);

   304     

   305     /**

   306      * copies email part contents from buffer given by user

   307      *

   308      * @param aBuffer buffer given by user

   309      */

   310      IMPORT_C void SetContent(TDes16& aBuffer); 

   311 

   312     /**

   313      * meeting request accessor if email part is a meeting request

   314      * 

   315      * @return meeting request object

   316      */

   317      IMPORT_C MMRInfoObject& GetMRInfo();

   318     

   319     /**

   320      * stores given meeting request object as email part

   321      * 

   322      * @param aMeetingRequest meeting request object

   323      */

   324      IMPORT_C void SetMRInfo(MMRInfoObject* aMeetingRequest);

   325 

   326     /**

   327      * method checks if MRInfo exists

   328      * 

   329      * @return true / false

   330      */

   331      IMPORT_C TBool IsMRInfoSet();

   332 

   333     /**

   334      * Sets attachment name for email part. Full path can be

   335      * given as input even though only filename is saved. 

   336      * 

   337      * @param aFilePath attachment name

   338      */        

   339      IMPORT_C void SetAttachmentNameL(const TDesC& aFilePath);

   340 

   341     /**

   342      * returns email part attachment name

   343      * 

   344      * @return attachment name

   345      */        

   346      IMPORT_C TDesC& AttachmentNameL();

   347     

   348 // <qmail>

   349     /**

   350      * finds email body part based on given content type 

   351      * (plain text or html body part of email message)

   352      * 

   353      * @param aContentType body part content type to be searched

   354      * @param aDataSource data source: email store/local object

   355      *

   356      * @return email body part or NULL if not found, ownership is transferred to user

   357      */

   358      IMPORT_C CFSMailMessagePart* FindBodyPartL(const TDesC& aContentType,

   359          TFSMailMessagePartDataSource aDataSource = EDataSourceMessageStore);

   360 // </qmail>

   361 

   362     /**

   363      * starts email part fetching from email server

   364      * 

   365      * @param aMessagePartId message part id of email part to be fetched

   366      * @param aOperationObserver observer to forward fetching progress events

   367      * to user

   368      * @param aPreferredByteCount indicates how much more content for part(s)

   369      *        user wants to fetch. Default value zero indicates that all content

   370      *        should be fetched. Actual amount of data fetched may differ from

   371      *        requested (possibly all fetched in any case).

   372      *

   373      * @return err code

   374      */        

   375      IMPORT_C TInt FetchMessagePartL(   const TFSMailMsgId aMessagePartId,

   376                                         MFSMailRequestObserver& aOperationObserver,

   377                                         const TUint aPreferredByteCount);

   378 

   379     /**

   380      * starts email parts fetching from email server

   381      * 

   382      * @param aMessagePartIds message part ids of email parts to be fetched

   383      * @param aOperationObserver observer to forward fetching progress events

   384      * to user

   385      * @param aPreferredByteCount indicates how much more content for part(s)

   386      *        user wants to fetch. Default value zero indicates that all content

   387      *        should be fetched. Actual amount of data fetched may differ from

   388      *        requested (possibly all fetched in any case).

   389      *

   390      * @return err code

   391      */        

   392      IMPORT_C TInt FetchMessagesPartsL( const RArray<TFSMailMsgId>& aMessagePartIds,

   393                                         MFSMailRequestObserver& aOperationObserver,

   394                                         const TUint aPreferredByteCount);

   395     /**

   396      * creates a list containing all email / email part subparts

   397      * 

   398      * @param aParts email part list given/owned by user

   399      */        

   400      IMPORT_C void AppendAttachmentsL(RPointerArray<CFSMailMessagePart>& aParts);

   401 

   402     /**

   403      * sets email part fetch status

   404      * 

   405      * @param aMessagePartStatus (EFSMessagePartsKnown)

   406      */

   407      IMPORT_C void SetMessagePartsStatus(TFSPartFetchState aMessagePartStatus);

   408 

   409     /**

   410      * Adds new attachment to this email (part).

   411      * 

   412      * @param aFilePath full path of new attachment.

   413      * @param aInsertBefore defines position of new attachment,

   414      *        if NullId then new attachment is created as last part.

   415      * @param aContentType attachment content type

   416 

   417      * @return new email part, ownership is transferred to user

   418      */ 

   419      IMPORT_C CFSMailMessagePart* AddNewAttachmentL( const TDesC& aFilePath, 

   420                                                      const TFSMailMsgId aInsertBefore,

   421                                                      const TDesC& aContentType );

   422     /**

   423      * read only part size accessor (character or byte count)

   424      *

   425      */

   426      IMPORT_C TUint ReadOnlyPartSize() const;

   427 

   428     /**

   429      * read only part size mutator

   430      *

   431      * @param aReadOnlyPartSize read only size to be set

   432      * (character or byte count)

   433      */

   434      IMPORT_C void SetReadOnlyPartSize(const TUint aReadOnlyPartSize);

   435      

   436 // <qmail>

   437      /**

   438  	 * gets the new NmMessagePart object

   439  	 *

   440  	 * @return NmMessagePart object

   441  	 */

   442  	 IMPORT_C NmMessagePart* GetNmMessagePart();

   443 // </qmail>

   444  	 

   445 // <qmail>

   446      /**

   447       * Gets the text content from private shared object.

   448       * Returns the ownership of text buffer to caller.

   449       * Returned object should be removed from CleanupStack after usage.

   450       * 

   451       * @return HBufC*

   452       */

   453      IMPORT_C HBufC* GetLocalTextContentLC();

   454 // </qmail>

   455      

   456      

   457 public: // data

   458 

   459 protected:

   460 

   461     /**

   462      * constructor

   463      */

   464      CFSMailMessagePart();

   465 

   466     /**

   467      * lists subparts

   468      */

   469      void ListMessagePartsL( RPointerArray<CFSMailMessagePart>& aParts );

   470          

   471     /**

   472      * clears internal part array

   473      */

   474      void ClearPartsArray(TBool aClearAll);

   475      

   476     /**

   477      * finds id of body part

   478      */

   479      TFSMailMsgId FindBodyPartIdL(const TDesC& aContentType);

   480 

   481      /**

   482      * Returns a flat list of message parts that can be handled as attachments.

   483      * Excludes message parts that are multipart and parts that are considered

   484      * plain text or html body.

   485      * 

   486      * @param aParts contains flat list of attachments

   487      */        

   488      virtual void DoAttachmentListL(RPointerArray<CFSMailMessagePart>& aParts);

   489 

   490 protected: // data

   491 

   492     /**

   493      * email fetch from email server status

   494      */

   495      TFSPartFetchState                  iMessagePartsStatus;

   496 

   497 // <qmail>

   498  	/**

   499  	 * message part MIME type - pointer descriptor to access QString object

   500  	 */

   501  	 mutable TPtrC						iContentTypePtr;

   502 // </qmail>

   503 	 

   504   	/** message parts array */

   505 	 RPointerArray<CFSMailMessagePart>	iMessageParts;

   506 	 TBool                              iReadMessageParts;

   507 	 

   508 // <qmail>

   509 	/**

   510 	 * Reference to QT side of the message meta data object.

   511 	 */

   512 	 QExplicitlySharedDataPointer<NmMessagePartPrivate> iNmPrivateMessagePart;

   513 // </qmail>

   514 

   515 protected:

   516 

   517     /**

   518      * Two-phased constructor

   519      */

   520      void ConstructL( TFSMailMsgId aMessageId, TFSMailMsgId aMessagePartId );

   521 

   522 // <qmail>

   523     /**

   524      * Two-phased constructor

   525      */

   526      void ConstructL(const NmId &aNmMessageId, const NmMessagePart& aNmMessagePart);

   527 

   528      void ConstructL(const NmMessagePart& aNmMessagePart,

   529                      const NmMessageEnvelope& aNmMessageEnvelope);

   530 // </qmail>

   531 

   532 private:    // data

   533 

   534 // <qmail>

   535 // Unnecessary members removed: iMessagePartId, iContentSize, iFetchedContentSize

   536 // </qmail>

   537      /** read only part size */

   538      TUint           iReadOnlyPartSize;

   539 

   540      /** fetched from email server indication */

   541      TBool           iIsFetched;

   542 

   543 // <qmail>

   544    	/**

   545    	 * email content decription  - pointer descriptor to access QString object

   546    	 */

   547    	 mutable TPtrC	iContentDescriptionPtr;      

   548 

   549    	/**

   550    	 * email content disposition  - pointer descriptor to access QString object

   551    	 */

   552    	 mutable TPtrC	iContentDispositionPtr;

   553 // </qmail>

   554  	 

   555      /** attachment name */

   556      HBufC           *iAttachmentName;

   557 

   558      /** email content class */

   559      HBufC           *iContentClass;

   560 

   561 // <qmail>

   562     /**

   563      * email content id  - pointer descriptor to access QString object

   564      */

   565      mutable TPtrC	iContentIDPtr;

   566 // </qmail>

   567 

   568      /** content disposition parameters */

   569      CDesCArray      *iContentDispositionParams;

   570 

   571      /** content type parameters */

   572      CDesCArray      *iContentTypeParams;

   573 

   574      /** meeting request object */

   575      MMRInfoObject*  iMeetingRequest;                       

   576 

   577      /* temp file handle */

   578      RFile           iFile;

   579  };

   580 

   581 #endif // __CFSMAILMESSAGEPART_H