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 class CFSMailRequestHandler;

    42 

    43 const TInt KArrayGranularity = 16;

    44 

    45 /**

    46  *  email parts handling class

    47  *

    48  *  @lib FSFWCommonLib

    49  *  @since S60 v3.1

    50  */

    51 NONSHARABLE_CLASS ( CFSMailMessagePart ) : public CFSMailMessageBase

    52 {

    53  public:

    54     //<qmail>

    55     /**

    56      * Enumeration to indicate data source

    57      */

    58     enum TFSMailMessagePartDataSource

    59         {

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

    61         EDataSourceLocal                // internal private shared object

    62         };

    63     //<qmail>

    64    

    65  public:

    66 

    67     /**

    68      * Two-phased constructor.

    69      *

    70      * @param aMessageId message id in plugin containing email

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

    72      */

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

    74 

    75     /**

    76      * Two-phased constructor.

    77      *

    78      * @param aMessageId message id in plugin containing email

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

    80      */

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

    82 

    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      

    90     /**

    91      * destructor

    92      */  

    93      IMPORT_C virtual ~CFSMailMessagePart();

    94      

    95   /**

    96      * email part id accessor

    97      *

    98      * @return email part id

    99      */

   100      IMPORT_C TFSMailMsgId GetPartId() const;

   101 

   102     /**

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

   104      *

   105      * @return email part content type

   106      */

   107      IMPORT_C const TDesC& GetContentType() const;

   108     

   109     /**

   110      * email part content-type mutator 

   111      *

   112      * @param aContentType new content type value

   113      */

   114      IMPORT_C void SetContentType(const TDesC& aContentType);

   115 

   116     /**

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

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

   119      * then modifying it's contents.

   120      * 

   121      * @return content type parameters

   122      */

   123      IMPORT_C CDesCArray& ContentTypeParameters();

   124      

   125     /**

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

   127    * if any.

   128      *

   129      * @return email Content-Description

   130      */

   131      IMPORT_C const TDesC& ContentDescription();

   132      

   133     /**

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

   135      * if any.

   136      *

   137      * @param aContentDescription new email content description value

   138      */

   139      IMPORT_C void SetContentDescription(const TDesC& aContentDesctiption);

   140 

   141     /**

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

   143      * if any.

   144      *

   145      * @return email Content-Disposition

   146      */

   147      IMPORT_C const TDesC& ContentDisposition();

   148      

   149     /**

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

   151      * if any.

   152      *

   153      * @param aContentDisposition new email content disposition value

   154      */    

   155      IMPORT_C void SetContentDisposition(const TDesC& aContentDesctiption);

   156 

   157     /**

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

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

   160      * then modifying it's contents.

   161      *

   162      * @return content disposition parameters

   163      */

   164      IMPORT_C CDesCArray& ContentDispositionParameters();

   165 

   166     /**

   167      * email Content-Id accessor.

   168      *

   169      * @return email Content-Id

   170      */

   171      IMPORT_C const TDesC& ContentID();

   172      

   173     /**

   174      * email Content-Id mutator

   175      *

   176      * @param aContentID new email Content-Id value

   177      */

   178      IMPORT_C void SetContentIDL(const TDesC& aContentID);

   179 

   180     /**

   181      * email Content-Class accessor

   182      *

   183      * @return email Content-Class

   184      */

   185      IMPORT_C const TDesC& GetContentClass();

   186 

   187     /**

   188      * email Content-Class mutator

   189      *

   190      * @param aContentClass new email Content-Class value

   191      */

   192      IMPORT_C void SetContentClass( const TDesC& aContentClass );

   193 

   194     /**

   195      * saves this message part 

   196      */

   197      IMPORT_C void SaveL();

   198     

   199     /**

   200      * lists all direct child parts of this email part

   201      *

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

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

   204      */

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

   206          TFSMailMessagePartDataSource aDataSource = EDataSourceMessageStore);

   207 

   208     /**

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

   210      * 

   211      * @param aPartId defines parent part id

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

   213      */

   214      IMPORT_C CFSMailMessagePart* ChildPartL( const TFSMailMsgId aPartId );

   215 

   216     /**

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

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

   219      * 

   220      * @return ETrue if this email part is email

   221      */        

   222    IMPORT_C virtual TBool IsMessageL() const;

   223 

   224     /**

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

   226      * 

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

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

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

   230      *

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

   232      */

   233      IMPORT_C CFSMailMessagePart* NewChildPartL( const TFSMailMsgId aInsertBefore,

   234                                                  const TDesC& aContentType );

   235 

   236     /**

   237      * Copies given email object as new child part of this email part or email.

   238    *

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

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

   241      * @param aMessage message to be copied as child part

   242      *

   243      * @return new child part, ownership is transferred to user

   244      */        

   245      IMPORT_C CFSMailMessagePart* CopyMessageAsChildPartL( TFSMailMsgId aInsertBefore,

   246                                                            CFSMailMessage* aMessage);

   247 

   248     /**

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

   250      * 

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

   252      */

   253      IMPORT_C void RemoveChildPartL(TFSMailMsgId aPartId);

   254 

   255     /**

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

   257      * The caller must close the file handle.

   258      *

   259      * @return content file handle 

   260      */

   261      IMPORT_C RFile GetContentFileL();

   262         

   263     /**

   264      * copies contents of this message part to given file

   265      *

   266      * @param aContentLocation defines file location as 

   267      * a) directory, when plugin finds out corresponding file name

   268      *    related to this part id, in this case last character should

   269      *    be '/'

   270      * b) directory & filename, when both directory and file name

   271      *    are given by user

   272      * 

   273      */        

   274      IMPORT_C void CopyContentFileL(const TDesC& aContentLocation);

   275 

   276     /**

   277      * Sets email part contents from given file, possible old contents are replaced.

   278      *

   279      * @param aFilePath defines the target file

   280      */

   281      IMPORT_C void SetContentFromFileL(const TDesC& aFilePath);

   282 

   283     /**

   284      * Removes from message store fetched contents of this part

   285      * and possible child parts

   286      *

   287      */  

   288      IMPORT_C void RemoveContentL();

   289     

   290     /**

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

   292      *

   293      */

   294      IMPORT_C TUint ContentSize() const;

   295 

   296     /**

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

   298      *

   299      * @param aContentSize content size to be set

   300      */

   301      IMPORT_C void SetContentSize(const TUint aContentSize);

   302     

   303     /**

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

   305      * 

   306      */

   307      IMPORT_C TUint FetchedContentSize() const;

   308 

   309     /**

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

   311      * 

   312      * @param aContentSize content size to be set

   313      */

   314      IMPORT_C void SetFetchedContentSize(TUint aContentSize);

   315 

   316     /**

   317      * returns email part content current fetch state

   318      * Intended as utility function for UI.

   319      * If (0 == FetchedContentSize())

   320      *    return EFSNone;

   321      * else if (FetchedContentSize() < ContentSize()) then

   322      *    return EFSPartial

   323      * else

   324      *    return EFSFull

   325      *

   326      * @return email fetch state (EFSNone / EFSPartial / EFSFull)

   327      */

   328      IMPORT_C TFSPartFetchState FetchLoadState() const;

   329 

   330     /**

   331      * copies email part contents to buffer given by user

   332      *

   333      * @param aBuffer buffer owned by user

   334      * @param aStartOffset offset from content begin

   335      */

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

   337   

   338     /**

   339      * copies email part contents from buffer given by user

   340      *

   341      * @param aBuffer buffer given by user

   342      */

   343      IMPORT_C void SetContent(TDes16& aBuffer); 

   344 

   345   /**

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

   347      * 

   348      * @return meeting request object

   349      */

   350      IMPORT_C MMRInfoObject& GetMRInfo();

   351   

   352   /**

   353    * stores given meeting request object as email part

   354    * 

   355    * @param aMeetingRequest meeting request object

   356    */

   357      IMPORT_C void SetMRInfo(MMRInfoObject* aMeetingRequest);

   358 

   359     /**

   360    * method checks if MRInfo exists

   361    * 

   362    * @return true / false

   363    */

   364    IMPORT_C TBool IsMRInfoSet();

   365 

   366     /**

   367    * plugin request handler accessor

   368    * 

   369    * @return request handler

   370    */

   371      IMPORT_C CFSMailRequestHandler& RequestHandler( );

   372 

   373   /**

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

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

   376      * 

   377      * @param aFilePath attachment name

   378      */        

   379    IMPORT_C void SetAttachmentNameL(const TDesC& aFilePath);

   380 

   381     /**

   382      * returns email part attachment name

   383      * 

   384      * @return attachment name

   385      */        

   386      IMPORT_C TDesC& AttachmentNameL();

   387   

   388     /**

   389      * finds email body part based on given content type 

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

   391      * 

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

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

   394      *

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

   396      */

   397      IMPORT_C CFSMailMessagePart* FindBodyPartL(const TDesC& aContentType,

   398          TFSMailMessagePartDataSource aDataSource = EDataSourceMessageStore);

   399 

   400 

   401     /**

   402      * starts email part fetching from email server

   403      * 

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

   405      * @param aOperationObserver observer to forward fetching progress events

   406      * to user

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

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

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

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

   411      *

   412      * @return err code

   413      */        

   414    IMPORT_C TInt FetchMessagePartL(   const TFSMailMsgId aMessagePartId,

   415                           MFSMailRequestObserver& aOperationObserver,

   416                         const TUint aPreferredByteCount);

   417 

   418     /**

   419      * starts email parts fetching from email server

   420      * 

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

   422      * @param aOperationObserver observer to forward fetching progress events

   423      * to user

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

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

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

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

   428      *

   429      * @return err code

   430      */        

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

   432                         MFSMailRequestObserver& aOperationObserver,

   433                         const TUint aPreferredByteCount);

   434   /**

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

   436    * 

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

   438    */        

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

   440 

   441   /**

   442    * sets email part fetch status

   443    * 

   444    * @param aMessagePartStatus (EFSMessagePartsKnown)

   445    */

   446      IMPORT_C void SetMessagePartsStatus(TFSPartFetchState aMessagePartStatus);

   447 

   448     /**

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

   450    * 

   451    * @param aFilePath full path of new attachment.

   452    * @param aInsertBefore defines position of new attachment,

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

   454    * @param aContentType attachment content type

   455 

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

   457    */ 

   458    IMPORT_C CFSMailMessagePart* AddNewAttachmentL( const TDesC& aFilePath, 

   459                                                    const TFSMailMsgId aInsertBefore,

   460                                                    const TDesC& aContentType );

   461     /**

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

   463      *

   464      */

   465      IMPORT_C TUint ReadOnlyPartSize() const;

   466 

   467     /**

   468      * read only part size mutator

   469      *

   470      * @param aReadOnlyPartSize read only size to be set

   471      * (character or byte count)

   472      */

   473      IMPORT_C void SetReadOnlyPartSize(const TUint aReadOnlyPartSize);

   474      

   475      /**

   476       * removes attachment downloaded contents from local/terminal memory

   477       *

   478       */

   479      IMPORT_C void RemoveDownLoadedAttachmentsL();

   480      

   481      //<qmail>

   482      /**

   483  	 * gets the new NmMessagePart object

   484  	 *

   485  	 * @return NmMessagePart object

   486  	 */

   487  	 IMPORT_C NmMessagePart* GetNmMessagePart();

   488      //<qmail>

   489  	 

   490  	 //<qmail>

   491      /**

   492       * Gets the text content from private shared object.

   493       * Returns the ownership of text buffer to caller.

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

   495       * 

   496       * @return HBufC*

   497       */

   498      IMPORT_C HBufC* GetLocalTextContentLC();

   499      //<qmail>

   500      

   501      

   502 public: // data

   503 

   504 protected:

   505 

   506     /**

   507      * constructor

   508      */

   509      CFSMailMessagePart();

   510 

   511     /**

   512      * lists subparts

   513      */

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

   515        

   516     /**

   517      * clears internal part array

   518      */

   519      void ClearPartsArray(TBool aClearAll);

   520      

   521     /**

   522      * finds id of body part

   523      */

   524    TFSMailMsgId FindBodyPartIdL(const TDesC& aContentType);

   525 

   526      /**

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

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

   529      * plain text or html body.

   530      * 

   531      * @param aParts contains flat list of attachments

   532      */        

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

   534 

   535 protected: // data

   536 

   537    CFSMailRequestHandler*       iRequestHandler;  

   538 

   539     /**

   540      * email fetch from email server status

   541      */

   542    TFSPartFetchState          iMessagePartsStatus;

   543 

   544  	/**

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

   546  	 */

   547  	 mutable TPtrC						iContentTypePtr;

   548 	 

   549   	/** message parts array */

   550 	 RPointerArray<CFSMailMessagePart>	iMessageParts;

   551 	 TBool                              iReadMessageParts;

   552 	 

   553     //<qmail>

   554 	/**

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

   556 	 */

   557 	 QExplicitlySharedDataPointer<NmMessagePartPrivate> iNmPrivateMessagePart;

   558     //<qmail>

   559 

   560 protected:

   561 

   562   /**

   563      * Two-phased constructor

   564      */

   565      void ConstructL( TFSMailMsgId aMessageId, TFSMailMsgId aMessagePartId );

   566 

   567     //<qmail>

   568     /**

   569      * Two-phased constructor

   570      */

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

   572 

   573      void ConstructL(const NmMessagePart& aNmMessagePart,

   574                      const NmMessageEnvelope& aNmMessageEnvelope);

   575     //<qmail>

   576 

   577 private:	// data

   578 

   579      /** read only part size */

   580      TUint           iReadOnlyPartSize;

   581 

   582      /** fetched from email server indication */

   583      TBool           iIsFetched;

   584 

   585    	/**

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

   587    	 */

   588    	 mutable TPtrC	iContentDescriptionPtr;      

   589 

   590    	/**

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

   592    	 */

   593    	 mutable TPtrC	iContentDispositionPtr;

   594  	 

   595      /** attachment name */

   596      HBufC           *iAttachmentName;

   597 

   598      /** email content class */

   599      HBufC           *iContentClass;

   600 

   601     /**

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

   603      */

   604      mutable TPtrC	iContentIDPtr;     

   605 

   606      /** content disposition parameters */

   607      CDesCArray      *iContentDispositionParams;

   608 

   609      /** content type parameters */

   610      CDesCArray      *iContentTypeParams;

   611 

   612      /** meeting request object */

   613      MMRInfoObject*  iMeetingRequest;           

   614 

   615      /* temp file handle */

   616      RFile           iFile;

   617  };

   618 

   619 #endif // __CFSMAILMESSAGEPART_H