1 /*

     2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Metadata engine client session

    15 *

    16 */

    17 

    18 

    19 #ifndef __MDESESSION_H__

    20 #define __MDESESSION_H__

    21 

    22 

    23 #include <e32base.h>

    24 #include <badesca.h>

    25 

    26 #include <mdccommon.h>

    27 

    28 

    29 /* Forward declarations. */

    30 class CMdESession;

    31 class CMdEObjectDef;

    32 class CMdERelationDef;

    33 class CMdEEventDef;

    34 class CMdEObject;

    35 class TMdEObject;

    36 class CMdERelation;

    37 class TMdERelation;

    38 class CMdEEvent;

    39 class CMdEObjectQuery;

    40 class CMdERelationQuery;

    41 class CMdEEventQuery;

    42 class CMdELogicCondition;

    43 class CMdEInstanceItem;

    44 class RMdEEngineSession;

    45 class MMdEQueryObserver;

    46 class CMdENamespaceDef;

    47 class RMdEDataBuffer;

    48 class CMdECondition;

    49 

    50 

    51 

    52 /**

    53  * Observer interface for a metadata engine session.

    54  * 

    55  * 

    56  * 

    57  * Examples of MdE session usage:

    58  * 

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

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

    61  * 

    62  * class CMdESessionExample : public MMdESessionObserver

    63  * {

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

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

    66  * 		...

    67  * 

    68  * 		CMdESession* iMdeSession;

    69  * };

    70  * 

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

    72  * 

    73  * void CMdESessionExample::OpenSession()

    74  * {

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

    76  * }

    77  * 

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

    79  *	{

    80  *		if ( KErrNone != aError ) {

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

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

    83  * 

    84  * 			delete iMdeSession; iMdeSession = NULL;

    85  * 			return;

    86  * 		}

    87  * 		

    88  * 		// The session was opened successfully.

    89  * 		...

    90  *	}

    91  * 

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

    93  * {

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

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

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

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

    98  * 

    99  * 		delete iMdeSession; iMdeSession = NULL;

   100  * }

   101  */

   102 class MMdESessionObserver

   103 	{

   104 public:

   105 

   106 	/**

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

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

   109 	 *

   110 	 * @param aSession session

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

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

   113 	 *                 session failed

   114 	 */

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

   116 

   117 	/**

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

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

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

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

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

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

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

   125 	 *

   126 	 * @param aSession session

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

   128 	 */

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

   130     };

   131 

   132 

   133 /**

   134  * Observer interface for modifications of the metadata engine schema.

   135  */

   136 class MMdESchemaObserver

   137 	{

   138 public:

   139 

   140 	/**

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

   142 	 *

   143 	 * @param none

   144 	 */

   145 	virtual void HandleSchemaModified() = 0;

   146     };

   147     

   148 /**

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

   150  * database.

   151  * 

   152  * Examples of observers.

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

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

   155  * relations and events works the same way.

   156  * 

   157  * class CMdeObserverExample : public MMdEObjectObserver, public MMdEObjectPresentObserver

   158  * {

   159  *		void HandleObjectNotification(CMdESession& aSession, TObserverNotificationType aType,

   160  *						const RArray<TItemId>& aObjectIdArray);

   161  *		void HandleObjectPresentNotification(CMdESession& aSession, TBool aPresent,

   162  *		 				const RArray<TItemId>& aObjectIdArray);

   163  * 		...

   164  * 		CMdESession* iMdeSession;

   165  * };

   166  * 

   167  * void CMdeObserverExample::ConstructL()

   168  * {

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

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

   171  * 		// the condition as simple as possible.

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

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

   174  *   		&iMdeSession->GetDefaultNamespaceDefL() );

   175  * 

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

   177  * 		iMdeSession->AddObjectPresentObserverL( *this );

   178  * }

   179  * 

   180  * @see MMdEObjectObserver::HandleObjectNotification

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

   182  *						const RArray<TItemId>& aObjectIdArray)

   183  * {

   184  *	 	if ( aType == ENotifyAdd )

   185  * 		{	

   186  * 		// object was added to DB

   187  * 		} else if ( aType == ENotifyModify )

   188  * 		{

   189  * 		// object was modified

   190  * 		} else if ( aType == ENotifyRemove )

   191  * 		{

   192  * 		// object was removed from DB

   193  * 		}

   194  * 

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

   196  * }

   197  * 

   198  * void CMdeObserverExample::HandleObjectPresentNotification(CMdESession& aSession, 

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

   200  *	{

   201  * 		if ( aPresent )

   202  * 		{

   203  * 			// objects in aObjectIdArray were set as present

   204  * 		}

   205  *  }

   206  */

   207 class MMdEObjectObserver

   208 	{

   209 public:

   210 

   211 	/**

   212 	 * Called to notify the observer that new objects has been

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

   214 	 * 

   215 	 * @param aSession session

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

   217 	 * @param aObjectIdArray IDs of added object

   218 	 * @see CMdESession::AddObjectObserverL

   219 	 * @see CMdELogicCondition

   220 	 */

   221 	virtual void HandleObjectNotification(CMdESession& aSession, 

   222 						TObserverNotificationType aType,

   223 						const RArray<TItemId>& aObjectIdArray) = 0;

   224     };

   225 

   226 class MMdEObjectObserverWithUri

   227     {

   228 public:

   229 

   230     /**

   231      * Called to notify the observer that new objects has been

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

   233      * 

   234      * @param aSession session

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

   236      * @param aObjectIdArray IDs of added object

   237      * @param aUriArray Uris of added object

   238      * @see CMdESession::AddObjectObserverL

   239      * @see CMdELogicCondition

   240      */

   241     virtual void HandleUriObjectNotification(CMdESession& aSession, 

   242                         TObserverNotificationType aType,

   243                         const RArray<TItemId>& aObjectIdArray,

   244                         const RPointerArray<HBufC>& aObjectUriArray) = 0;

   245     };

   246     

   247 /**

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

   249  * database.

   250  */

   251 class MMdEObjectPresentObserver

   252 	{

   253 public:

   254 

   255 	/**

   256 	 * Called to notify the observer that objects has been set

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

   258 	 *

   259 	 * @param aSession session

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

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

   262 	 */

   263 	virtual void HandleObjectPresentNotification(CMdESession& aSession, 

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

   265     };

   266 

   267 /**

   268  * Observer interface for modifications of the relations in the metadata 

   269  * engine database.

   270  */

   271 class MMdERelationPresentObserver

   272 	{

   273 public:

   274 

   275 	/**

   276 	 * Called to notify the observer that objects has been set

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

   278 	 *

   279 	 * @param aSession session

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

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

   282 	 */

   283 	virtual void HandleRelationPresentNotification(CMdESession& aSession,

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

   285     };

   286 

   287 

   288 /**

   289  * Observer interface for modifications of relations in the metadata engine 

   290  * database. This observer returns only relations IDs.

   291  */

   292 class MMdERelationObserver

   293 	{

   294 public:

   295 

   296 	/**

   297 	 * Called to notify the observer that new relations has been

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

   299 	 *

   300 	 * @param aSession session

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

   302 	 * @param aRelationIdArray IDs of relations

   303 	 */

   304 	virtual void HandleRelationNotification(CMdESession& aSession, 

   305 			TObserverNotificationType aType,

   306 			const RArray<TItemId>& aRelationIdArray) = 0;

   307     };

   308 

   309 /**

   310  * Observer interface for modifications of relations in the metadata engine 

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

   312  */

   313 class MMdERelationItemObserver

   314 	{

   315 public:

   316 

   317 	/**

   318 	 * Called to notify the observer that new relations has been

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

   320 	 *

   321 	 * @param aSession session

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

   323 	 * @param aRelationArray relations

   324 	 */

   325 	virtual void HandleRelationItemNotification(CMdESession& aSession, 

   326 			TObserverNotificationType aType,

   327 			const RArray<TMdERelation>& aRelationArray) = 0;

   328     };

   329 

   330 /**

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

   332  * engine database.

   333  */

   334 class MMdEEventObserver

   335 	{

   336 public:

   337 

   338 	/**

   339 	 * Called to notify the observer that new events has been

   340 	 * added or removed in the metadata engine database.

   341 	 *

   342 	 * @param aSession session

   343 	 * @param aType if event was added or removed

   344 	 * @param aEventIdArray IDs of added events

   345 	 */

   346 	virtual void HandleEventNotification(CMdESession& aSession, 

   347 			TObserverNotificationType aType,

   348 			const RArray<TItemId>& aEventIdArray) = 0;

   349 

   350     };

   351 

   352 /**

   353  * Metadata engine session.

   354  */

   355 NONSHARABLE_CLASS(CMdESession) : public CBase

   356 	{

   357 public:

   358 

   359 	/* Constructors and destructor. */

   360 

   361 	/**

   362 	 * Opens a new metadata engine session.

   363 	 *

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

   365 	 *                  completed

   366 	 *

   367 	 * @return metadata engine session

   368 	 */

   369 	IMPORT_C static CMdESession* NewL(MMdESessionObserver& aObserver);

   370 

   371 	/**

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

   373 	 * cleanup stack.

   374 	 *

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

   376 	 *                  completed

   377      *

   378 	 * @return  metadata engine session

   379 	 */

   380 	IMPORT_C static CMdESession* NewLC(MMdESessionObserver& aObserver);

   381 

   382 	/**

   383 	 * Destructor.

   384 	 */

   385 	virtual ~CMdESession();

   386 

   387 	/* Methods for managing namespace definitions. */

   388 

   389 	/**

   390 	 * Returns the number of namespace definitions.

   391 	 *

   392 	 * @return number of namespace definitions

   393 	 */

   394 	virtual TInt NamespaceDefCount() const = 0;

   395 

   396 	/**

   397 	 * Returns the namespace definition at the specified index.

   398 	 *

   399 	 * @param aIndex index

   400 	 *

   401 	 * @return namespace definition

   402 	 */

   403 	virtual CMdENamespaceDef& NamespaceDefL(TInt aIndex) = 0;

   404 

   405 	/**

   406 	 * Returns the namespace definition with the specified name.

   407 	 *

   408 	 * @param aName name

   409 	 *

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

   411 	 *         with the specified name

   412 	 */

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

   414 

   415 	 /* Returns the default namespace definition.

   416 	 *

   417 	 * @return  the default namespace definition.

   418 	 */

   419 	virtual CMdENamespaceDef& GetDefaultNamespaceDefL() = 0;

   420 

   421 	/**

   422 	 * Adds a new relation definition to namespace,

   423 	 *

   424 	 * Example:

   425 	 *  void AddRelationL()

   426 	 *  {

   427 	 *    _LIT( TestRelation, "TestRelation" );

   428 	 *    TBuf <15> relname( TestRelation );

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

   430 	 *  }

   431 	 * 

   432 	 * @param aNamespaceDef namespace definition to which relation belongs

   433 	 * @param aName         relation definitions name

   434 	 */

   435 	virtual void AddRelationDefL(const CMdENamespaceDef &aNamespaceDef, 

   436 			const TDesC &aName) = 0;

   437 

   438 	/**

   439 	 * Adds a new event definition to namespace.

   440 	 * 

   441 	 * Example:

   442 	 *  void AddEventDefL()

   443 	 *  {

   444 	 *    _LIT( TestEvent, "TestEvent" );

   445 	 *    TBuf <10> eventName( TestEvent );

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

   447 	 *  }

   448 	 *

   449 	 * @param aNamespaceDef namespace definition to which event belongs

   450 	 * @param aName         event definitions name

   451 	 */

   452 	virtual void AddEventDefL(const CMdENamespaceDef &aNamespaceDef, 

   453 			const TDesC &aName) = 0;

   454 

   455 	/* Methods for managing objects. */

   456 

   457     /**

   458      * Adds multiple instance items to metadata database.

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

   460      * event causes a leave.

   461 	 *

   462      * @param aItems list of items to add

   463      * @return first item error

   464      */

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

   466 

   467     /**

   468      * Commits multiple instance items to metadata database.

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

   470      * event causes a leave.

   471      * 

   472      * @param aItems list of items to add

   473      * @return first item error

   474      */

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

   476 

   477    /**

   478      * Adds multiple instance items asynchronously to metadata database.

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

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

   481      * deserialized with DeserializeItemsL method.

   482      * 

   483      * Example:

   484      *  class CExampleActiveObject : public CActive

   485      *  {

   486      *    void CActiveObject::AddItemsL();

   487      *    ...

   488      *    RPointerArray<CMdEInstanceItem> iItems;

   489      *    RMdEDataBuffer iResultBuffer;

   490      *  };

   491      * 

   492      *  void CExampleActiveObject::AddItemsL()

   493      *  {

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

   495      *    SetActive();

   496      *  }

   497      * 

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

   499      * 

   500      * @param aItems List of item to add.

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

   502      *                completes.

   503      * @param aSerializedItemIds Returned serialized list of item IDs.

   504      */

   505 	virtual void AddItemsAsyncL( 

   506 			RPointerArray<CMdEInstanceItem>& aItems, 

   507 			TRequestStatus& aStatus,

   508 			RMdEDataBuffer& aSerializedItemIds) = 0;

   509 

   510    /**

   511      * Commits multiple instance items asynchronously to metadata database.

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

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

   514      * deserialized with DeserializeItemsL method.

   515      * 

   516      * Example:

   517      *  class CExampleActiveObject : public CActive

   518      *   {

   519      *     void CActiveObject::UpdateItemsL();

   520      *     ...

   521      *     RPointerArray<CMdEInstanceItem> iItems;

   522      *     RMdEDataBuffer iResultBuffer;

   523      *   };

   524      * 

   525      *   void CExampleActiveObject::UpdateItemsL()

   526      *   {

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

   528      *     SetActive();

   529      *   }

   530      * 

   531      * @param aItems List of item to add.

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

   533      *                completes.

   534      * @param aSerializedItemIds Returned serialized list of item IDs.

   535      */

   536 	virtual void UpdateItemsAsyncL( 

   537 			RPointerArray<CMdEInstanceItem>& aItems, 

   538 			TRequestStatus& aStatus,

   539 			RMdEDataBuffer& aSerializedItemIds ) = 0;

   540 

   541 	/**

   542 	 * Constructs a new empty object. Note that the object is not inserted in 

   543 	 * the database. The ownership of the new object is passed to the caller 

   544 	 * (that is, the caller is responsible for deleting the object).

   545 	 *

   546 	 * Example:

   547 	 *  _LIT( KObjectDef, "ObjectDefName" );

   548 	 *  TBuf<13> objDefStr( KObjectDef );

   549 	 *  CMdENamespaceDef& defNS = iMdESession->GetDefaultNamespaceDefL();

   550 	 *	CMdEObjectDef& mdeObjectDef = defNS.GetObjectDefL( objDefStr );

   551 	 *  CMdEObject* mdeObject = iMdESession->NewObjectL( mdeObjectDef, aUri );

   552 	 * 

   553 	 * @param aDef definition of the new object

   554 	 * @param aUri URI of the new object

   555 	 * @param aMediaId media ID of the new object (default 0)

   556 	 *

   557 	 * @return new object

   558 	 */

   559 	virtual CMdEObject* NewObjectL( CMdEObjectDef& aDef, const TDesC& aUri, 

   560                                     TUint32 aMediaId = 0 ) = 0;

   561 

   562 	/**

   563 	 * Constructs a new empty object and leaves it in the cleanup stack. 

   564 	 * Note that the object is not inserted in the database. The ownership of 

   565 	 * the new object is passed to the caller (that is, the caller is 

   566 	 * responsible for deleting the object).

   567 	 * 

   568  	 * Example:

   569 	 *  _LIT( KObjectDef, "ObjectDefName" );

   570 	 *  TBuf<13> objDefStr( KObjectDef );

   571 	 *  CMdENamespaceDef& defNS = iMdESession->GetDefaultNamespaceDefL();

   572 	 *	CMdEObjectDef& mdeObjectDef = defNS.GetObjectDefL( objDefStr );

   573 	 *  CMdEObject* mdeObject = iMdESession->NewObjectLC( mdeObjectDef, aUri );

   574 	 *

   575 	 * @param aDef definition of the new object

   576 	 * @param aUri URI of the new object

   577 	 * @param aMediaId media ID of the new object (default 0)

   578 	 *

   579 	 * @return new object

   580 	 */

   581 	virtual CMdEObject* NewObjectLC( CMdEObjectDef& aDef, const TDesC& aUri, 

   582                                      TUint32 aMediaId = 0 ) = 0;

   583 

   584     /**

   585      * Adds the specified new object to metadata database.

   586      * aObject is modified so that it has the new item ID.

   587      * If object adding fails object's ID is KNoId, 

   588      * otherwise object adding is successful.

   589      *

   590      * @param aObject object to be added

   591      *

   592      * @return item ID of the added object

   593      */

   594     virtual TItemId AddObjectL(CMdEObject& aObject) = 0;

   595 

   596     /**

   597      * Adds multiple object items to the metadata engine database.

   598      * The array contains the object items. aObjects are modified 

   599      * so that those has the new item IDs. If object adding fails

   600      * object's ID is KNoId, otherwise object adding is successful.

   601      *

   602      * @param aObjects  list of objects to be added

   603      * @return first object error

   604      */

   605     virtual TInt AddObjectsL(RPointerArray<CMdEObject>& aObjects) = 0;

   606 

   607 	/**

   608 	 * Deserialize serialized list of item IDs

   609 	 *

   610 	 * @param aSerializedItemIds serialized list of item IDs

   611 	 * @param aResultObjects     if not NULL object IDs are deserialized from 

   612 	 *                           buffer to this ID array

   613 	 * @param aResultEvents      if not NULL event IDs are deserialized from 

   614 	 *                           buffer to this ID array

   615 	 * @param aResultRelations   if not NULL relation IDs are deserialized 

   616 	 *                           from buffer to this ID array

   617 	 *

   618 	 * @return error code of first failed item, if no errors KErrNone

   619 	 */

   620 	virtual TInt DeserializeIdsL( RMdEDataBuffer& aSerializedItemIds, 

   621 			RArray<TItemId>* aResultObjects = NULL, 

   622 			RArray<TItemId>* aResultEvents = NULL, 

   623 			RArray<TItemId>* aResultRelations = NULL ) = 0;

   624 						   

   625 	/**

   626 	 * Deserialize serialized list of items

   627 	 *

   628 	 * @param aSerializedItems serialized list of items

   629 	 * @param aItems items are deserialized from buffer to this item array

   630 	 *

   631 	 * @return first item error

   632 	 */

   633 	virtual TInt DeserializeItemsL( RMdEDataBuffer& aSerializedItems, 

   634 			RPointerArray<CMdEInstanceItem>& aItems ) = 0;

   635 

   636 	/**

   637 	 * Removes the object with the specified identifier from metadata database.

   638 	 *

   639 	 * @param aId identifier

   640 	 * @param aNamespaceDef namespace where object is removed, if NULL default 

   641 	 *                      namespace is used

   642 	 * @return KNoId if removing has failed, otherwise removed object's ID

   643 	 */

   644 	virtual TItemId RemoveObjectL( TItemId aId, 

   645 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   646 

   647 	/**

   648 	 * Removes the object with the specified URI from metadata database.

   649 	 *

   650 	 * @param aUri URI

   651 	 * @param aNamespaceDef namespace from remove object, if NULL default 

   652 	 *                      namespace is used

   653 	 * @return KNoId if removing has failed, otherwise removed object's ID

   654 	 */

   655 	virtual TItemId RemoveObjectL( const TDesC& aUri, 

   656 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   657 

   658 	/**

   659 	 * Removes the array of objects with the specified identifier from 

   660 	 * metadata database.

   661 	 *

   662 	 * @param aId object IDs to be removed

   663 	 * @param aResult result array where succefully removed object IDs are 

   664 	 *                added (KNoId is added from those objects which removing 

   665 	 *                has failed)

   666 	 * @param aNamespaceDef namespace where object is removed, if NULL default 

   667 	 *                      namespace is used

   668 	 * @return first item error

   669 	 */

   670 	virtual TInt RemoveObjectsL( 

   671 			const RArray<TItemId>& aId, RArray<TItemId>& aResult, 

   672 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   673 

   674 	/**

   675 	 * Removes the array of objects with the specified URI from metadata 

   676 	 * database.

   677 	 *

   678 	 * @param aUri object URIs to be removed

   679 	 * @param aResult result array where succefully removed object IDs are 

   680 	 *                added (KNoId is added from those objects which removing 

   681 	 *                has failed)

   682 	 * @param aNamespaceDef namespace where object is removed, if NULL default 

   683 	 *                      namespace is used

   684 	 * @return first item error

   685 	 */

   686 	virtual TInt RemoveObjectsL( 

   687 			const RPointerArray<TDesC>& aUri, RArray<TItemId>& aResult, 

   688 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   689 

   690 	/**

   691 	 * Asynchronously removes the array of objects with the specified 

   692 	 * object IDs from metadata database. Returned serialized list of item IDs 

   693 	 * must be deserialized with DeserializeIdsL method.

   694 	 *

   695 	 * @param aId object IDs to be removed

   696      * @param aStatus returns the result code after the asynchronous call 

   697      *                completes.

   698      * @param aSerializedObjectIds returned serialized list of object IDs

   699 	 * @param aNamespaceDef namespace where object is removed, if NULL default 

   700 	 *                      namespace is used

   701 	 */

   702 	virtual void RemoveObjectsAsyncL( 

   703 			const RArray<TItemId>& aId, TRequestStatus& aStatus, 

   704 			RMdEDataBuffer& aSerializedObjectIds, 

   705 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   706 

   707 	/**

   708 	 * Asynchronously removes the array of objects with the specified URI from 

   709 	 * metadata database. Returned serialized list of item IDs must be 

   710 	 * deserialized with DeserializeIdsL method.

   711 	 *

   712 	 * @param aUri object URIs to be removed

   713      * @param aStatus returns the result code after the asynchronous call 

   714      *                completes.

   715      * @param aSerializedObjectIds returned serialized list of object IDs

   716 	 * @param aNamespaceDef namespace where object is removed, if NULL default 

   717 	 *                      namespace is used

   718 	 */

   719 	virtual void RemoveObjectsAsyncL( 

   720 			const RPointerArray<TDesC>& aUri, TRequestStatus& aStatus, 

   721 			RMdEDataBuffer& aSerializedObjectIds, 

   722 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   723 	

   724 	/**

   725 	 * Returns the object with the specified ID and specified object 

   726 	 * definition.

   727 	 *

   728 	 * Example:

   729 	 *   CMdENamespaceDef& defaultNamespace = iSession->GetDefaultNamespaceDefL();

   730      * 	 CMdEObjectDef& imageObjDef = defaultNamespace.GetObjectDefL( MdeConstants::Image::KImageObject );

   731 	 * 	 CMdEObject* object = iSession->GetObjectL( aObjectId, imageObjDef );

   732 	 * 

   733 	 * @param aId object ID

   734 	 * @param aObjectDef object definition

   735 	 *

   736 	 * @return object or NULL, if there is no object with the specified 

   737 	 *         identifier in the metadata engine database

   738 	 */

   739 	virtual CMdEObject* GetObjectL( const TItemId aId, 

   740 			CMdEObjectDef& aObjectDef ) = 0;

   741 

   742 	/**

   743 	 * Returns the object (object may contain only properties defined in 

   744 	 * "Object") with the specified ID and specified namespace (if namespace 

   745 	 * is NULL, the default namespace is used).

   746 	 *

   747 	 * @param aId object ID

   748 	 * @param aNamespaceDef namespace

   749 	 *

   750 	 * @return  object or NULL, if there is no object with the specified 

   751 	 *          identifier in the metadata engine database

   752 	 */

   753 	virtual CMdEObject* GetObjectL( const TItemId aId, 

   754 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   755 

   756 	/**

   757 	 * Returns the object (object will contain all it's properties) 

   758 	 * with the specified ID and specified namespace 

   759 	 * (if namespace is NULL, the default namespace is used).

   760 	 *

   761 	 * @param aId object ID

   762 	 * @param aNamespaceDef namespace

   763 	 *

   764 	 * @return  object or NULL, if there is no object with the specified 

   765 	 *          identifier in the metadata engine database

   766 	 */

   767 	virtual CMdEObject* GetFullObjectL( const TItemId aId, 

   768 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   769 

   770 	/**

   771 	 * Returns the object with the specified GUID and specified object 

   772 	 * definition.

   773 	 * 

   774 	 * Example:

   775 	 *   CMdENamespaceDef& defaultNamespace = iSession->GetDefaultNamespaceDefL();

   776      * 	 CMdEObjectDef& imageObjDef = defaultNamespace.GetObjectDefL( MdeConstants::Image::KImageObject );

   777      *   CMdEObject* object = iMdeSession->GetObjectL( 12345, 67890, imageObjDef );

   778 	 *

   779 	 * @param aGuidHigh GUID high

   780 	 * @param aGuidLow GUID low

   781 	 * @param aObjectDef object definition

   782 	 *

   783 	 * @return  object or NULL, if there is no object with the specified 

   784 	 *          identifier in the metadata engine database

   785 	 */

   786 	virtual CMdEObject* GetObjectL( 

   787 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   788 			CMdEObjectDef& aObjectDef ) = 0;

   789 

   790 	/**

   791 	 * Returns the object (object may contain only properties definied in 

   792 	 * "Object") with the specified GUID and specified namespace (if namespace 

   793 	 * is NULL, the default namespace is used).

   794 	 *

   795 	 * Example:

   796      *   CMdEObject* object = iMdeSession->GetObjectL( 12345, 67890 );

   797 	 * 

   798 	 * @param aGuidHigh  GUID high

   799 	 * @param aGuidLow  GUID low

   800 	 * @param aNamespaceDef namespace

   801 	 *

   802 	 * @return  object or NULL, if there is no object with the specified 

   803 	 *          identifier in the metadata engine database

   804 	 */

   805 	virtual CMdEObject* GetObjectL( 

   806 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   807 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   808 

   809 	/**

   810 	 * Returns the object (object will contain all it's properties) 

   811 	 * with the specified GUID and specified namespace 

   812 	 * (if namespace is NULL, the default namespace is used).

   813 	 * 

   814 	 * Example:

   815      *   CMdEObject* object = iMdeSession->GetFullObjectL( 12345, 67890 );

   816 	 *

   817 	 * @param aGuidHigh GUID high

   818 	 * @param aGuidLow GUID low

   819 	 * @param aNamespaceDef namespace

   820 	 *

   821 	 * @return  object or NULL, if there is no object with the specified 

   822 	 *          identifier in the metadata engine database

   823 	 */

   824 	virtual CMdEObject* GetFullObjectL( 

   825 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   826 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   827 

   828 	/**

   829 	 * Returns the object with the specified URI and specified object 

   830 	 * definition.

   831 	 *

   832 	 * Example:

   833 	 *   CMdENamespaceDef& defaultNamespace = iSession->GetDefaultNamespaceDefL();

   834      * 	 CMdEObjectDef& imageObjDef = defaultNamespace.GetObjectDefL( MdeConstants::Image::KImageObject );

   835      *   CMdEObject* object = iMdeSession->GetObjectL( aUri, imageObjDef );

   836 	 *

   837 	 * @param aUri object URI

   838 	 * @param aObjectDef object definition

   839 	 *

   840 	 * @return  object or NULL, if there is no object with the specified 

   841 	 *          identifier in the metadata engine database

   842 	 */

   843 	virtual CMdEObject* GetObjectL( const TDesC& aUri, 

   844 			CMdEObjectDef& aObjectDef ) = 0;

   845 

   846 	/**

   847 	 * Returns the object (object may contain only properties definied in 

   848 	 * "Object") with the specified URI specified namespace (if namespace is 

   849 	 * NULL, the default namespace is used).

   850 	 *

   851 	 * @param aUri object URI

   852 	 * @param aNamespaceDef namespace

   853 	 *

   854 	 * @return  object or NULL, if there is no object with the specified 

   855 	 *          identifier in the metadata engine database

   856 	 */

   857 	virtual CMdEObject* GetObjectL( const TDesC& aUri, 

   858 			CMdENamespaceDef* aNamespaceDef = NULL) = 0;

   859 

   860 	/**

   861 	 * Returns the object (object will contain all it's properties) with the 

   862 	 * specified URI specified namespace (if namespace is NULL, the default 

   863 	 * namespace is used).

   864 	 *

   865 	 * @param aUri object URI

   866 	 * @param aNamespaceDef namespace

   867 	 *

   868 	 * @return  object or NULL, if there is no object with the specified 

   869 	 *          identifier in the metadata engine database

   870 	 */

   871 	virtual CMdEObject* GetFullObjectL( const TDesC& aUri, 

   872 			CMdENamespaceDef* aNamespaceDef = NULL) = 0;

   873 

   874 	/**

   875 	 * Opens the object with the specified ID and specified object 

   876 	 * definition for modifications. The object is locked so that nobody else 

   877 	 * can open it for modifications. The modifications are committed by 

   878 	 * calling the <code>CommitObject()</code> method, which releases the lock.

   879 	 * The modifications can be canceled by calling the 

   880 	 * <code>CancelObject()</code> method, which also releases the lock.

   881 	 *

   882 	 * Example:

   883 	 *  CMdENamespaceDef& defaultNamespace = iMdeSession->GetDefaultNamespaceDefL();

   884      *	CMdEObjectDef& imageDef = defaultNamespace.GetObjectDefL( MdeConstants::Image::KImageObject );

   885 	 *  CMdEObject* image = iMdESession->OpenObjectL( 17, imageDef );

   886 	 * 

   887 	 *  CMdEPropertyDef& lastModDatePropDef = imageDef.GetPropertyDefL(

   888      *   		Object::KLastModifiedDateProperty );

   889      * 

   890      *  CMdEProperty* lastModDateProp = NULL;

   891      *  image->Property( lastModDatePropDef, lastModDateProp, 0 );

   892      * 

   893      *  TTime currenttime( 0 );

   894      *	currenttime.UniversalTime();

   895      * 

   896      *  if ( lastModDateProp )

   897      *      {

   898      *      lastModDateProp->SetTimeValueL( currenttime );

   899      *      }

   900      *  else

   901      *      {

   902      *      image->AddTimePropertyL( lastModDatePropDef, currenttime );

   903      *      }

   904      *  }

   905      *  iMdeSession->CommitObjectL( *image );

   906 	 *  

   907 	 * 

   908 	 * @param aId  object ID

   909 	 * @param aObjectDef object definition

   910 	 *

   911 	 * @return  Object or NULL, if there is no object with the specified 

   912      *          identifier in the metadata engine database.

   913 	 */

   914 	virtual CMdEObject* OpenObjectL( const TItemId aId, 

   915 			CMdEObjectDef& aObjectDef ) = 0;

   916 

   917 	/**

   918 	 * Opens the object (object may contain only properties definied in "Object") 

   919 	 * with the specified ID and specified namespace 

   920 	 * (if namespace is NULL, the default namespace is used) for modifications.

   921 	 * The object is locked so that nobody else can open it for modifications.

   922 	 * The modifications are committed by calling the <code>CommitObject()</code>

   923 	 * method, which releases the lock. The modifications can be canceled by

   924 	 * calling the <code>CancelObject()</code> method, which also releases the

   925 	 * lock.

   926 	 *

   927 	 * @param aId  object ID.

   928 	 * @param aNamespaceDef namespace

   929 	 *

   930 	 * @return  Object or NULL, if there is no object with the specified 

   931      *          identifier in the metadata engine database.

   932 	 */

   933 	virtual CMdEObject* OpenObjectL( const TItemId aId, 

   934 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   935 

   936 	/**

   937 	 * Opens the object (object will contain all it's properties) 

   938 	 * with the specified ID and specified namespace 

   939 	 * (if namespace is NULL, the default namespace is used) for modifications.

   940 	 * The object is locked so that nobody else can open it for modifications.

   941 	 * The modifications are committed by calling the <code>CommitObject()</code>

   942 	 * method, which releases the lock. The modifications can be canceled by

   943 	 * calling the <code>CancelObject()</code> method, which also releases the

   944 	 * lock.

   945 	 *

   946 	 * @param aId  object ID.

   947 	 * @param aNamespaceDef namespace

   948 	 *

   949 	 * @return  Object or NULL, if there is no object with the specified 

   950      *          identifier in the metadata engine database.

   951 	 */

   952 	virtual CMdEObject* OpenFullObjectL( const TItemId aId, 

   953 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   954 

   955 

   956 	/**

   957 	 * Opens the object with the specified GUID and specified object 

   958 	 * definition for modifications. The object is locked so that nobody else 

   959 	 * can open it for modifications. The modifications are committed by 

   960 	 * calling the <code>CommitObject()</code> method, which releases the lock.

   961 	 * The modifications can be canceled by calling the 

   962 	 * <code>CancelObject()</code> method, which also releases the lock.

   963 	 *

   964 	 * @param aGuidHigh  GUID high

   965 	 * @param aGuidLow  GUID low

   966 	 * @param aObjectDef object definition

   967 	 *

   968 	 * @return  Object or NULL, if there is no object with the specified 

   969      *          identifier in the metadata engine database.

   970 	 */

   971 	virtual CMdEObject* OpenObjectL( 

   972 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   973 			CMdEObjectDef& aObjectDef ) = 0;

   974 

   975 	/**

   976 	 * Opens the object (object may contain only properties definied in "Object") 

   977 	 * with the specified GUID and specified namespace 

   978 	 * (if namespace is NULL, the default namespace is used) for modifications.

   979 	 * The object is locked so that nobody else can open it for modifications.

   980 	 * The modifications are committed by calling the <code>CommitObject()</code>

   981 	 * method, which releases the lock. The modifications can be canceled by

   982 	 * calling the <code>CancelObject()</code> method, which also releases the

   983 	 * lock.

   984 	 *

   985 	 * @param aGuidHigh  GUID high

   986 	 * @param aGuidLow  GUID low

   987 	 * @param aNamespaceDef namespace

   988 	 *

   989 	 * @return  Object or NULL, if there is no object with the specified 

   990      *          identifier in the metadata engine database.

   991 	 */

   992 	virtual CMdEObject* OpenObjectL( 

   993 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   994 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   995 

   996 	/**

   997 	 * Opens the object (object will contain all it's properties) 

   998 	 * with the specified GUID and specified namespace 

   999 	 * (if namespace is NULL, the default namespace is used) for modifications.

  1000 	 * The object is locked so that nobody else can open it for modifications.

  1001 	 * The modifications are committed by calling the <code>CommitObject()</code>

  1002 	 * method, which releases the lock. The modifications can be canceled by

  1003 	 * calling the <code>CancelObject()</code> method, which also releases the

  1004 	 * lock.

  1005 	 *

  1006 	 * @param aGuidHigh  GUID high

  1007 	 * @param aGuidLow  GUID low

  1008 	 * @param aNamespaceDef namespace

  1009 	 *

  1010 	 * @return  Object or NULL, if there is no object with the specified 

  1011      *          identifier in the metadata engine database.

  1012 	 */

  1013 	virtual CMdEObject* OpenFullObjectL( 

  1014 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

  1015 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1016 

  1017 

  1018 	/**

  1019 	 * Opens the object with the specified URI for modifications and specified 

  1020 	 * object definition. The object is locked so that nobody else can open it 

  1021 	 * for modifications. The modifications are committed by calling the 

  1022 	 * <code>CommitObject()</code> method, which releases the lock. The 

  1023 	 * modifications can be canceled by calling the <code>CancelObject()</code> 

  1024 	 * method, which also releases the lock.

  1025 	 *

  1026 	 * @param aUri  object URI

  1027 	 * @param aObjectDef object definition

  1028 	 *

  1029 	 * @return  Object or NULL, if there is no object with the specified 

  1030      *          identifier in the metadata engine database.

  1031 	 */

  1032 	virtual CMdEObject* OpenObjectL( const TDesC& aUri, 

  1033 			CMdEObjectDef& aObjectDef ) = 0;

  1034 

  1035 	/**

  1036 	 * Opens the object (object may contain only properties definied in "Object") 

  1037 	 * with the specified ID and specified namespace 

  1038 	 * (if namespace is NULL, the default namespace is used) for modifications.

  1039 	 * The object is locked so that nobody else can open it for modifications.

  1040 	 * The modifications are committed by calling the <code>CommitObject()</code>

  1041 	 * method, which releases the lock. The modifications can be canceled by

  1042 	 * calling the <code>CancelObject()</code> method, which also releases the

  1043 	 * lock.

  1044 	 *

  1045 	 * @param aUri  Object URI.

  1046 	 * @param aNamespaceDef namespace

  1047 	 *

  1048 	 * @return  Object or NULL, if there is no object with the specified 

  1049      *          identifier in the metadata engine database.

  1050 	 */

  1051 	virtual CMdEObject* OpenObjectL( const TDesC& aUri, 

  1052 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1053 

  1054 	/**

  1055 	 * Opens the object (object will contain all it's properties) 

  1056 	 * with the specified ID and specified namespace 

  1057 	 * (if namespace is NULL, the default namespace is used) for modifications.

  1058 	 * The object is locked so that nobody else can open it for modifications.

  1059 	 * The modifications are committed by calling the <code>CommitObject()</code>

  1060 	 * method, which releases the lock. The modifications can be canceled by

  1061 	 * calling the <code>CancelObject()</code> method, which also releases the

  1062 	 * lock.

  1063 	 *

  1064 	 * @param aUri  Object URI.

  1065 	 * @param aNamespaceDef namespace

  1066 	 *

  1067 	 * @return  Object or NULL, if there is no object with the specified 

  1068      *          identifier in the metadata engine database.

  1069 	 */

  1070 	virtual CMdEObject* OpenFullObjectL( const TDesC& aUri, 

  1071 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1072 

  1073 	/**

  1074 	 * Gets metadata object id, definition and some flags by URI. Does not return the whole object.

  1075 	 * 

  1076 	 * @param aObject on return contains information about the metadata object

  1077 	 * @param aUri metadata object URI

  1078 	 * @param aNamespaceDef namespace definition. If namespace is NULL then the default namespace is used.

  1079 	 */

  1080 	virtual void CheckObjectL( TMdEObject& aObject, const TDesC& aUri, 

  1081 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1082 

  1083 	/**

  1084 	 * Gets metadata object id, definition and some flags by id. Does not return the whole object.

  1085 	 * 

  1086 	 * @param aObject on return contains information about the metadata object

  1087 	 * @param aId metadata object id

  1088 	 * @param aNamespaceDef namespace definition. If namespace is NULL then the default namespace is used.

  1089 	 */

  1090 	virtual void CheckObjectL( TMdEObject& aObject, TItemId aId, 

  1091 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1092 

  1093 	/**

  1094 	 * Gets an array of TMdEObject objects that contain metadata object ids, definitions and 

  1095 	 * some flags by object ids. Does not return whole objects.

  1096 	 * 

  1097 	 * @param aObjects on return contains an array of objects containing information about metadata objects

  1098 	 * @param aIds array of metadata object ids

  1099 	 * @param aNamespaceDef namespace definition. If namespace is NULL then the default namespace is used.

  1100 	 */

  1101 	virtual void CheckObjectL( RArray<TMdEObject>& aObjects, 

  1102 			const RArray<TItemId>& aIds, 

  1103 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1104 	

  1105 	/**

  1106      * Commits the modifications made to the object to the database

  1107 	 * and releases the modification lock.

  1108      * 

  1109 	 * @param aObject  Object.

  1110      */

  1111     virtual void CommitObjectL(CMdEObject& aObject) = 0;

  1112 

  1113 	/**

  1114      * Commits the modifications made to objects to the database

  1115 	 * and releases the modification locks.

  1116      * 

  1117 	 * @param aObject  Object.

  1118      */

  1119     virtual void CommitObjectsL(RPointerArray<CMdEObject>& aObjects) = 0;

  1120 

  1121     /**

  1122      * Cancels the modifications made to the object and releases the

  1123 	 * modification lock.

  1124      * 

  1125 	 * @param aObject  Object.

  1126      */

  1127     virtual TItemId CancelObjectL(CMdEObject& aObject) = 0;

  1128 

  1129 

  1130 	/* Methods for managing relations. */

  1131 

  1132 	/**

  1133 	 * Returns the relation with the specified ID and specified namespace 

  1134 	 * (if namespace is NULL, the default namespace is used).