Collapse all Symbian^3 Product Developer Library

MNcdOperation Class Reference

class MNcdOperation : public MCatalogsBase

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.

MNcdNode MNcdQuery

Inherits from

MNcdOperation
- MCatalogsBase

Public Member Functions
void	CancelOperation()
void	CompleteQueryL(MNcdQuery &)
MNcdNode *	Node()
TState	OperationStateL()
TNcdInterfaceId	OperationType()
TNcdProgress	Progress()
void	StartOperationL()

Protected Member Functions
	~MNcdOperation()

Inherited Functions
	MCatalogsBase::AddRef()const
	MCatalogsBase::QueryInterfaceL()
	MCatalogsBase::QueryInterfaceL()const
	MCatalogsBase::QueryInterfaceL(TInt)const
	MCatalogsBase::QueryInterfaceLC()
	MCatalogsBase::QueryInterfaceLC()const
	MCatalogsBase::Release()const
	MCatalogsBase::~MCatalogsBase()

Public Member Enumerations
enum	TState { EStateStopped, EStateRunning, EStateQuery, EStateComplete, EStateCancelled }

Inherited Enumerations
	MCatalogsBase:@52

Constructor & Destructor Documentation

~MNcdOperation()

~MNcdOperation

(

)

[protected, inline, virtual]

Destructor.

MCatalogsBase::~MCatalogsBase

Member Functions Documentation

CancelOperation()

void

CancelOperation

(

)

[pure virtual]

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.

CompleteQueryL(MNcdQuery &)

void

CompleteQueryL

(

MNcdQuery &

aQuery

)

[pure virtual]

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.

Exceptions

KErrNotFound

No query object pending for the operation. KErrNotReady Query object is not in a valid state.

Parameters

MNcdQuery & aQuery

Node()

MNcdNode *

Node

(

)

[pure virtual]

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.

OperationStateL()

TState

OperationStateL

(

)

const [pure virtual]

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.

OperationType()

TNcdInterfaceId

OperationType

(

)

const [pure virtual]

Type of the operation. This can be used to easily get the correct interface via QueryInterfaceL.

Progress()

TNcdProgress

Progress

(

)

const [pure virtual]

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!

StartOperationL()

void

StartOperationL

(

)

[pure virtual]

Starts operation, an asynchronous function.

Exceptions

KErrInUse	if operation already started.
KErrCancel	if operation has been cancelled

Member Enumerations Documentation

Enum TState

Operation states.

Enumerators

EStateStopped	Nothing done yet, initial state.
EStateRunning	Operation is running.
EStateQuery	Waiting query completion.
EStateComplete	Operation complete.
EStateCancelled	Operation cancelled