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 __MEMAILACTIONS

    19 #define __MEMAILACTIONS

    20 

    21 #include <e32cmn.h>

    22 #include <memailmessage.h>

    23 

    24 namespace EmailInterface {

    25 

    26 class MMessageIterator;

    27 class TEmailSortCriteria;

    28 

    29 /**

    30 * Observer interface for handling email search results.

    31 */

    32 class MEmailSearchObserver

    33 {

    34 public:

    35     /**

    36      * Called when search has next message available.

    37      * This callback is called several times until all results

    38      * have been delivered.

    39      *

    40      * @param message found in search, ownership is transferred.

    41      *          

    42      */ 

    43     virtual void HandleResultL( 

    44         MEmailMessage* aMessage ) = 0;

    45 

    46     /**

    47      * Notifies that the search has completed and no more results are expected.

    48      */

    49     virtual void SearchCompletedL() = 0;

    50 };

    51 

    52 /**

    53  * Search interface for messages. Results are provided asynchronoysly.

    54  * By default all found mailboxes are included in search.

    55  * @code

    56    

    57    MEmailMailbox* mailbox = NULL;

    58    // obtain mailbox here... 

    59    // ...and now get search interface

    60    MEmailMessageSearchAsync* search = mailbox->MessageSearchL();

    61    CleanupReleasePushL( *search );

    62    TEmailSortCriteria criteria;

    63    criteria.iAscending = ETrue;

    64    criteria.iField = TEmailSortCriteria::EByDate;                 

    65    search->SetSortCriteriaL( criteria );

    66    search->StartSearchL( *this ); // this implements MEmailSearchObserver

    67    search->Cancel(); // cancel search

    68    CleanupStack::PopAndDestroy(); // search

    69    

    70    @endcode

    71    

    72  * @since S60 v5.0

    73  */

    74 class MEmailMessageSearchAsync : public MEmailInterface

    75 {

    76 public:

    77         

    78     /**

    79     * Sets sort order for search results.

    80     * Leaves KErrNotReady if search is ongoing.

    81     */

    82     virtual void SetSortCriteriaL( const TEmailSortCriteria& aCriteria ) = 0;

    83     

    84     /**

    85     * Adds a search key. Leaves KErrNotReady if search is ongoing.

    86     */

    87     virtual void AddSearchKeyL( const TDesC& aSearchKey ) = 0;

    88                                                                   

    89     /**

    90     * Enables/disables search from remote email server.

    91     * Leaves KErrNotReady if search is ongoing.

    92     */

    93     virtual void SetRemoteSearchL( TBool aRemote ) = 0;                                                                  

    94     

    95     /**

    96     * Indicates whether remote search is enabled.

    97     */

    98     virtual TBool IsRemoteSearch() const = 0;

    99     

   100     /**

   101      * Starts search, all methods affecting search attribures leave

   102      * KErrNotReady while search is ongoing.

   103      * @param aObserver called when results are available.

   104      */     

   105     virtual void StartSearchL( MEmailSearchObserver& aObserver ) = 0;

   106 

   107     /**

   108      * Cancels search.

   109      */

   110     virtual void Cancel() = 0;

   111                                              

   112     /** returns search status 

   113       * @return search status:

   114       *     < 0 : Search has failed

   115       *     KRequestPending : search is ongoing. note that status may be

   116       *         KRequestPending after HandleResultL callback because results 

   117       *         may be given in chunks of results. Size of chunk depends on

   118       *         implementation and may vary.

   119       *     KErrNone : initial state, or search has finished

   120       */

   121     virtual TInt Status() const = 0;

   122     

   123     /**

   124      * Resets all search attribures. Cancels search if ongoing. 

   125      */

   126     virtual void Reset() = 0;

   127 };

   128 

   129 } //EmailInterface

   130 

   131 #endif // __MEMAILACTIONS

   132 

   133 // End of file.