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 /**

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

   228  * database.

   229  */

   230 class MMdEObjectPresentObserver

   231 	{

   232 public:

   233 

   234 	/**

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

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

   237 	 *

   238 	 * @param aSession session

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

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

   241 	 */

   242 	virtual void HandleObjectPresentNotification(CMdESession& aSession, 

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

   244     };

   245 

   246 /**

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

   248  * engine database.

   249  */

   250 class MMdERelationPresentObserver

   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 HandleRelationPresentNotification(CMdESession& aSession,

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

   264     };

   265 

   266 

   267 /**

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

   269  * database. This observer returns only relations IDs.

   270  */

   271 class MMdERelationObserver

   272 	{

   273 public:

   274 

   275 	/**

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

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

   278 	 *

   279 	 * @param aSession session

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

   281 	 * @param aRelationIdArray IDs of relations

   282 	 */

   283 	virtual void HandleRelationNotification(CMdESession& aSession, 

   284 			TObserverNotificationType aType,

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

   286     };

   287 

   288 /**

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

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

   291  */

   292 class MMdERelationItemObserver

   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 if relation was added/modified/remove

   302 	 * @param aRelationArray relations

   303 	 */

   304 	virtual void HandleRelationItemNotification(CMdESession& aSession, 

   305 			TObserverNotificationType aType,

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

   307     };

   308 

   309 /**

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

   311  * engine database.

   312  */

   313 class MMdEEventObserver

   314 	{

   315 public:

   316 

   317 	/**

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

   319 	 * added or removed in the metadata engine database.

   320 	 *

   321 	 * @param aSession session

   322 	 * @param aType if event was added or removed

   323 	 * @param aEventIdArray IDs of added events

   324 	 */

   325 	virtual void HandleEventNotification(CMdESession& aSession, 

   326 			TObserverNotificationType aType,

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

   328 

   329     };

   330 

   331 /**

   332  * Metadata engine session.

   333  */

   334 NONSHARABLE_CLASS(CMdESession) : public CBase

   335 	{

   336 public:

   337 

   338 	/* Constructors and destructor. */

   339 

   340 	/**

   341 	 * Opens a new metadata engine session.

   342 	 *

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

   344 	 *                  completed

   345 	 *

   346 	 * @return metadata engine session

   347 	 */

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

   349 

   350 	/**

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

   352 	 * cleanup stack.

   353 	 *

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

   355 	 *                  completed

   356      *

   357 	 * @return  metadata engine session

   358 	 */

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

   360 

   361 	/**

   362 	 * Destructor.

   363 	 */

   364 	virtual ~CMdESession();

   365 

   366 	/* Methods for managing namespace definitions. */

   367 

   368 	/**

   369 	 * Returns the number of namespace definitions.

   370 	 *

   371 	 * @return number of namespace definitions

   372 	 */

   373 	virtual TInt NamespaceDefCount() const = 0;

   374 

   375 	/**

   376 	 * Returns the namespace definition at the specified index.

   377 	 *

   378 	 * @param aIndex index

   379 	 *

   380 	 * @return namespace definition

   381 	 */

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

   383 

   384 	/**

   385 	 * Returns the namespace definition with the specified name.

   386 	 *

   387 	 * @param aName name

   388 	 *

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

   390 	 *         with the specified name

   391 	 */

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

   393 

   394 	 /* Returns the default namespace definition.

   395 	 *

   396 	 * @return  the default namespace definition.

   397 	 */

   398 	virtual CMdENamespaceDef& GetDefaultNamespaceDefL() = 0;

   399 

   400 	/**

   401 	 * Adds a new relation definition to namespace,

   402 	 *

   403 	 * Example:

   404 	 *  void AddRelationL()

   405 	 *  {

   406 	 *    _LIT( TestRelation, "TestRelation" );

   407 	 *    TBuf <15> relname( TestRelation );

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

   409 	 *  }

   410 	 * 

   411 	 * @param aNamespaceDef namespace definition to which relation belongs

   412 	 * @param aName         relation definitions name

   413 	 */

   414 	virtual void AddRelationDefL(const CMdENamespaceDef &aNamespaceDef, 

   415 			const TDesC &aName) = 0;

   416 

   417 	/**

   418 	 * Adds a new event definition to namespace.

   419 	 * 

   420 	 * Example:

   421 	 *  void AddEventDefL()

   422 	 *  {

   423 	 *    _LIT( TestEvent, "TestEvent" );

   424 	 *    TBuf <10> eventName( TestEvent );

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

   426 	 *  }

   427 	 *

   428 	 * @param aNamespaceDef namespace definition to which event belongs

   429 	 * @param aName         event definitions name

   430 	 */

   431 	virtual void AddEventDefL(const CMdENamespaceDef &aNamespaceDef, 

   432 			const TDesC &aName) = 0;

   433 

   434 	/* Methods for managing objects. */

   435 

   436     /**

   437      * Adds multiple instance items to metadata database.

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

   439      * event causes a leave.

   440 	 *

   441      * @param aItems list of items to add

   442      * @return first item error

   443      */

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

   445 

   446     /**

   447      * Commits multiple instance items to metadata database.

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

   449      * event causes a leave.

   450      * 

   451      * @param aItems list of items to add

   452      * @return first item error

   453      */

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

   455 

   456    /**

   457      * Adds multiple instance items asynchronously to metadata database.

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

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

   460      * deserialized with DeserializeItemsL method.

   461      * 

   462      * Example:

   463      *  class CExampleActiveObject : public CActive

   464      *  {

   465      *    void CActiveObject::AddItemsL();

   466      *    ...

   467      *    RPointerArray<CMdEInstanceItem> iItems;

   468      *    RMdEDataBuffer iResultBuffer;

   469      *  };

   470      * 

   471      *  void CExampleActiveObject::AddItemsL()

   472      *  {

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

   474      *    SetActive();

   475      *  }

   476      * 

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

   478      * 

   479      * @param aItems List of item to add.

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

   481      *                completes.

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

   483      */

   484 	virtual void AddItemsAsyncL( 

   485 			RPointerArray<CMdEInstanceItem>& aItems, 

   486 			TRequestStatus& aStatus,

   487 			RMdEDataBuffer& aSerializedItemIds) = 0;

   488 

   489    /**

   490      * Commits multiple instance items asynchronously to metadata database.

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

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

   493      * deserialized with DeserializeItemsL method.

   494      * 

   495      * Example:

   496      *  class CExampleActiveObject : public CActive

   497      *   {

   498      *     void CActiveObject::UpdateItemsL();

   499      *     ...

   500      *     RPointerArray<CMdEInstanceItem> iItems;

   501      *     RMdEDataBuffer iResultBuffer;

   502      *   };

   503      * 

   504      *   void CExampleActiveObject::UpdateItemsL()

   505      *   {

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

   507      *     SetActive();

   508      *   }

   509      * 

   510      * @param aItems List of item to add.

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

   512      *                completes.

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

   514      */

   515 	virtual void UpdateItemsAsyncL( 

   516 			RPointerArray<CMdEInstanceItem>& aItems, 

   517 			TRequestStatus& aStatus,

   518 			RMdEDataBuffer& aSerializedItemIds ) = 0;

   519 

   520 	/**

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

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

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

   524 	 *

   525 	 * Example:

   526 	 *  _LIT( KObjectDef, "ObjectDefName" );

   527 	 *  TBuf<13> objDefStr( KObjectDef );

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

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

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

   531 	 * 

   532 	 * @param aDef definition of the new object

   533 	 * @param aUri URI of the new object

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

   535 	 *

   536 	 * @return new object

   537 	 */

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

   539                                     TUint32 aMediaId = 0 ) = 0;

   540 

   541 	/**

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

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

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

   545 	 * responsible for deleting the object).

   546 	 * 

   547  	 * Example:

   548 	 *  _LIT( KObjectDef, "ObjectDefName" );

   549 	 *  TBuf<13> objDefStr( KObjectDef );

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

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

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

   553 	 *

   554 	 * @param aDef definition of the new object

   555 	 * @param aUri URI of the new object

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

   557 	 *

   558 	 * @return new object

   559 	 */

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

   561                                      TUint32 aMediaId = 0 ) = 0;

   562 

   563     /**

   564      * Adds the specified new object to metadata database.

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

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

   567      * otherwise object adding is successful.

   568      *

   569      * @param aObject object to be added

   570      *

   571      * @return item ID of the added object

   572      */

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

   574 

   575     /**

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

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

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

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

   580      *

   581      * @param aObjects  list of objects to be added

   582      * @return first object error

   583      */

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

   585 

   586 	/**

   587 	 * Deserialize serialized list of item IDs

   588 	 *

   589 	 * @param aSerializedItemIds serialized list of item IDs

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

   591 	 *                           buffer to this ID array

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

   593 	 *                           buffer to this ID array

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

   595 	 *                           from buffer to this ID array

   596 	 *

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

   598 	 */

   599 	virtual TInt DeserializeIdsL( RMdEDataBuffer& aSerializedItemIds, 

   600 			RArray<TItemId>* aResultObjects = NULL, 

   601 			RArray<TItemId>* aResultEvents = NULL, 

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

   603 						   

   604 	/**

   605 	 * Deserialize serialized list of items

   606 	 *

   607 	 * @param aSerializedItems serialized list of items

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

   609 	 *

   610 	 * @return first item error

   611 	 */

   612 	virtual TInt DeserializeItemsL( RMdEDataBuffer& aSerializedItems, 

   613 			RPointerArray<CMdEInstanceItem>& aItems ) = 0;

   614 

   615 	/**

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

   617 	 *

   618 	 * @param aId identifier

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

   620 	 *                      namespace is used

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

   622 	 */

   623 	virtual TItemId RemoveObjectL( TItemId aId, 

   624 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   625 

   626 	/**

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

   628 	 *

   629 	 * @param aUri URI

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

   631 	 *                      namespace is used

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

   633 	 */

   634 	virtual TItemId RemoveObjectL( const TDesC& aUri, 

   635 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   636 

   637 	/**

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

   639 	 * metadata database.

   640 	 *

   641 	 * @param aId object IDs to be removed

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

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

   644 	 *                has failed)

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

   646 	 *                      namespace is used

   647 	 * @return first item error

   648 	 */

   649 	virtual TInt RemoveObjectsL( 

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

   651 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   652 

   653 	/**

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

   655 	 * database.

   656 	 *

   657 	 * @param aUri object URIs to be removed

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

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

   660 	 *                has failed)

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

   662 	 *                      namespace is used

   663 	 * @return first item error

   664 	 */

   665 	virtual TInt RemoveObjectsL( 

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

   667 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   668 

   669 	/**

   670 	 * Asynchronously removes the array of objects with the specified 

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

   672 	 * must be deserialized with DeserializeIdsL method.

   673 	 *

   674 	 * @param aId object IDs to be removed

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

   676      *                completes.

   677      * @param aSerializedObjectIds returned serialized list of object IDs

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

   679 	 *                      namespace is used

   680 	 */

   681 	virtual void RemoveObjectsAsyncL( 

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

   683 			RMdEDataBuffer& aSerializedObjectIds, 

   684 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   685 

   686 	/**

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

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

   689 	 * deserialized with DeserializeIdsL method.

   690 	 *

   691 	 * @param aUri object URIs to be removed

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

   693      *                completes.

   694      * @param aSerializedObjectIds returned serialized list of object IDs

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

   696 	 *                      namespace is used

   697 	 */

   698 	virtual void RemoveObjectsAsyncL( 

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

   700 			RMdEDataBuffer& aSerializedObjectIds, 

   701 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   702 	

   703 	/**

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

   705 	 * definition.

   706 	 *

   707 	 * Example:

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

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

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

   711 	 * 

   712 	 * @param aId object ID

   713 	 * @param aObjectDef object definition

   714 	 *

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

   716 	 *         identifier in the metadata engine database

   717 	 */

   718 	virtual CMdEObject* GetObjectL( const TItemId aId, 

   719 			CMdEObjectDef& aObjectDef ) = 0;

   720 

   721 	/**

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

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

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

   725 	 *

   726 	 * @param aId object ID

   727 	 * @param aNamespaceDef namespace

   728 	 *

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

   730 	 *          identifier in the metadata engine database

   731 	 */

   732 	virtual CMdEObject* GetObjectL( const TItemId aId, 

   733 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   734 

   735 	/**

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

   737 	 * with the specified ID and specified namespace 

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

   739 	 *

   740 	 * @param aId object ID

   741 	 * @param aNamespaceDef namespace

   742 	 *

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

   744 	 *          identifier in the metadata engine database

   745 	 */

   746 	virtual CMdEObject* GetFullObjectL( const TItemId aId, 

   747 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   748 

   749 	/**

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

   751 	 * definition.

   752 	 * 

   753 	 * Example:

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

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

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

   757 	 *

   758 	 * @param aGuidHigh GUID high

   759 	 * @param aGuidLow GUID low

   760 	 * @param aObjectDef object definition

   761 	 *

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

   763 	 *          identifier in the metadata engine database

   764 	 */

   765 	virtual CMdEObject* GetObjectL( 

   766 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   767 			CMdEObjectDef& aObjectDef ) = 0;

   768 

   769 	/**

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

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

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

   773 	 *

   774 	 * Example:

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

   776 	 * 

   777 	 * @param aGuidHigh  GUID high

   778 	 * @param aGuidLow  GUID low

   779 	 * @param aNamespaceDef namespace

   780 	 *

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

   782 	 *          identifier in the metadata engine database

   783 	 */

   784 	virtual CMdEObject* GetObjectL( 

   785 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   786 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   787 

   788 	/**

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

   790 	 * with the specified GUID and specified namespace 

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

   792 	 * 

   793 	 * Example:

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

   795 	 *

   796 	 * @param aGuidHigh GUID high

   797 	 * @param aGuidLow GUID low

   798 	 * @param aNamespaceDef namespace

   799 	 *

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

   801 	 *          identifier in the metadata engine database

   802 	 */

   803 	virtual CMdEObject* GetFullObjectL( 

   804 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   805 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   806 

   807 	/**

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

   809 	 * definition.

   810 	 *

   811 	 * Example:

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

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

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

   815 	 *

   816 	 * @param aUri object URI

   817 	 * @param aObjectDef object definition

   818 	 *

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

   820 	 *          identifier in the metadata engine database

   821 	 */

   822 	virtual CMdEObject* GetObjectL( const TDesC& aUri, 

   823 			CMdEObjectDef& aObjectDef ) = 0;

   824 

   825 	/**

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

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

   828 	 * NULL, the default namespace is used).

   829 	 *

   830 	 * @param aUri object URI

   831 	 * @param aNamespaceDef namespace

   832 	 *

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

   834 	 *          identifier in the metadata engine database

   835 	 */

   836 	virtual CMdEObject* GetObjectL( const TDesC& aUri, 

   837 			CMdENamespaceDef* aNamespaceDef = NULL) = 0;

   838 

   839 	/**

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

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

   842 	 * namespace is used).

   843 	 *

   844 	 * @param aUri object URI

   845 	 * @param aNamespaceDef namespace

   846 	 *

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

   848 	 *          identifier in the metadata engine database

   849 	 */

   850 	virtual CMdEObject* GetFullObjectL( const TDesC& aUri, 

   851 			CMdENamespaceDef* aNamespaceDef = NULL) = 0;

   852 

   853 	/**

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

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

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

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

   858 	 * The modifications can be canceled by calling the 

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

   860 	 *

   861 	 * Example:

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

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

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

   865 	 * 

   866 	 *  CMdEPropertyDef& lastModDatePropDef = imageDef.GetPropertyDefL(

   867      *   		Object::KLastModifiedDateProperty );

   868      * 

   869      *  CMdEProperty* lastModDateProp = NULL;

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

   871      * 

   872      *  TTime currenttime( 0 );

   873      *	currenttime.UniversalTime();

   874      * 

   875      *  if ( lastModDateProp )

   876      *      {

   877      *      lastModDateProp->SetTimeValueL( currenttime );

   878      *      }

   879      *  else

   880      *      {

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

   882      *      }

   883      *  }

   884      *  iMdeSession->CommitObjectL( *image );

   885 	 *  

   886 	 * 

   887 	 * @param aId  object ID

   888 	 * @param aObjectDef object definition

   889 	 *

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

   891      *          identifier in the metadata engine database.

   892 	 */

   893 	virtual CMdEObject* OpenObjectL( const TItemId aId, 

   894 			CMdEObjectDef& aObjectDef ) = 0;

   895 

   896 	/**

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

   898 	 * with the specified ID and specified namespace 

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

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

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

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

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

   904 	 * lock.

   905 	 *

   906 	 * @param aId  object ID.

   907 	 * @param aNamespaceDef namespace

   908 	 *

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

   910      *          identifier in the metadata engine database.

   911 	 */

   912 	virtual CMdEObject* OpenObjectL( const TItemId aId, 

   913 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   914 

   915 	/**

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

   917 	 * with the specified ID and specified namespace 

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

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

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

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

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

   923 	 * lock.

   924 	 *

   925 	 * @param aId  object ID.

   926 	 * @param aNamespaceDef namespace

   927 	 *

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

   929      *          identifier in the metadata engine database.

   930 	 */

   931 	virtual CMdEObject* OpenFullObjectL( const TItemId aId, 

   932 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   933 

   934 

   935 	/**

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

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

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

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

   940 	 * The modifications can be canceled by calling the 

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

   942 	 *

   943 	 * @param aGuidHigh  GUID high

   944 	 * @param aGuidLow  GUID low

   945 	 * @param aObjectDef object definition

   946 	 *

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

   948      *          identifier in the metadata engine database.

   949 	 */

   950 	virtual CMdEObject* OpenObjectL( 

   951 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   952 			CMdEObjectDef& aObjectDef ) = 0;

   953 

   954 	/**

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

   956 	 * with the specified GUID and specified namespace 

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

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

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

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

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

   962 	 * lock.

   963 	 *

   964 	 * @param aGuidHigh  GUID high

   965 	 * @param aGuidLow  GUID low

   966 	 * @param aNamespaceDef namespace

   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 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   974 

   975 	/**

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

   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* OpenFullObjectL( 

   993 			const TInt64 aGuidHigh, const TInt64 aGuidLow, 

   994 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

   995 

   996 

   997 	/**

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

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

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

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

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

  1003 	 * method, which also releases the lock.

  1004 	 *

  1005 	 * @param aUri  object URI

  1006 	 * @param aObjectDef object definition

  1007 	 *

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

  1009      *          identifier in the metadata engine database.

  1010 	 */

  1011 	virtual CMdEObject* OpenObjectL( const TDesC& aUri, 

  1012 			CMdEObjectDef& aObjectDef ) = 0;

  1013 

  1014 	/**

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

  1016 	 * with the specified ID and specified namespace 

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

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

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

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

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

  1022 	 * lock.

  1023 	 *

  1024 	 * @param aUri  Object URI.

  1025 	 * @param aNamespaceDef namespace

  1026 	 *

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

  1028      *          identifier in the metadata engine database.

  1029 	 */

  1030 	virtual CMdEObject* OpenObjectL( const TDesC& aUri, 

  1031 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1032 

  1033 	/**

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

  1035 	 * with the specified ID and specified namespace 

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

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

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

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

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

  1041 	 * lock.

  1042 	 *

  1043 	 * @param aUri  Object URI.

  1044 	 * @param aNamespaceDef namespace

  1045 	 *

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

  1047      *          identifier in the metadata engine database.

  1048 	 */

  1049 	virtual CMdEObject* OpenFullObjectL( const TDesC& aUri, 

  1050 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1051 

  1052 	/**

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

  1054 	 * 

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

  1056 	 * @param aUri metadata object URI

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

  1058 	 */

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

  1060 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1061 

  1062 	/**

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

  1064 	 * 

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

  1066 	 * @param aId metadata object id

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

  1068 	 */

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

  1070 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1071 

  1072 	/**

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

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

  1075 	 * 

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

  1077 	 * @param aIds array of metadata object ids

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

  1079 	 */

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

  1081 			const RArray<TItemId>& aIds, 

  1082 			CMdENamespaceDef* aNamespaceDef = NULL ) = 0;

  1083 	

  1084 	/**

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

  1086 	 * and releases the modification lock.

  1087      * 

  1088 	 * @param aObject  Object.

  1089      */

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

  1091 

  1092 	/**

  1093      * Commits the modifications made to objects to the database

  1094 	 * and releases the modification locks.

  1095      * 

  1096 	 * @param aObject  Object.

  1097      */

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

  1099 

  1100     /**

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

  1102 	 * modification lock.

  1103      * 

  1104 	 * @param aObject  Object.

  1105      */

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

  1107 

  1108 

  1109 	/* Methods for managing relations. */

  1110 

  1111 	/**

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

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

  1114 	 * 

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

  1116 	 * caller of the method (that is, the caller is responsible for deleting 

  1117 	 * the relation).

  1118 	 *

  1119 	 * @param aId  relation ID

  1120 	 * @param aNamespaceDef namespace

  1121 	 *

  1122 	 * @return  relation or NULL, if there is no relation with the specified ID

  1123 	 *          in the metadata engine database

  1124 	 */

  1125 	virtual CMdERelation* GetRelationL(TItemId aId, 

  1126 			CMdENamespaceDef* aNamespacedef = NULL) = 0;

  1127 

  1128 	/**

  1129 	 * Constructs a new empty relation. Note that the relation is not inserted 

  1130 	 * in the database. The ownership of the new relation is passed to the 

  1131 	 * caller (that is, the caller is responsible for deleting the relation).

  1132 	 * 

  1133 	 * Example:

  1134      *	 CMdERelationDef& relationDef = namespaceDef.GetRelationDefL( MdeConstants::Relations::KContains );