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

    32 class CFSMailMessage;

    33 class MFSMailRequestObserver;

    34 

    35 const TInt KArrayGranularity = 16;

    36 

    37 /**

    38  *  email parts handling class

    39  *

    40  *  @lib FSFWCommonLib

    41  *  @since S60 v3.1

    42  */

    43 class CFSMailMessagePart : public CFSMailMessageBase

    44 {

    45  public:

    46 

    47     /**

    48      * Two-phased constructor.

    49      *

    50      * @param aMessageId message id in plugin containing email

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

    52      */

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

    54 

    55     /**

    56      * Two-phased constructor.

    57      *

    58      * @param aMessageId message id in plugin containing email

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

    60      */

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

    62 

    63     /**

    64      * destructor

    65      */  

    66      IMPORT_C virtual ~CFSMailMessagePart();

    67      

    68     /**

    69      * email part id accessor

    70      *

    71      * @return email part id

    72      */

    73      IMPORT_C TFSMailMsgId GetPartId() const;

    74 

    75     /**

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

    77      *

    78      * @return email part content type

    79      */

    80      IMPORT_C const TDesC& GetContentType();

    81     

    82     /**

    83      * email part content-type mutator 

    84      *

    85      * @param aContentType new content type value

    86      */

    87      IMPORT_C void SetContentType(const TDesC& aContentType);

    88 

    89     /**

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

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

    92      * then modifying it's contents.

    93      * 

    94      * @return content type parameters

    95      */

    96      IMPORT_C CDesCArray& ContentTypeParameters();

    97      

    98     /**

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

   100      * if any.

   101      *

   102      * @return email Content-Description

   103      */

   104      IMPORT_C const TDesC& ContentDescription();

   105      

   106     /**

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

   108      * if any.

   109      *

   110      * @param aContentDescription new email content description value

   111      */

   112      IMPORT_C void SetContentDescription(const TDesC& aContentDesctiption);

   113 

   114     /**

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

   116      * if any.

   117      *

   118      * @return email Content-Disposition

   119      */

   120      IMPORT_C const TDesC& ContentDisposition();

   121      

   122     /**

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

   124      * if any.

   125      *

   126      * @param aContentDisposition new email content disposition value

   127      */    

   128      IMPORT_C void SetContentDisposition(const TDesC& aContentDesctiption);

   129 

   130     /**

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

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

   133      * then modifying it's contents.

   134      *

   135      * @return content disposition parameters

   136      */

   137      IMPORT_C CDesCArray& ContentDispositionParameters();

   138 

   139     /**

   140      * email Content-Id accessor.

   141      *

   142      * @return email Content-Id

   143      */

   144      IMPORT_C const TDesC& ContentID();

   145      

   146     /**

   147      * email Content-Id mutator

   148      *

   149      * @param aContentID new email Content-Id value

   150      */

   151      IMPORT_C void SetContentIDL(const TDesC& aContentID);

   152 

   153     /**

   154      * email Content-Class accessor

   155      *

   156      * @return email Content-Class

   157      */

   158      IMPORT_C const TDesC& GetContentClass();

   159 

   160     /**

   161      * email Content-Class mutator

   162      *

   163      * @param aContentClass new email Content-Class value

   164      */

   165      IMPORT_C void SetContentClass( const TDesC& aContentClass );

   166 

   167     /**

   168      * saves this message part 

   169      */

   170      IMPORT_C void SaveL();

   171     

   172     /**

   173      * lists all direct child parts of this email part

   174      *

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

   176      */

   177      IMPORT_C void ChildPartsL(RPointerArray<CFSMailMessagePart>& aParts);

   178 

   179     /**

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

   181      * 

   182      * @param aPartId defines parent part id

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

   184      */

   185      IMPORT_C CFSMailMessagePart* ChildPartL( const TFSMailMsgId aPartId );

   186 

   187     /**

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

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

   190      * 

   191      * @return ETrue if this email part is email

   192      */        

   193      IMPORT_C virtual TBool IsMessageL() const;

   194 

   195     /**

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

   197      * 

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

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

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

   201      *

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

   203      */

   204      IMPORT_C CFSMailMessagePart* NewChildPartL( const TFSMailMsgId aInsertBefore,

   205                                                  const TDesC& aContentType );

   206 

   207     /**

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

   209      *

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

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

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

   213      *

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

   215      */        

   216      IMPORT_C CFSMailMessagePart* CopyMessageAsChildPartL( TFSMailMsgId aInsertBefore,

   217                                                            CFSMailMessage* aMessage);

   218 

   219     /**

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

   221      * 

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

   223      */

   224      IMPORT_C void RemoveChildPartL(TFSMailMsgId aPartId);

   225 

   226     /**

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

   228      * The caller must close the file handle.

   229      *

   230      * @return content file handle 

   231      */

   232      IMPORT_C RFile GetContentFileL();

   233         

   234     /**

   235      * copies contents of this message part to given file

   236      *

   237      * @param aContentLocation defines file location as 

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

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

   240      *    be '/'

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

   242      *    are given by user

   243      * 

   244      */        

   245      IMPORT_C void CopyContentFileL(const TDesC& aContentLocation);

   246 

   247     /**

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

   249      *

   250      * @param aFilePath defines the target file

   251      */

   252      IMPORT_C void SetContentFromFileL(const TDesC& aFilePath);

   253 

   254     /**

   255      * Removes from message store fetched contents of this part

   256      * and possible child parts

   257      *

   258      */  

   259      IMPORT_C void RemoveContentL();

   260     

   261     /**

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

   263      *

   264      */

   265      IMPORT_C TUint ContentSize() const;

   266 

   267     /**

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

   269      *

   270      * @param aContentSize content size to be set

   271      */

   272      IMPORT_C void SetContentSize(const TUint aContentSize);

   273     

   274     /**

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

   276      * 

   277      */

   278      IMPORT_C TUint FetchedContentSize() const;

   279 

   280     /**

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

   282      * 

   283      * @param aContentSize content size to be set

   284      */

   285      IMPORT_C void SetFetchedContentSize(TUint aContentSize);

   286 

   287     /**

   288      * returns email part content current fetch state

   289      * Intended as utility function for UI.

   290      * If (0 == FetchedContentSize())

   291      *    return EFSNone;

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

   293      *    return EFSPartial

   294      * else

   295      *    return EFSFull

   296      *

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

   298      */

   299      IMPORT_C TFSPartFetchState FetchLoadState() const;

   300 

   301     /**

   302      * copies email part contents to buffer given by user

   303      *

   304      * @param aBuffer buffer owned by user

   305      * @param aStartOffset offset from content begin

   306      */

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

   308     

   309     /**

   310      * copies email part contents from buffer given by user

   311      *

   312      * @param aBuffer buffer given by user

   313      */

   314      IMPORT_C void SetContent(TDes16& aBuffer); 

   315 

   316     /**

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

   318      * 

   319      * @return meeting request object

   320      */

   321      IMPORT_C MMRInfoObject& GetMRInfo();

   322     

   323     /**

   324      * stores given meeting request object as email part

   325      * 

   326      * @param aMeetingRequest meeting request object

   327      */

   328      IMPORT_C void SetMRInfo(MMRInfoObject* aMeetingRequest);

   329 

   330     /**

   331      * method checks if MRInfo exists

   332      * 

   333      * @return true / false

   334      */

   335      IMPORT_C TBool IsMRInfoSet();

   336 

   337     /**

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

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

   340      * 

   341      * @param aFilePath attachment name

   342      */        

   343      IMPORT_C void SetAttachmentNameL(const TDesC& aFilePath);

   344 

   345     /**

   346      * returns email part attachment name

   347      * 

   348      * @return attachment name

   349      */        

   350      IMPORT_C TDesC& AttachmentNameL();

   351     

   352     /**

   353      * finds email body part based on given content type 

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

   355      * 

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

   357      *

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

   359      */

   360      IMPORT_C CFSMailMessagePart* FindBodyPartL(const TDesC& aContentType);

   361 

   362     /**

   363      * Checks that content type matches given.

   364      * 

   365      * @param aContentType body part content type to be checked

   366      *

   367      * @return ETrue if content type of message part matches tto given

   368      */

   369      IMPORT_C TBool ContentTypeMatches( const TDesC& aContentType );

   370 

   371     /**

   372      * starts email part fetching from email server

   373      * 

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

   375      * @param aOperationObserver observer to forward fetching progress events

   376      * to user

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

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

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

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

   381      *

   382      * @return err code

   383      */        

   384      IMPORT_C TInt FetchMessagePartL(   const TFSMailMsgId aMessagePartId,

   385                                         MFSMailRequestObserver& aOperationObserver,

   386                                         const TUint aPreferredByteCount);

   387 

   388     /**

   389      * starts email parts fetching from email server

   390      * 

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

   392      * @param aOperationObserver observer to forward fetching progress events

   393      * to user

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

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

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

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

   398      *

   399      * @return err code

   400      */        

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

   402                                         MFSMailRequestObserver& aOperationObserver,

   403                                         const TUint aPreferredByteCount);

   404     /**

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

   406      * 

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

   408      */        

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

   410 

   411     /**

   412      * sets email part fetch status

   413      * 

   414      * @param aMessagePartStatus (EFSMessagePartsKnown)

   415      */

   416      IMPORT_C void SetMessagePartsStatus(TFSPartFetchState aMessagePartStatus);

   417 

   418     /**

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

   420      * 

   421      * @param aFilePath full path of new attachment.

   422      * @param aInsertBefore defines position of new attachment,

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

   424      * @param aContentType attachment content type

   425 

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

   427      */ 

   428      IMPORT_C CFSMailMessagePart* AddNewAttachmentL( const TDesC& aFilePath, 

   429                                                      const TFSMailMsgId aInsertBefore,

   430                                                      const TDesC& aContentType );

   431     /**

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

   433      *

   434      */

   435      IMPORT_C TUint ReadOnlyPartSize() const;

   436 

   437     /**

   438      * read only part size mutator

   439      *

   440      * @param aReadOnlyPartSize read only size to be set

   441      * (character or byte count)

   442      */

   443      IMPORT_C void SetReadOnlyPartSize(const TUint aReadOnlyPartSize);

   444      

   445      /**

   446       * removes attachment downloaded contents from local/terminal memory

   447       *

   448       */

   449      IMPORT_C void RemoveDownLoadedAttachmentsL();

   450      

   451      

   452 public: // data

   453 

   454 protected:

   455 

   456     /**

   457      * constructor

   458      */

   459      CFSMailMessagePart();

   460 

   461     /**

   462      * lists subparts

   463      */

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

   465          

   466     /**

   467      * clears internal part array

   468      */

   469      void ClearPartsArray(TBool aClearAll);

   470      

   471     /**

   472      * finds id of body part

   473      */

   474      TFSMailMsgId FindBodyPartIdL(const TDesC& aContentType);

   475 

   476      /**

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

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

   479      * plain text or html body.

   480      * 

   481      * @param aParts contains flat list of attachments

   482      */        

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

   484 

   485 protected: // data

   486 

   487     /**

   488      * email fetch from email server status

   489      */

   490      TFSPartFetchState                  iMessagePartsStatus;

   491 

   492     /**

   493      * message part MIME type

   494      */

   495      HBufC                              *iContentType;

   496      

   497     /** message parts array */

   498      RPointerArray<CFSMailMessagePart>  iMessageParts;

   499      TBool                              iReadMessageParts;

   500 

   501 private:

   502 

   503     /**

   504      * Two-phased constructor

   505      */

   506      void ConstructL( TFSMailMsgId aMessageId, TFSMailMsgId aMessagePartId );

   507 

   508 private:    // data

   509 

   510      /** message part id */

   511      TFSMailMsgId    iMessagePartId;

   512 

   513      /** email part content size */

   514      TUint           iContentSize;

   515 

   516      /** read only part size */

   517      TUint           iReadOnlyPartSize;

   518 

   519      /** email part fetched content size */

   520      TInt            iFetchedContentSize;

   521 

   522      /** fetched from email server indication */

   523      TBool           iIsFetched;

   524 

   525      /** email content decription */

   526      HBufC           *iContentDescription;

   527 

   528      /** email content disposition */

   529      HBufC           *iContentDisposition;

   530      

   531      /** attachment name */

   532      HBufC           *iAttachmentName;

   533 

   534      /** email content class */

   535      HBufC           *iContentClass;

   536 

   537      /** email content id */

   538      HBufC           *iContentID;

   539 

   540      /** content disposition parameters */

   541      CDesCArray      *iContentDispositionParams;

   542 

   543      /** content type parameters */

   544      CDesCArray      *iContentTypeParams;

   545 

   546      /** meeting request object */

   547      MMRInfoObject*  iMeetingRequest;                       

   548 

   549      /* temp file handle */

   550      RFile           iFile;

   551  };

   552 

   553 #endif // __CFSMAILMESSAGEPART_H