--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ncdengine/inc/ncdoperation.h Thu Dec 17 08:51:10 2009 +0200
@@ -0,0 +1,196 @@
+/*
+* 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