1 /*

     2 * Copyright (c) 2006 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:  

    15 *

    16 */

    17 

    18 

    19 #ifndef M_NCDOPERATION_H

    20 #define M_NCDOPERATION_H

    21 

    22 #include <e32cmn.h>

    23 

    24 #include "catalogsbase.h"

    25 #include "ncdinterfaceids.h"

    26 

    27 class TNcdProgress;

    28 class MNcdQuery;

    29 class MNcdNode;

    30 

    31 /**

    32  *  Main operation interface.

    33  *

    34  *  Operation objects are used in the Catalogs engine for potentially

    35  *  time consuming operations e.g. downloading items or loading node data

    36  *  from server. 

    37  *

    38  *  Operation objects function asynchronously. All operations have their own 

    39  *  observer interface that operation users should implement. Callbacks to

    40  *  observers occur at key points in an operation's execution. These points

    41  *  include progress events, query receival and operation completion.

    42  *

    43  *  All operations related to a node that they are started from. The node can

    44  *  be aqcuired via this interface. The intention is that operations mostly 

    45  *  just notify their observers of progress, completion etc. and that the 

    46  *  observers can get what they need via the node.

    47  *

    48  *  Operations can send querys to observers at any time. Querys always need

    49  *  to be completed before the operation can continue! Querys are mostly sent

    50  *  in situations where user interaction is needed to continue the operation

    51  *  (e.g. filling credit card information for a purchase operation).

    52  *

    53  *  @note Parallel operations from different clients for one node metadata are

    54  *  not supported. Requests for an operation for a node metadata that already

    55  *  has an active operation for another client, will fail with the error code

    56  *  KNcdErrorParallelOperationNotAllowed.

    57  *

    58  *  This affects only clients using the same family id, and only operations that

    59  *  are node-specific. Operation request methods that can cause this have this 

    60  *  potential exception in their comments.

    61  *

    62  *  Clients can handle this situation e.g. by waiting a moment and trying again

    63  *  to see if the other operation has completed. However, as a general rule

    64  *  situations where clients run in parallel and excecute operations on the

    65  *  same content should be avoided to allow smooth operation of said clients.

    66  *

    67  *  @see MNcdNode

    68  *  @see MNcdQuery

    69  *  

    70  */

    71 class MNcdOperation : public virtual MCatalogsBase

    72     {

    73     

    74 public:

    75 

    76     /**

    77      * Unique identifier for the interface, required for all MCatalogsBase interfaces.

    78      *

    79      * 

    80      */

    81     enum { KInterfaceUid = ENcdOperationUid };

    82     

    83     /** 

    84      * Operation states.

    85      *

    86      * 

    87      */

    88     enum TState

    89         {

    90         /** Nothing done yet, initial state. */

    91         EStateStopped,

    92         

    93         /** Operation is running. */

    94         EStateRunning,

    95         

    96         /** Waiting query completion. */

    97         EStateQuery,

    98         

    99         /** Operation complete. */

   100         EStateComplete,

   101         

   102         /** Operation cancelled */

   103         EStateCancelled

   104         

   105         };

   106 

   107     /**

   108      * Getter for operation state. It can be useful to find

   109      * out the operations state in situations where the operation

   110      * is not actively monitored (via observer) or where an operation

   111      * is left in an unactive state and later resumed.

   112      *

   113      * @return State of the operation.

   114      */

   115     virtual TState OperationStateL() const = 0;

   116     

   117     /**

   118      * Type of the operation. This can be used to easily get the 

   119      * correct interface via QueryInterfaceL.

   120      *

   121      * @return Interface id of the operation interface.

   122      */

   123     virtual TNcdInterfaceId OperationType() const = 0;

   124     

   125     /**

   126      * Starts operation, an asynchronous function.

   127      *

   128      * @exception KErrInUse if operation already started.

   129      * @exception KErrCancel if operation has been cancelled

   130      */

   131     virtual void StartOperationL() = 0;

   132     

   133     /**

   134      * Cancel operation, a synchronous function.

   135      *

   136      * OperationComplete() will be called for each observer with KErrCancel

   137      * as the error parameter.

   138      *

   139      * @note Operation can not be started again.

   140      */

   141     virtual void CancelOperation() = 0;

   142 

   143     /**

   144      * Returns current progress information immediately.

   145      * Can be safely used during an ui update. Users should always use this

   146      * method when displaying progress information for operations.

   147      *

   148      * Both made progress and maximum progress can change during an operation

   149      * e.g. when file size information is received for a download operation.

   150      *

   151      * Progress information should never be used to decide whether an 

   152      * operation has been completed! Operation completion is always explicitly

   153      * notified via an observer callback!

   154      * 

   155      * @return Structure describing operation progress.

   156      */

   157     virtual TNcdProgress Progress() const = 0;

   158 

   159     /**

   160      * Notifies the operation that the current query has been completed. This

   161      * must be called to continue the operation if a query is pending! 

   162      * The query is acquired in the operation callback.

   163      *

   164      * Before completion, the query object needs to be set to a valid state.

   165      * This means that all its non-optional items need to be set to valid

   166      * values and the query is accepted, OR the query is declined/cancelled.

   167      *

   168      * @exception KErrNotFound No query object pending for the operation.

   169      *            KErrNotReady Query object is not in a valid state.

   170      */

   171     virtual void CompleteQueryL( MNcdQuery& aQuery ) = 0;

   172     

   173     /**

   174      * Getter for the node that this operation was started from.

   175      * This can be used in callbacks to easily access the related node.

   176      *

   177      * @note AddRef() is called to the node so the user must call Release()

   178      *       when no longer needed.

   179      * @return Pointer to the node object that originated this operation.

   180      *         Counted, Release() must be called after use.

   181      */

   182     virtual MNcdNode* Node() = 0;

   183 

   184 protected:

   185 

   186     /**

   187     * Destructor.

   188     *

   189     * @see MCatalogsBase::~MCatalogsBase

   190     */

   191     virtual ~MNcdOperation() {}

   192 

   193     };

   194 	

   195 	

   196 #endif //  M_NCDOPERATION_H