/*
* 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