/*+
−
* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).+
−
* All rights reserved.+
−
* This component and the accompanying materials are made available+
−
* under the terms of "Eclipse Public License v1.0"+
−
* which accompanies this distribution, and is available+
−
* at the URL "http://www.eclipse.org/legal/epl-v10.html".+
−
*+
−
* Initial Contributors:+
−
* Nokia Corporation - initial contribution.+
−
*+
−
* Contributors:+
−
*+
−
* Description:  +
−
*+
−
*/+
−
+
−
+
−
#ifndef M_NCDOPERATION_H+
−
#define M_NCDOPERATION_H+
−
+
−
#include <e32cmn.h>+
−
+
−
#include "catalogsbase.h"+
−
#include "ncdinterfaceids.h"+
−
+
−
class TNcdProgress;+
−
class MNcdQuery;+
−
class MNcdNode;+
−
+
−
/**+
−
 *  Main operation interface.+
−
 *+
−
 *  Operation objects are used in the Catalogs engine for potentially+
−
 *  time consuming operations e.g. downloading items or loading node data+
−
 *  from server. +
−
 *+
−
 *  Operation objects function asynchronously. All operations have their own +
−
 *  observer interface that operation users should implement. Callbacks to+
−
 *  observers occur at key points in an operation's execution. These points+
−
 *  include progress events, query receival and operation completion.+
−
 *+
−
 *  All operations related to a node that they are started from. The node can+
−
 *  be aqcuired via this interface. The intention is that operations mostly +
−
 *  just notify their observers of progress, completion etc. and that the +
−
 *  observers can get what they need via the node.+
−
 *+
−
 *  Operations can send querys to observers at any time. Querys always need+
−
 *  to be completed before the operation can continue! Querys are mostly sent+
−
 *  in situations where user interaction is needed to continue the operation+
−
 *  (e.g. filling credit card information for a purchase operation).+
−
 *+
−
 *  @note Parallel operations from different clients for one node metadata are+
−
 *  not supported. Requests for an operation for a node metadata that already+
−
 *  has an active operation for another client, will fail with the error code+
−
 *  KNcdErrorParallelOperationNotAllowed.+
−
 *+
−
 *  This affects only clients using the same family id, and only operations that+
−
 *  are node-specific. Operation request methods that can cause this have this +
−
 *  potential exception in their comments.+
−
 *+
−
 *  Clients can handle this situation e.g. by waiting a moment and trying again+
−
 *  to see if the other operation has completed. However, as a general rule+
−
 *  situations where clients run in parallel and excecute operations on the+
−
 *  same content should be avoided to allow smooth operation of said clients.+
−
 *+
−
 *  @see MNcdNode+
−
 *  @see MNcdQuery+
−
 *  +
−
 */+
−
class MNcdOperation : public virtual MCatalogsBase+
−
    {+
−
    +
−
public:+
−
+
−
    /**+
−
     * Unique identifier for the interface, required for all MCatalogsBase interfaces.+
−
     *+
−
     * +
−
     */+
−
    enum { KInterfaceUid = ENcdOperationUid };+
−
    +
−
    /** +
−
     * Operation states.+
−
     *+
−
     * +
−
     */+
−
    enum TState+
−
        {+
−
        /** Nothing done yet, initial state. */+
−
        EStateStopped,+
−
        +
−
        /** Operation is running. */+
−
        EStateRunning,+
−
        +
−
        /** Waiting query completion. */+
−
        EStateQuery,+
−
        +
−
        /** Operation complete. */+
−
        EStateComplete,+
−
        +
−
        /** Operation cancelled */+
−
        EStateCancelled+
−
        +
−
        };+
−
+
−
    /**+
−
     * Getter for operation state. It can be useful to find+
−
     * out the operations state in situations where the operation+
−
     * is not actively monitored (via observer) or where an operation+
−
     * is left in an unactive state and later resumed.+
−
     *+
−
     * @return State of the operation.+
−
     */+
−
    virtual TState OperationStateL() const = 0;+
−
    +
−
    /**+
−
     * Type of the operation. This can be used to easily get the +
−
     * correct interface via QueryInterfaceL.+
−
     *+
−
     * @return Interface id of the operation interface.+
−
     */+
−
    virtual TNcdInterfaceId OperationType() const = 0;+
−
    +
−
    /**+
−
     * Starts operation, an asynchronous function.+
−
     *+
−
     * @exception KErrInUse if operation already started.+
−
     * @exception KErrCancel if operation has been cancelled+
−
     */+
−
    virtual void StartOperationL() = 0;+
−
    +
−
    /**+
−
     * Cancel operation, a synchronous function.+
−
     *+
−
     * OperationComplete() will be called for each observer with KErrCancel+
−
     * as the error parameter.+
−
     *+
−
     * @note Operation can not be started again.+
−
     */+
−
    virtual void CancelOperation() = 0;+
−
+
−
    /**+
−
     * Returns current progress information immediately.+
−
     * Can be safely used during an ui update. Users should always use this+
−
     * method when displaying progress information for operations.+
−
     *+
−
     * Both made progress and maximum progress can change during an operation+
−
     * e.g. when file size information is received for a download operation.+
−
     *+
−
     * Progress information should never be used to decide whether an +
−
     * operation has been completed! Operation completion is always explicitly+
−
     * notified via an observer callback!+
−
     * +
−
     * @return Structure describing operation progress.+
−
     */+
−
    virtual TNcdProgress Progress() const = 0;+
−
+
−
    /**+
−
     * Notifies the operation that the current query has been completed. This+
−
     * must be called to continue the operation if a query is pending! +
−
     * The query is acquired in the operation callback.+
−
     *+
−
     * Before completion, the query object needs to be set to a valid state.+
−
     * This means that all its non-optional items need to be set to valid+
−
     * values and the query is accepted, OR the query is declined/cancelled.+
−
     *+
−
     * @exception KErrNotFound No query object pending for the operation.+
−
     *            KErrNotReady Query object is not in a valid state.+
−
     */+
−
    virtual void CompleteQueryL( MNcdQuery& aQuery ) = 0;+
−
    +
−
    /**+
−
     * Getter for the node that this operation was started from.+
−
     * This can be used in callbacks to easily access the related node.+
−
     *+
−
     * @note AddRef() is called to the node so the user must call Release()+
−
     *       when no longer needed.+
−
     * @return Pointer to the node object that originated this operation.+
−
     *         Counted, Release() must be called after use.+
−
     */+
−
    virtual MNcdNode* Node() = 0;+
−
+
−
protected:+
−
+
−
    /**+
−
    * Destructor.+
−
    *+
−
    * @see MCatalogsBase::~MCatalogsBase+
−
    */+
−
    virtual ~MNcdOperation() {}+
−
+
−
    };+
−
	+
−
	+
−
#endif //  M_NCDOPERATION_H+
−