1 /*

     2 * Copyright (c) 2010 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: ECom interface for Email Client API

    15 *

    16 */

    17 

    18 #ifndef MEMAILCONTENT_H

    19 #define MEMAILCONTENT_H

    20 

    21 #include <emailapidefs.h>

    22 

    23 namespace EmailInterface {

    24 

    25 _LIT( KContentTypeTextPlain, "text/plain" );

    26 _LIT( KContentTypeTextHtml, "text/html" );

    27 

    28 class MEmailOperationObserver;

    29 class MEmailAttachment;

    30 class MEmailMultipart;

    31 class MEmailTextContent;

    32 class MEmailMessageContent;

    33 

    34 /**

    35 * Callback interface used for content fetching asynchronously.

    36 * Object deriving this interface is passed to MEmailMessageContent::FetchL

    37 * @since S60 v5.0

    38 */

    39 class MEmailFetchObserver

    40 {

    41 public:

    42     /** Content fetched

    43     * @param operation result 

    44     */

    45     virtual void DataFetchedL( const TInt aResult ) = 0;

    46 };

    47 

    48 typedef RPointerArray<MEmailMessageContent> REmailContentArray;

    49 

    50 /**

    51 * Base interface for mime message parts.

    52 * @since S60 v5.0

    53 */

    54 class MEmailMessageContent : public MEmailInterface

    55 {

    56 public:

    57     /** numeric identifier of message content */

    58     virtual TMessageContentId Id() const = 0;

    59 

    60 // fields as per RFC 2045

    61     /**

    62      * return sContent-Type field value

    63      */

    64     virtual TPtrC ContentType() const = 0;

    65 

    66     /**

    67      * sets value of Content-Type field

    68      * @param content type

    69      */

    70     virtual void SetContentType( const TDesC& aContentType ) = 0;

    71 

    72     /**

    73     /* Returns Content-ID field value.

    74      * @return content id

    75      */

    76     virtual TPtrC ContentId() const = 0;

    77 

    78     /**

    79      * Sets value of Content-ID field

    80      * @param content id

    81      */

    82     virtual void SetContentId( const TDesC& aContentId ) = 0;

    83 

    84     /**

    85      * Returns value of content-description field

    86      * @return content description 

    87      */

    88     virtual TPtrC ContentDescription() const = 0;

    89 

    90     /**

    91      * Sets value of content description field

    92      * @param content description 

    93      */

    94     virtual void SetContentDescription( const TDesC& aContentDescription ) = 0;

    95 

    96     /**

    97      * Returns value of content disposition field

    98      * @return content disposition

    99      */

   100     virtual TPtrC ContentDisposition() const = 0;

   101 

   102     /**

   103      * Sets value of content-disposition field

   104      * @param content disposition

   105      */

   106     virtual void SetContentDisposition( const TDesC& aContentDisposition ) = 0;

   107 

   108 // end of standard  RFC 2045 fields

   109 

   110     /**

   111      * returns Content-class field value (non-standard)

   112      */

   113     virtual TPtrC ContentClass() const = 0;

   114 

   115     /**

   116      * Sets value of Content-class field (non-standard)

   117      * @param content class

   118      */

   119     virtual void SetContentClass( const TDesC& aContentClass ) = 0;

   120 

   121     /**

   122      * Available (=fetched) size accessor. If this is less than value from

   123      * TotalSize(), Fetch() should be used to retrieve more data from

   124      * remote mail server.

   125      * @return fetched size of the data.

   126      */

   127     virtual TInt AvailableSize() const = 0;

   128 

   129     /**

   130      * Total size accessor

   131      * @return total size of message text.

   132      */

   133     virtual TInt TotalSize( ) const = 0;

   134 

   135     /**

   136      * Returns pointer descriptor to content data

   137      */

   138     virtual TPtrC ContentL() const = 0;

   139 

   140     /**

   141      * Sets content data.

   142      */

   143     virtual void SetContentL( const TDesC& aContent ) = 0;

   144 

   145     /**

   146      * Starts fetching rest of content asynchronously.

   147      *

   148      * If available size after fetch is smaller than total size, next chunk can

   149      * be fetched with new invocatin of Fetch method.

   150      *

   151      * Calling Release() implicitly cancels fetching.

   152      * @param aObserver called when when fetch completes.

   153      * @exception KErrInUse if fetch is ongoing

   154      */

   155     virtual void FetchL( MEmailFetchObserver& aObserver ) = 0;

   156 

   157     /**

   158      * Cancels fetch operation, observer is not called

   159      */

   160     virtual void CancelFetch() = 0;

   161 

   162     /**

   163      * Stores message content to a file

   164      */

   165     virtual void SaveToFileL( const TDesC& aPath ) = 0;

   166 

   167     /**

   168      * Typesafe multipart accessor for obtaining MEmailMultipart pointer

   169      * to this object.

   170      * @param content as multipart or NULL if content is not multipart

   171      */

   172     virtual MEmailMultipart* AsMultipartOrNull() const = 0;

   173 

   174     /**

   175      * Typesafe text content accessor for obtaining MEmailTextContent pointer

   176      * to this object.

   177      * @param content as text content or NULL if content is not text

   178      */

   179     virtual MEmailTextContent* AsTextContentOrNull() const = 0;

   180 

   181     /**

   182      * Typesafe attachment content accessor for obtaining MEmailAttachment pointer

   183      * to this object.

   184      * @param content as attachment content or NULL if content is not an attachment

   185      */

   186     virtual MEmailAttachment* AsAttachmentOrNull() const = 0;

   187 };

   188 

   189 /**

   190 * Convenience abstraction for manipulating plain or html text content. Use

   191 * CEmailInterfaceFactory::InterfaceL( KEmailIFUidTextContent ) to make new

   192 * instance of this interface.

   193 * @since S60 v5.0

   194 */

   195 class MEmailTextContent : public MEmailMessageContent

   196 {

   197 public:

   198     /**

   199      * Text (content) type 

   200      */

   201     enum TTextType {

   202         EPlainText, // text/plain

   203         EHtmlText   // text/html

   204     };

   205 

   206     /**

   207     * Tells if content has specified type of text.

   208     */

   209     virtual TTextType TextType() const = 0;

   210 

   211     /**

   212     * Sets (replaces) text to message content. Possible old content is

   213     * deleted. Content type is set to "text/plain" or "text/html" based on

   214     * specified text type.

   215     * @param aPlainOrHtml sub-type of the text

   216     * @param aText content of the message part

   217     */

   218     virtual void SetTextL(

   219         const TTextType aPlainOrHtml,

   220         const TDesC& aText ) = 0;

   221 };

   222 

   223 /**

   224 * Message part with multiple sub parts. If MEmailMessage::ContentL returns

   225 * content with type "multipart/*" (where '*' is a character sequence) it can

   226 * safely be casted to MEmailMultipart

   227 * @since S60 v5.0

   228 */

   229 class MEmailMultipart : public MEmailMessageContent

   230 {

   231 public:

   232     /**

   233     * Returns number of child parts

   234     */

   235     virtual TInt PartCountL() = 0;

   236 

   237     /**

   238     * Returns a child part, ownership is transferred.

   239     * @param aIndex part to return, leaves KErrArgument if out of bounds

   240     */

   241     virtual MEmailMessageContent* PartByIndexL( const TUint aIndex ) const = 0;

   242 

   243     /**

   244     * Deletes part by index.

   245     * @param aIndex part to delete, leaves KErrArgument if out of bounds

   246     */

   247     virtual void DeletePartL( const TUint aIndex ) = 0;

   248 

   249     /**

   250     * Adds message part, ownership is transferred.

   251     * @param aPart any object derived from MEmailMessageContent

   252     * @param aPos position among child parts

   253     */

   254     virtual void AddPartL(

   255         const MEmailMessageContent& aPart,

   256         const TUint aPos ) = 0;

   257 };

   258 

   259 typedef RPointerArray<MEmailAttachment> REmailAttachmentArray;

   260 

   261 /**

   262 * Email attachment interface

   263 * Attachment is created with MEmailMessage::AddAttachmentL()

   264 * @since S60 v5.0

   265 */

   266 class MEmailAttachment : public MEmailMessageContent

   267 {

   268 public:

   269       /**

   270       * Returns file handle of this attachment. If the attachment is

   271       * not associated with a file, null file handle is returned.

   272       */

   273       virtual RFile FileL() const = 0;

   274 

   275       /**

   276       * Sets file name field

   277       */

   278       virtual void SetFileNameL( const TDesC& aFileName ) = 0;

   279 

   280       /**

   281       * Returns file name or null pointer descriptor if attachment

   282       * is not associated with any file

   283       */

   284       virtual TPtrC FileNameL() const = 0;

   285 };

   286 

   287 } // namespace EmailInterface

   288 

   289 #endif // MEMAILCONTENT_H