/*

* Copyright (c) 2005-2009 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:  Metadata engine client session

*

*/

#ifndef __MDESESSION_H__

#define __MDESESSION_H__

#include <e32base.h>

#include <badesca.h>

#include <mdccommon.h>

/* Forward declarations. */

class CMdESession;

class CMdEObjectDef;

class CMdERelationDef;

class CMdEEventDef;

class CMdEObject;

class TMdEObject;

class CMdERelation;

class TMdERelation;

class CMdEEvent;

class CMdEObjectQuery;

class CMdERelationQuery;

class CMdEEventQuery;

class CMdELogicCondition;

class CMdEInstanceItem;

class MMdEQueryObserver;

class CMdENamespaceDef;

class RMdEDataBuffer;

class CMdECondition;

/**

 * Observer interface for a metadata engine session.

 * 

 * 

 * 

 * Examples of MdE session usage:

 * 

 * The class that needs a MdE session needs to implement MMdESessionObserver interface to get

 * a notification of completed session opening or an error that has occurred.

 * 

 * class CMdESessionExample : public MMdESessionObserver

 * {

 * 		void HandleSessionOpened(CMdESession& aSession, TInt aError);

 *   	void HandleSessionError(CMdESession& aSession, TInt aError);

 * 		...

 * 

 * 		CMdESession* iMdeSession;

 * };

 * 

 * The session is opened simply by creating an instance of CMdESession.

 * 

 * void CMdESessionExample::OpenSession()

 * {

 * 		iMdeSession = CMdESession::NewL( *this );

 * }

 * 

 * void CMdESessionExample::HandleSessionOpened(CMdESession& aSession, TInt aError)

 *	{

 *		if ( KErrNone != aError ) {

 * 			// Error occurred when opening session. iMdeSession must be deleted and new

 * 			// session opened if we wish to use MdE.

 * 

 * 			delete iMdeSession; iMdeSession = NULL;

 * 			return;

 * 		}

 * 		

 * 		// The session was opened successfully.

 * 		...

 *	}

 * 

 * void CMdESessionError::HandleSessionError(CMdESession& aSession, TInt aError)

 * {

 * 		// This function is called when an error has occurred in the session by some

 * 		// external source (e.g. other clients). It’s important to notice, that 

 * 		// this method is called when the session has already been opened, not when 

 * 		// error happens during opening. Session can't be used anymore and it must be deleted.

 * 

 * 		delete iMdeSession; iMdeSession = NULL;

 * }

 */

class MMdESessionObserver

	{

public:

	/**

	 * Called to notify the observer that opening the session has been 

	 * completed and, if the opening succeeded, the session is ready for use.

	 *

	 * @param aSession session

	 * @param aError   <code>KErrNone</code>, if opening the session succeeded;

	 *                 or one of the system-wide error codes, if opening the 

	 *                 session failed

	 */

	virtual void HandleSessionOpened(CMdESession& aSession, TInt aError) = 0;

	/**

	 * Called to notify the observer about errors, which are not a direct 

	 * consequence of the operations initiated by the client but caused by 

	 * some external source (e.g., other clients). The error cannot be 

	 * recovered and all on-going operations initiated by the client have been 

	 * aborted. Any attempts to continue using the session will cause a panic. 

	 * The client should close the session immediately and try to open a new 

	 * session, if it needs to continue using the metadata engine.

	 *

	 * @param aSession session

	 * @param aError one of the system-wide error codes

	 */

	virtual void HandleSessionError(CMdESession& aSession, TInt aError) = 0;

    };

/**

 * Observer interface for modifications of the metadata engine schema.

 */

class MMdESchemaObserver

	{

public:

	/**

	 * Called to notify the observer that the schema has been modified.

	 *

	 * @param none

	 */

	virtual void HandleSchemaModified() = 0;

    };

/**

 * Observer interface for modifications of the objects in the metadata engine 

 * database.

 * 

 * Examples of observers.

 * A class that is interested in observing events in the DB must implement observer interfaces

 * and register as observer. Following examples show how this is done for objects but observing

 * relations and events works the same way.

 * 

 * class CMdeObserverExample : public MMdEObjectObserver, public MMdEObjectPresentObserver

 * {

 *		void HandleObjectNotification(CMdESession& aSession, TObserverNotificationType aType,

 *						const RArray<TItemId>& aObjectIdArray);

 *		void HandleObjectPresentNotification(CMdESession& aSession, TBool aPresent,

 *		 				const RArray<TItemId>& aObjectIdArray);

 * 		...

 * 		CMdESession* iMdeSession;

 * };

 * 

 * void CMdeObserverExample::ConstructL()

 * {

 * 		// Register this class as observer and start listening to object remove events.

 * 		// The logic condition can be as complicated as is necessary. In this example

 * 		// the condition as simple as possible.

 *		CMdELogicCondition* condition = CMdELogicCondition::NewL( ELogicConditionOperatorAnd );

 *		iMdeSession->AddObjectObserverL( *this, condition, ENotifyRemove, 

 *   		&iMdeSession->GetDefaultNamespaceDefL() );

 * 

 * 		// Start listening to changes in object present status.

 * 		iMdeSession->AddObjectPresentObserverL( *this );

 * }

 * 

 * @see MMdEObjectObserver::HandleObjectNotification

 * void CMdeObserverExample::HandleObjectNotification(CMdESession& aSession, TObserverNotificationType aType,

 *						const RArray<TItemId>& aObjectIdArray)

 * {

 *	 	if ( aType == ENotifyAdd )

 * 		{	

 * 		// object was added to DB

 * 		} else if ( aType == ENotifyModify )

 * 		{

 * 		// object was modified

 * 		} else if ( aType == ENotifyRemove )

 * 		{

 * 		// object was removed from DB

 * 		}

 * 

 * 		// aObjectIdArray contains ids for all objects that were added/modified/removed

 * }

 * 

 * void CMdeObserverExample::HandleObjectPresentNotification(CMdESession& aSession, 

 *			TBool aPresent, const RArray<TItemId>& aObjectIdArray)

 *	{

 * 		if ( aPresent )

 * 		{

 * 			// objects in aObjectIdArray were set as present

 * 		}

 *  }

 */

class MMdEObjectObserver

	{

public:

	/**

	 * Called to notify the observer that new objects has been

	 * added/modified/removed in the metadata engine database.

	 * 

	 * @param aSession session

	 * @param aType defines if object was added/modified/remove

	 * @param aObjectIdArray IDs of added object

	 * @see CMdESession::AddObjectObserverL

	 * @see CMdELogicCondition

	 */

	virtual void HandleObjectNotification(CMdESession& aSession, 

						TObserverNotificationType aType,

						const RArray<TItemId>& aObjectIdArray) = 0;

    };

class MMdEObjectObserverWithUri

    {

public:

    /**

     * Called to notify the observer that new objects has been

     * added/modified/removed in the metadata engine database.

     * 

     * @param aSession session

     * @param aType defines if object was added/modified/remove

     * @param aObjectIdArray IDs of added object

     * @param aUriArray Uris of added object

     * @see CMdESession::AddObjectObserverL

     * @see CMdELogicCondition

     */

    virtual void HandleUriObjectNotification(CMdESession& aSession, 

                        TObserverNotificationType aType,

                        const RArray<TItemId>& aObjectIdArray,

                        const RPointerArray<HBufC>& aObjectUriArray) = 0;

    };

/**

 * Observer interface for modifications of the objects in the metadata engine 

 * database.

 */

class MMdEObjectPresentObserver

	{

public:

	/**

	 * Called to notify the observer that objects has been set

	 * to present or not present state in the metadata engine database.

	 *

	 * @param aSession session

	 * @param aPresent state: ETrue - present or  EFales - not present

	 * @param aObjectIdArray object IDs which are set to present state

	 */

	virtual void HandleObjectPresentNotification(CMdESession& aSession, 

			TBool aPresent, const RArray<TItemId>& aObjectIdArray) = 0;

    };

/**

 * Observer interface for modifications of the relations in the metadata 

 * engine database.

 */

class MMdERelationPresentObserver

	{

public:

	/**

	 * Called to notify the observer that objects has been set

	 * to present or not present state in the metadata engine database.

	 *

	 * @param aSession session

	 * @param aPresent state: ETrue - present or  EFales - not present

	 * @param aObjectIdArray object IDs which are set to present state

	 */

	virtual void HandleRelationPresentNotification(CMdESession& aSession,

			TBool aPresent, const RArray<TItemId>& aRelationIdArray) = 0;

    };

/**

 * Observer interface for modifications of relations in the metadata engine 

 * database. This observer returns only relations IDs.

 */

class MMdERelationObserver

	{

public:

	/**

	 * Called to notify the observer that new relations has been

	 * added/modified/removed in the metadata engine database.

	 *

	 * @param aSession session

	 * @param aType defines if relation was added/modified/remove

	 * @param aRelationIdArray IDs of relations

	 */

	virtual void HandleRelationNotification(CMdESession& aSession, 

			TObserverNotificationType aType,

			const RArray<TItemId>& aRelationIdArray) = 0;

    };

/**

 * Observer interface for modifications of relations in the metadata engine 

 * database. This observer returns relations (not only IDs).

 */

class MMdERelationItemObserver

	{

public:

	/**

	 * Called to notify the observer that new relations has been

	 * added/modified/removed in the metadata engine database.

	 *

	 * @param aSession session

	 * @param aType if relation was added/modified/remove

	 * @param aRelationArray relations

	 */

	virtual void HandleRelationItemNotification(CMdESession& aSession, 

			TObserverNotificationType aType,

			const RArray<TMdERelation>& aRelationArray) = 0;

    };

/**

 * Observer interface for additions or removes of new events to the metadata 

 * engine database.

 */

class MMdEEventObserver

	{

public:

	/**

	 * Called to notify the observer that new events has been

	 * added or removed in the metadata engine database.

	 *

	 * @param aSession session

	 * @param aType if event was added or removed

	 * @param aEventIdArray IDs of added events

	 */

	virtual void HandleEventNotification(CMdESession& aSession, 

			TObserverNotificationType aType,

			const RArray<TItemId>& aEventIdArray) = 0;

    };

/**

 * Metadata engine session.

 */

NONSHARABLE_CLASS(CMdESession) : public CBase

	{

public:

	/* Constructors and destructor. */

	/**

	 * Opens a new metadata engine session.

	 *

	 * @param aObserver observer to notify when opening the session has been 

	 *                  completed

	 *

	 * @return metadata engine session

	 */

	IMPORT_C static CMdESession* NewL(MMdESessionObserver& aObserver);

	/**

	 * Opens a new metadata engine session and leaves the session in the 

	 * cleanup stack.

	 *

	 * @param aObserver observer to notify when opening the session has been 

	 *                  completed

     *

	 * @return  metadata engine session

	 */

	IMPORT_C static CMdESession* NewLC(MMdESessionObserver& aObserver);

	/**

	 * Destructor.

	 */

	virtual ~CMdESession();

	/* Methods for managing namespace definitions. */

	/**

	 * Returns the number of namespace definitions.

	 *

	 * @return number of namespace definitions

	 */

	virtual TInt NamespaceDefCount() const = 0;

	/**

	 * Returns the namespace definition at the specified index.

	 *

	 * @param aIndex index

	 *

	 * @return namespace definition

	 */

	virtual CMdENamespaceDef& NamespaceDefL(TInt aIndex) = 0;

	/**

	 * Returns the namespace definition with the specified name.

	 *

	 * @param aName name

	 *

	 * @return namespace definition; or 0, if there is no object definition

	 *         with the specified name

	 */

	virtual CMdENamespaceDef& GetNamespaceDefL(const TDesC& aName) = 0;

	 /* Returns the default namespace definition.

	 *

	 * @return  the default namespace definition.

	 */

	virtual CMdENamespaceDef& GetDefaultNamespaceDefL() = 0;

	/**

	 * Adds a new relation definition to namespace,

	 *

	 * Example:

	 *  void AddRelationL()

	 *  {

	 *    _LIT( TestRelation, "TestRelation" );

	 *    TBuf <15> relname( TestRelation );

	 * 	  iMdeSession->AddRelationDefL( *iDefaultNamespaceDef, relname );

	 *  }

	 * 

	 * @param aNamespaceDef namespace definition to which relation belongs

	 * @param aName         relation definitions name

	 */

	virtual void AddRelationDefL(const CMdENamespaceDef &aNamespaceDef, 

			const TDesC &aName) = 0;

	/**

	 * Adds a new event definition to namespace.

	 * 

	 * Example:

	 *  void AddEventDefL()

	 *  {

	 *    _LIT( TestEvent, "TestEvent" );

	 *    TBuf <10> eventName( TestEvent );

	 * 	  iMdeSession->AddRelationDefL( *iDefaultNamespaceDef, eventName );

	 *  }

	 *

	 * @param aNamespaceDef namespace definition to which event belongs

	 * @param aName         event definitions name

	 */

	virtual void AddEventDefL(const CMdENamespaceDef &aNamespaceDef, 

			const TDesC &aName) = 0;

	/* Methods for managing objects. */

    /**

     * Adds multiple instance items to metadata database.

     * The array contains the items, any other type than object, relation or 

     * event causes a leave.

	 *

     * @param aItems list of items to add

     * @return first item error

     */

	virtual TInt AddItemsL( RPointerArray<CMdEInstanceItem>& aItems ) = 0;

    /**

     * Commits multiple instance items to metadata database.

     * The array contains the items, any other type than object, relation or 

     * event causes a leave.

     * 

     * @param aItems list of items to add

     * @return first item error

     */

	virtual TInt UpdateItemsL( RPointerArray<CMdEInstanceItem>& aItems ) = 0;

   /**

     * Adds multiple instance items asynchronously to metadata database.

     * The array contains the items, any other type than object, relation or 

     * event causes a leave. Returned serialized list of item IDs must be 

     * deserialized with DeserializeItemsL method.

     * 

     * Example:

     *  class CExampleActiveObject : public CActive

     *  {

     *    void CActiveObject::AddItemsL();

     *    ...

     *    RPointerArray<CMdEInstanceItem> iItems;

     *    RMdEDataBuffer iResultBuffer;

     *  };

     * 

     *  void CExampleActiveObject::AddItemsL()

     *  {

     *    iMdeSession->AddItemsAsyncL( iItems, iStatus, iResultBuffer );

     *    SetActive();

     *  }

     * 

     * When adding items is finished, RunL() will be called.

     * 

     * @param aItems List of item to add.

     * @param aStatus Returns the result code after the asynchronous call 

     *                completes.

     * @param aSerializedItemIds Returned serialized list of item IDs.

     */

	virtual void AddItemsAsyncL( 

			RPointerArray<CMdEInstanceItem>& aItems, 

			TRequestStatus& aStatus,

			RMdEDataBuffer& aSerializedItemIds) = 0;

   /**

     * Commits multiple instance items asynchronously to metadata database.

     * The array contains the items, any other type than object, relation or 

     * event causes a leave. Returned serialized list of item IDs must be 

     * deserialized with DeserializeItemsL method.

     * 

     * Example:

     *  class CExampleActiveObject : public CActive

     *   {

     *     void CActiveObject::UpdateItemsL();

     *     ...

     *     RPointerArray<CMdEInstanceItem> iItems;

     *     RMdEDataBuffer iResultBuffer;

     *   };

     * 

     *   void CExampleActiveObject::UpdateItemsL()

     *   {

     *     iMdeSession->UpdateItemsAsyncL( iItems, iStatus, iResultBuffer );

     *     SetActive();

     *   }

     *