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 MMdEQueryObserver;

    45 class CMdENamespaceDef;

    46 class RMdEDataBuffer;

    47 class CMdECondition;

    48 

    49 

    50 

    51 /**

    52  * Observer interface for a metadata engine session.

    53  * 

    54  * 

    55  * 

    56  * Examples of MdE session usage:

    57  * 

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

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

    60  * 

    61  * class CMdESessionExample : public MMdESessionObserver

    62  * {

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

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

    65  * 		...

    66  * 

    67  * 		CMdESession* iMdeSession;

    68  * };

    69  * 

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

    71  * 

    72  * void CMdESessionExample::OpenSession()

    73  * {

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

    75  * }

    76  * 

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

    78  *	{

    79  *		if ( KErrNone != aError ) {

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

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

    82  * 

    83  * 			delete iMdeSession; iMdeSession = NULL;

    84  * 			return;

    85  * 		}

    86  * 		

    87  * 		// The session was opened successfully.

    88  * 		...

    89  *	}

    90  * 

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

    92  * {

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

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

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

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

    97  * 

    98  * 		delete iMdeSession; iMdeSession = NULL;

    99  * }

   100  */

   101 class MMdESessionObserver

   102 	{

   103 public:

   104 

   105 	/**

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

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

   108 	 *

   109 	 * @param aSession session

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

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

   112 	 *                 session failed

   113 	 */

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

   115 

   116 	/**

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

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

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

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

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

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

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

   124 	 *

   125 	 * @param aSession session

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

   127 	 */

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

   129     };

   130 

   131 

   132 /**

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

   134  */

   135 class MMdESchemaObserver

   136 	{

   137 public:

   138 

   139 	/**

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

   141 	 *

   142 	 * @param none

   143 	 */

   144 	virtual void HandleSchemaModified() = 0;

   145     };

   146     

   147 /**

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

   149  * database.

   150  * 

   151  * Examples of observers.

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

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

   154  * relations and events works the same way.

   155  * 

   156  * class CMdeObserverExample : public MMdEObjectObserver, public MMdEObjectPresentObserver

   157  * {

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

   159  *						const RArray<TItemId>& aObjectIdArray);

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

   161  *		 				const RArray<TItemId>& aObjectIdArray);

   162  * 		...

   163  * 		CMdESession* iMdeSession;

   164  * };

   165  * 

   166  * void CMdeObserverExample::ConstructL()

   167  * {

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

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

   170  * 		// the condition as simple as possible.

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

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

   173  *   		&iMdeSession->GetDefaultNamespaceDefL() );

   174  * 

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

   176  * 		iMdeSession->AddObjectPresentObserverL( *this );

   177  * }

   178  * 

   179  * @see MMdEObjectObserver::HandleObjectNotification

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

   181  *						const RArray<TItemId>& aObjectIdArray)

   182  * {

   183  *	 	if ( aType == ENotifyAdd )

   184  * 		{	

   185  * 		// object was added to DB

   186  * 		} else if ( aType == ENotifyModify )

   187  * 		{

   188  * 		// object was modified

   189  * 		} else if ( aType == ENotifyRemove )

   190  * 		{

   191  * 		// object was removed from DB

   192  * 		}

   193  * 

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

   195  * }

   196  * 

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

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

   199  *	{

   200  * 		if ( aPresent )

   201  * 		{

   202  * 			// objects in aObjectIdArray were set as present

   203  * 		}

   204  *  }

   205  */

   206 class MMdEObjectObserver

   207 	{

   208 public:

   209 

   210 	/**

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

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

   213 	 * 

   214 	 * @param aSession session

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

   216 	 * @param aObjectIdArray IDs of added object

   217 	 * @see CMdESession::AddObjectObserverL

   218 	 * @see CMdELogicCondition

   219 	 */

   220 	virtual void HandleObjectNotification(CMdESession& aSession, 

   221 						TObserverNotificationType aType,

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

   223     };

   224 

   225 class MMdEObjectObserverWithUri

   226     {

   227 public:

   228 

   229     /**

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

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

   232      * 

   233      * @param aSession session

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

   235      * @param aObjectIdArray IDs of added object

   236      * @param aUriArray Uris of added object

   237      * @see CMdESession::AddObjectObserverL

   238      * @see CMdELogicCondition

   239      */

   240     virtual void HandleUriObjectNotification(CMdESession& aSession, 

   241                         TObserverNotificationType aType,

   242                         const RArray<TItemId>& aObjectIdArray,

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

   244     };

   245     

   246 /**

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

   248  * database.

   249  */

   250 class MMdEObjectPresentObserver

   251 	{

   252 public:

   253 

   254 	/**

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

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

   257 	 *

   258 	 * @param aSession session

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

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

   261 	 */

   262 	virtual void HandleObjectPresentNotification(CMdESession& aSession, 

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

   264     };

   265 

   266 /**

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

   268  * engine database.

   269  */

   270 class MMdERelationPresentObserver

   271 	{

   272 public:

   273 

   274 	/**

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

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

   277 	 *

   278 	 * @param aSession session

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

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

   281 	 */

   282 	virtual void HandleRelationPresentNotification(CMdESession& aSession,

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

   284     };

   285 

   286 

   287 /**

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

   289  * database. This observer returns only relations IDs.

   290  */

   291 class MMdERelationObserver

   292 	{

   293 public:

   294 

   295 	/**

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

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

   298 	 *

   299 	 * @param aSession session

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

   301 	 * @param aRelationIdArray IDs of relations

   302 	 */

   303 	virtual void HandleRelationNotification(CMdESession& aSession, 

   304 			TObserverNotificationType aType,

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

   306     };

   307 

   308 /**

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

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

   311  */

   312 class MMdERelationItemObserver

   313 	{

   314 public:

   315 

   316 	/**

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

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

   319 	 *

   320 	 * @param aSession session

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

   322 	 * @param aRelationArray relations

   323 	 */

   324 	virtual void HandleRelationItemNotification(CMdESession& aSession, 

   325 			TObserverNotificationType aType,

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

   327     };

   328 

   329 /**

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

   331  * engine database.

   332  */

   333 class MMdEEventObserver

   334 	{

   335 public:

   336 

   337 	/**

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

   339 	 * added or removed in the metadata engine database.

   340 	 *

   341 	 * @param aSession session

   342 	 * @param aType if event was added or removed

   343 	 * @param aEventIdArray IDs of added events

   344 	 */

   345 	virtual void HandleEventNotification(CMdESession& aSession, 

   346 			TObserverNotificationType aType,

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

   348 

   349     };

   350 

   351 /**

   352  * Metadata engine session.

   353  */

   354 NONSHARABLE_CLASS(CMdESession) : public CBase

   355 	{

   356 public:

   357 

   358 	/* Constructors and destructor. */

   359 

   360 	/**

   361 	 * Opens a new metadata engine session.

   362 	 *

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

   364 	 *                  completed

   365 	 *

   366 	 * @return metadata engine session

   367 	 */

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

   369 

   370 	/**

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

   372 	 * cleanup stack.

   373 	 *

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

   375 	 *                  completed

   376      *

   377 	 * @return  metadata engine session

   378 	 */

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

   380 

   381 	/**

   382 	 * Destructor.

   383 	 */

   384 	virtual ~CMdESession();

   385 

   386 	/* Methods for managing namespace definitions. */

   387 

   388 	/**

   389 	 * Returns the number of namespace definitions.

   390 	 *

   391 	 * @return number of namespace definitions

   392 	 */

   393 	virtual TInt NamespaceDefCount() const = 0;

   394 

   395 	/**

   396 	 * Returns the namespace definition at the specified index.

   397 	 *

   398 	 * @param aIndex index

   399 	 *

   400 	 * @return namespace definition

   401 	 */

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

   403 

   404 	/**

   405 	 * Returns the namespace definition with the specified name.

   406 	 *

   407 	 * @param aName name

   408 	 *

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

   410 	 *         with the specified name

   411 	 */

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

   413 

   414 	 /* Returns the default namespace definition.

   415 	 *

   416 	 * @return  the default namespace definition.

   417 	 */

   418 	virtual CMdENamespaceDef& GetDefaultNamespaceDefL() = 0;

   419 

   420 	/**

   421 	 * Adds a new relation definition to namespace,

   422 	 *

   423 	 * Example:

   424 	 *  void AddRelationL()

   425 	 *  {

   426 	 *    _LIT( TestRelation, "TestRelation" );

   427 	 *    TBuf <15> relname( TestRelation );

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

   429 	 *  }

   430 	 * 

   431 	 * @param aNamespaceDef namespace definition to which relation belongs

   432 	 * @param aName         relation definitions name

   433 	 */

   434 	virtual void AddRelationDefL(const CMdENamespaceDef &aNamespaceDef, 

   435 			const TDesC &aName) = 0;

   436 

   437 	/**

   438 	 * Adds a new event definition to namespace.

   439 	 * 

   440 	 * Example:

   441 	 *  void AddEventDefL()

   442 	 *  {

   443 	 *    _LIT( TestEvent, "TestEvent" );

   444 	 *    TBuf <10> eventName( TestEvent );

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

   446 	 *  }

   447 	 *

   448 	 * @param aNamespaceDef namespace definition to which event belongs

   449 	 * @param aName         event definitions name

   450 	 */

   451 	virtual void AddEventDefL(const CMdENamespaceDef &aNamespaceDef, 

   452 			const TDesC &aName) = 0;

   453 

   454 	/* Methods for managing objects. */

   455 

   456     /**

   457      * Adds multiple instance items to metadata database.

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

   459      * event causes a leave.

   460 	 *

   461      * @param aItems list of items to add

   462      * @return first item error

   463      */

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

   465 

   466     /**

   467      * Commits multiple instance items to metadata database.

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

   469      * event causes a leave.

   470      * 

   471      * @param aItems list of items to add

   472      * @return first item error

   473      */

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

   475 

   476    /**

   477      * Adds multiple instance items asynchronously to metadata database.

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

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

   480      * deserialized with DeserializeItemsL method.

   481      * 

   482      * Example:

   483      *  class CExampleActiveObject : public CActive

   484      *  {

   485      *    void CActiveObject::AddItemsL();

   486      *    ...

   487      *    RPointerArray<CMdEInstanceItem> iItems;

   488      *    RMdEDataBuffer iResultBuffer;

   489      *  };

   490      * 

   491      *  void CExampleActiveObject::AddItemsL()

   492      *  {

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

   494      *    SetActive();

   495      *  }

   496      * 

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

   498      * 

   499      * @param aItems List of item to add.

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

   501      *                completes.

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

   503      */

   504 	virtual void AddItemsAsyncL( 

   505 			RPointerArray<CMdEInstanceItem>& aItems, 

   506 			TRequestStatus& aStatus,

   507 			RMdEDataBuffer& aSerializedItemIds) = 0;

   508 

   509    /**

   510      * Commits multiple instance items asynchronously to metadata database.

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

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

   513      * deserialized with DeserializeItemsL method.

   514      * 

   515      * Example:

   516      *  class CExampleActiveObject : public CActive

   517      *   {

   518      *     void CActiveObject::UpdateItemsL();

   519      *     ...

   520      *     RPointerArray<CMdEInstanceItem> iItems;

   521      *     RMdEDataBuffer iResultBuffer;

   522      *   };

   523      * 

   524      *   void CExampleActiveObject::UpdateItemsL()

   525      *   {

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

   527      *     SetActive();

   528      *   }

   529      * 

   530      * @param aItems List of item to add.

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

   532      *                completes.

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

   534      */

   535 	virtual void UpdateItemsAsyncL( 

   536 			RPointerArray<CMdEInstanceItem>& aItems, 

   537 			TRequestStatus& aStatus,

   538 			RMdEDataBuffer& aSerializedItemIds ) = 0;

   539 

   540 	/**

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

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

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

   544 	 *

   545 	 * Example:

   546 	 *  _LIT( KObjectDef, "ObjectDefName" );

   547 	 *  TBuf<13> objDefStr( KObjectDef );

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

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

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

   551 	 * 

   552 	 * @param aDef definition of the new object

   553 	 * @param aUri URI of the new object

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

   555 	 *

   556 	 * @return new object

   557 	 */

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

   559                                     TUint32 aMediaId = 0 ) = 0;

   560 

   561 	/**

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

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

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

   565 	 * responsible for deleting the object).

   566 	 * 

   567  	 * Example:

   568 	 *  _LIT( KObjectDef, "ObjectDefName" );

   569 	 *  TBuf<13> objDefStr( KObjectDef );

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

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

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

   573 	 *

   574 	 * @param aDef definition of the new object

   575 	 * @param aUri URI of the new object

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

   577 	 *

   578 	 * @return new object

   579 	 */

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

   581                                      TUint32 aMediaId = 0 ) = 0;

   582 

   583     /**

   584      * Adds the specified new object to metadata database.

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

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

   587      * otherwise object adding is successful.

   588      *

   589      * @param aObject object to be added

   590      *

   591      * @return item ID of the added object

   592      */

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

   594 

   595     /**

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

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

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

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

   600      *

   601      * @param aObjects  list of objects to be added

   602      * @return first object error

   603      */

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

   605 

   606 	/**

   607 	 * Deserialize serialized list of item IDs

   608 	 *

   609 	 * @param aSerializedItemIds serialized list of item IDs

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

   611 	 *                           buffer to this ID array

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

   613 	 *                           buffer to this ID array

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

   615 	 *                           from buffer to this ID array

   616 	 *

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

   618 	 */

   619 	virtual TInt DeserializeIdsL( RMdEDataBuffer& aSerializedItemIds, 

   620 			RArray<TItemId>* aResultObjects = NULL, 

   621 			RArray<TItemId>* aResultEvents = NULL, 

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

   623 						   

   624 	/**

   625 	 * Deserialize serialized list of items

   626 	 *

   627 	 * @param aSerializedItems serialized list of items

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

   629 	 *

   630 	 * @return first item error

   631 	 */

   632 	virtual TInt DeserializeItemsL( RMdEDataBuffer& aSerializedItems, 

   633 			RPointerArray<CMdEInstanceItem>& aItems ) = 0;

   634 

   635 	/**

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

   637 	 *

   638 	 * @param aId identifier

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

   640 	 *                      namespace is used

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

   642 	 */

   643 	virtual TItemId RemoveObjectL( TItemId aId, 

   644 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   645 

   646 	/**

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

   648 	 *

   649 	 * @param aUri URI

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

   651 	 *                      namespace is used

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

   653 	 */

   654 	virtual TItemId RemoveObjectL( const TDesC& aUri, 

   655 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   656 

   657 	/**

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

   659 	 * metadata database.

   660 	 *

   661 	 * @param aId object IDs to be removed

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

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

   664 	 *                has failed)

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

   666 	 *                      namespace is used

   667 	 * @return first item error

   668 	 */

   669 	virtual TInt RemoveObjectsL( 

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

   671 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   672 

   673 	/**

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

   675 	 * database.

   676 	 *

   677 	 * @param aUri object URIs to be removed

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

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

   680 	 *                has failed)

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

   682 	 *                      namespace is used

   683 	 * @return first item error

   684 	 */

   685 	virtual TInt RemoveObjectsL( 

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

   687 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   688 

   689 	/**

   690 	 * Asynchronously removes the array of objects with the specified 

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

   692 	 * must be deserialized with DeserializeIdsL method.

   693 	 *

   694 	 * @param aId object IDs to be removed

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

   696      *                completes.

   697      * @param aSerializedObjectIds returned serialized list of object IDs

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

   699 	 *                      namespace is used

   700 	 */

   701 	virtual void RemoveObjectsAsyncL( 

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

   703 			RMdEDataBuffer& aSerializedObjectIds, 

   704 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   705 

   706 	/**

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

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

   709 	 * deserialized with DeserializeIdsL method.

   710 	 *

   711 	 * @param aUri object URIs to be removed

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

   713      *                completes.

   714      * @param aSerializedObjectIds returned serialized list of object IDs

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

   716 	 *                      namespace is used

   717 	 */

   718 	virtual void RemoveObjectsAsyncL( 

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

   720 			RMdEDataBuffer& aSerializedObjectIds, 

   721 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   722 	

   723 	/**

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

   725 	 * definition.

   726 	 *

   727 	 * Example:

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

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

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

   731 	 * 

   732 	 * @param aId object ID

   733 	 * @param aObjectDef object definition

   734 	 *

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

   736 	 *         identifier in the metadata engine database

   737 	 */

   738 	virtual CMdEObject* GetObjectL( const TItemId aId, 

   739 			CMdEObjectDef& aObjectDef ) = 0;

   740 

   741 	/**

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

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

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

   745 	 *

   746 	 * @param aId object ID

   747 	 * @param aNamespaceDef namespace

   748 	 *

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

   750 	 *          identifier in the metadata engine database

   751 	 */

   752 	virtual CMdEObject* GetObjectL( const TItemId aId, 

   753 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   754 

   755 	/**

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

   757 	 * with the specified ID and specified namespace 

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

   759 	 *

   760 	 * @param aId object ID

   761 	 * @param aNamespaceDef namespace

   762 	 *

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

   764 	 *          identifier in the metadata engine database

   765 	 */

   766 	virtual CMdEObject* GetFullObjectL( const TItemId aId, 

   767 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   768 

   769 	/**

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

   771 	 * definition.

   772 	 * 

   773 	 * Example:

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

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

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

   777 	 *

   778 	 * @param aGuidHigh GUID high

   779 	 * @param aGuidLow GUID low

   780 	 * @param aObjectDef object definition

   781 	 *

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

   783 	 *          identifier in the metadata engine database

   784 	 */

   785 	virtual CMdEObject* GetObjectL( 

   786 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   787 			CMdEObjectDef& aObjectDef ) = 0;

   788 

   789 	/**

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

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

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

   793 	 *

   794 	 * Example:

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

   796 	 * 

   797 	 * @param aGuidHigh  GUID high

   798 	 * @param aGuidLow  GUID low

   799 	 * @param aNamespaceDef namespace

   800 	 *

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

   802 	 *          identifier in the metadata engine database

   803 	 */

   804 	virtual CMdEObject* GetObjectL( 

   805 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   806 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   807 

   808 	/**

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

   810 	 * with the specified GUID and specified namespace 

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

   812 	 * 

   813 	 * Example:

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

   815 	 *

   816 	 * @param aGuidHigh GUID high

   817 	 * @param aGuidLow GUID low

   818 	 * @param aNamespaceDef namespace

   819 	 *

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

   821 	 *          identifier in the metadata engine database

   822 	 */

   823 	virtual CMdEObject* GetFullObjectL( 

   824 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   825 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   826 

   827 	/**

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

   829 	 * definition.

   830 	 *

   831 	 * Example:

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

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

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

   835 	 *

   836 	 * @param aUri object URI

   837 	 * @param aObjectDef object definition

   838 	 *

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

   840 	 *          identifier in the metadata engine database

   841 	 */

   842 	virtual CMdEObject* GetObjectL( const TDesC& aUri, 

   843 			CMdEObjectDef& aObjectDef ) = 0;

   844 

   845 	/**

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

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

   848 	 * NULL, the default namespace is used).

   849 	 *

   850 	 * @param aUri object URI

   851 	 * @param aNamespaceDef namespace

   852 	 *

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

   854 	 *          identifier in the metadata engine database

   855 	 */

   856 	virtual CMdEObject* GetObjectL( const TDesC& aUri, 

   857 			CMdENamespaceDef* aNamespaceDef = NULL) = 0;

   858 

   859 	/**

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

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

   862 	 * namespace is used).

   863 	 *

   864 	 * @param aUri object URI

   865 	 * @param aNamespaceDef namespace

   866 	 *

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

   868 	 *          identifier in the metadata engine database

   869 	 */

   870 	virtual CMdEObject* GetFullObjectL( const TDesC& aUri, 

   871 			CMdENamespaceDef* aNamespaceDef = NULL) = 0;

   872 

   873 	/**

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

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

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

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

   878 	 * The modifications can be canceled by calling the 

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

   880 	 *

   881 	 * Example:

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

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

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

   885 	 * 

   886 	 *  CMdEPropertyDef& lastModDatePropDef = imageDef.GetPropertyDefL(

   887      *   		Object::KLastModifiedDateProperty );

   888      * 

   889      *  CMdEProperty* lastModDateProp = NULL;

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

   891      * 

   892      *  TTime currenttime( 0 );

   893      *	currenttime.UniversalTime();

   894      * 

   895      *  if ( lastModDateProp )

   896      *      {

   897      *      lastModDateProp->SetTimeValueL( currenttime );

   898      *      }

   899      *  else

   900      *      {

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

   902      *      }

   903      *  }

   904      *  iMdeSession->CommitObjectL( *image );

   905 	 *  

   906 	 * 

   907 	 * @param aId  object ID

   908 	 * @param aObjectDef object definition

   909 	 *

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

   911      *          identifier in the metadata engine database.

   912 	 */

   913 	virtual CMdEObject* OpenObjectL( const TItemId aId, 

   914 			CMdEObjectDef& aObjectDef ) = 0;

   915 

   916 	/**

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

   918 	 * with the specified ID and specified namespace 

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

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

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

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

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

   924 	 * lock.

   925 	 *

   926 	 * @param aId  object ID.

   927 	 * @param aNamespaceDef namespace

   928 	 *

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

   930      *          identifier in the metadata engine database.

   931 	 */

   932 	virtual CMdEObject* OpenObjectL( const TItemId aId, 

   933 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   934 

   935 	/**

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

   937 	 * with the specified ID and specified namespace 

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

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

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

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

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

   943 	 * lock.

   944 	 *

   945 	 * @param aId  object ID.

   946 	 * @param aNamespaceDef namespace

   947 	 *

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

   949      *          identifier in the metadata engine database.

   950 	 */

   951 	virtual CMdEObject* OpenFullObjectL( const TItemId aId, 

   952 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   953 

   954 

   955 	/**

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

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

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

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

   960 	 * The modifications can be canceled by calling the 

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

   962 	 *

   963 	 * @param aGuidHigh  GUID high

   964 	 * @param aGuidLow  GUID low

   965 	 * @param aObjectDef object definition

   966 	 *

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

   968      *          identifier in the metadata engine database.

   969 	 */

   970 	virtual CMdEObject* OpenObjectL( 

   971 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   972 			CMdEObjectDef& aObjectDef ) = 0;

   973 

   974 	/**

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

   976 	 * with the specified GUID and specified namespace 

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

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

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

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

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

   982 	 * lock.

   983 	 *

   984 	 * @param aGuidHigh  GUID high

   985 	 * @param aGuidLow  GUID low

   986 	 * @param aNamespaceDef namespace

   987 	 *

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

   989      *          identifier in the metadata engine database.

   990 	 */

   991 	virtual CMdEObject* OpenObjectL( 

   992 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   993 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   994 

   995 	/**

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

   997 	 * with the specified GUID and specified namespace 

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

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

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

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

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

  1003 	 * lock.

  1004 	 *

  1005 	 * @param aGuidHigh  GUID high

  1006 	 * @param aGuidLow  GUID low

  1007 	 * @param aNamespaceDef namespace

  1008 	 *

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

  1010      *          identifier in the metadata engine database.

  1011 	 */

  1012 	virtual CMdEObject* OpenFullObjectL( 

  1013 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

  1014 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1015 

  1016 

  1017 	/**

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

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

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

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

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

  1023 	 * method, which also releases the lock.

  1024 	 *

  1025 	 * @param aUri  object URI

  1026 	 * @param aObjectDef object definition

  1027 	 *

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

  1029      *          identifier in the metadata engine database.

  1030 	 */

  1031 	virtual CMdEObject* OpenObjectL( const TDesC& aUri, 

  1032 			CMdEObjectDef& aObjectDef ) = 0;

  1033 

  1034 	/**

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

  1036 	 * with the specified ID and specified namespace 

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

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

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

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

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

  1042 	 * lock.

  1043 	 *

  1044 	 * @param aUri  Object URI.

  1045 	 * @param aNamespaceDef namespace

  1046 	 *

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

  1048      *          identifier in the metadata engine database.

  1049 	 */

  1050 	virtual CMdEObject* OpenObjectL( const TDesC& aUri, 

  1051 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1052 

  1053 	/**

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

  1055 	 * with the specified ID and specified namespace 

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

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

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

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

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

  1061 	 * lock.

  1062 	 *

  1063 	 * @param aUri  Object URI.

  1064 	 * @param aNamespaceDef namespace

  1065 	 *

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

  1067      *          identifier in the metadata engine database.

  1068 	 */

  1069 	virtual CMdEObject* OpenFullObjectL( const TDesC& aUri, 

  1070 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1071 

  1072 	/**

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

  1074 	 * 

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

  1076 	 * @param aUri metadata object URI

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

  1078 	 */

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

  1080 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1081 

  1082 	/**

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

  1084 	 * 

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

  1086 	 * @param aId metadata object id

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

  1088 	 */

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

  1090 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1091 

  1092 	/**

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

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

  1095 	 * 

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

  1097 	 * @param aIds array of metadata object ids

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

  1099 	 */

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

  1101 			const RArray<TItemId>& aIds, 

  1102 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1103 	

  1104 	/**

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

  1106 	 * and releases the modification lock.

  1107      * 

  1108 	 * @param aObject  Object.

  1109      */

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

  1111 

  1112 	/**

  1113      * Commits the modifications made to objects to the database

  1114 	 * and releases the modification locks.

  1115      * 

  1116 	 * @param aObject  Object.

  1117      */

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

  1119 

  1120     /**

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

  1122 	 * modification lock.

  1123      * 

  1124 	 * @param aObject  Object.

  1125      */

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

  1127 

  1128 

  1129 	/* Methods for managing relations. */

  1130 

  1131 	/**

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

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

  1134 	 * 

  1135 	 * Note that the ownership of the returned relation is passed to the