1 /*

     2 * Copyright (c) 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:  Query base class

    15 *

    16 */

    17 

    18 

    19 #ifndef __MDEQUERY_H__

    20 #define __MDEQUERY_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 CMdEQuery;

    32 class CMdELogicCondition;

    33 class TMdEOrderRule;

    34 class CMdENamespaceDef;

    35 class CMdEItem;

    36 class CMdEInstanceItem;

    37 

    38 

    39 /**

    40  * Observer interface for MdE database queries.

    41  * 

    42  * Example of doing a query to metadata database:

    43  * 

    44  * A class needs to implement MMdEQueryObserver interface if it is going to do a query to MdE database.

    45  * 

    46  * class CMdEQueryExample : public MMdEQueryObserver

    47  * {

    48  *		void HandleQueryNewResults(CMdEQuery& aQuery, TInt aFirstNewItemIndex, TInt aNewItemCount);

    49  *		void HandleQueryCompleted(CMdEQuery& aQuery, TInt aError);

    50  * 		...

    51  * 		CMdESession* iMdeSession; // session to MdE, created before trying to do the query

    52  * 		CMdEQuery* iQuery;

    53  * };

    54  * 

    55  * void CMdEQueryExample::DoQuery()

    56  * {

    57  * 		CMdENamespaceDef& defNS = iMdeSession->GetDefaultNamespaceDefL();

    58  *	    

    59  *	    // In this function we create a query with following conditions:

    60  *	    // 		Right object in relation must be a location object.

    61  *	    // 		Left object in relation must have id 6.

    62  * 

    63  * 		// First create an object query. We want to find location objects so let's give that

    64  * 		// as a condition to the query. 

    65  *	    CMdEObjectDef& rightObjDef = defNS.GetObjectDefL(

    66  *	        MdeConstants::Location::KLocationObject );

    67  *	    iQuery = iMdeSession->NewObjectQueryL( defNS, rightObjDef, this );

    68  *			    

    69  * 		// Result mode EQueryResultModeItem means we want the query to return items.

    70  * 		// Other options are: EQueryResultModeId, EQueryResultModeCount, 

    71  * 		// EQueryResultModeDistinctValues and EQueryResultModeObjectWithFreetexts.

    72  *	    iQuery->SetResultMode( EQueryResultModeItem );

    73  * 

    74  * 		// ELogicConditionOperatorAnd means we want all conditions to be true.

    75  *	    iQuery->Conditions().SetOperator( ELogicConditionOperatorAnd );

    76  *	

    77  * 		// Add a relation condition to the query. The location object is the right side object of

    78  * 		// the relation.

    79  *	    CMdERelationCondition& filterCond = iQuery->Conditions().

    80  *	        AddRelationConditionL( ERelationConditionSideRight );

    81  *			        

    82  *		// The object on the left side of the relation must have ID 6.

    83  *	    filterCond.LeftL().AddObjectConditionL( 6 );

    84  *			    

    85  *	    iQuery->FindL( 10, 1 ); // Start the query! The first parameter is maximum number of result items. 

    86  * 								// The second parameter is number of results per observer

    87  *								// notification. This query returns maximum of 10 location items

    88  * 								// and gives a notification (HandleQueryNewResults) for each.

    89  * }

    90  * 

    91  * void CMdEQueryExample::HandleQueryCompleted( CMdEQuery& aQuery, TInt aError )

    92  * {

    93  * 		// query is completed

    94  * 		if( aQuery.Count() > 0 && aError == KErrNone )

    95  *		{

    96  *		// some items were found!

    97  *		}

    98  * }

    99  * 

   100  * void CMdEQueryExample::HandleQueryNewResults(CMdEQuery& aQuery, TInt aFirstNewItemIndex,

   101  *                                       TInt aNewItemCount)

   102  * {

   103  * 		// query is not yet completed but new results were found

   104  * }

   105  * 

   106  * @see CMdEQuery::FindL

   107  */

   108 class MMdEQueryObserver 

   109     {

   110 public:

   111 

   112     /**

   113      * Called to notify the observer that new results have been received 

   114      * in the query.

   115      *

   116      * @param aQuery              Query instance that received new results.

   117      * @param aFirstNewItemIndex  Index of the first new item that was added

   118      *                            to the result item array.

   119      * @param aNewItemCount       Number of items added to the result item 

   120      *                            array.

   121      */

   122     virtual void HandleQueryNewResults(CMdEQuery& aQuery,

   123                                        TInt aFirstNewItemIndex,

   124                                        TInt aNewItemCount) = 0;

   125 

   126 

   127             

   128     /**

   129      * Called to notify the observer that the query has been completed,

   130      * or that an error has occured.

   131      *

   132      * @param aQuery  Query instance.

   133      * @param aError  <code>KErrNone</code>, if the query was completed

   134      *                successfully. Otherwise one of the system-wide error 

   135      *                codes.

   136      */

   137     virtual void HandleQueryCompleted(CMdEQuery& aQuery, TInt aError) = 0;

   138     

   139     };

   140 

   141 

   142 /** Default count for finding items. */

   143 static const TUint KMdEQueryDefaultMaxCount = KMaxTUint;

   144 

   145 

   146 /**

   147  * MdE database query. This is the abstract base class for all metadata engine

   148  * database queries. Instances of a query class own all the result items 

   149  * fetched from the database; when the query instance is destroyed, the 

   150  * results will be destroyed as well.

   151  *

   152  * If a query is restarted by calling FindL() after a previous query operation 

   153  * has been completed, any new results are appended to the end of the result 

   154  * item list. The previous results are not affected by subsequent calls to 

   155  * FindL().

   156  *

   157  * The query parameters (order rules, search conditions, property filters) 

   158  * must be configured before FindL() is called. FindL() may be called several

   159  * times, but the query parameters that were in effect for the first Find()

   160  * are used for all FindL()s.

   161  */

   162 

   163 NONSHARABLE_CLASS(CMdEQuery) : public CBase

   164 	{

   165 public: 

   166 

   167     /** 

   168      * Query states.

   169      */

   170     enum TState

   171         {

   172         EStateFirst = 0x0000,

   173         

   174         /** The query has been created. The query parameters are specified

   175             during this state. */

   176         EStateNew,

   177         

   178         /** The query has been started with Find(). All the results received

   179             so far are available to the user. */

   180         EStateSearching,

   181         

   182         /** All the results have been found and they are available to 

   183             the user. */

   184         EStateCompleted,

   185         

   186         /** An error has occured. */

   187         EStateError,

   188         

   189         EStateLast

   190         };

   191 

   192     /* Constants. */

   193 	

   194 	/* Constructors and destructor. */

   195 

   196 	/**

   197 	 * Destructor.

   198 	 */

   199 	virtual ~CMdEQuery();

   200 

   201 

   202     /* Methods. */

   203 

   204     /**

   205 	 * Returns the type of the query.

   206 	 *

   207 	 * @return  Query type.

   208 	 */

   209 	IMPORT_C TQueryType Type() const;

   210 

   211     /**

   212 	 * Returns the namespace definition of the query.

   213 	 *

   214 	 * @return  Namespace definition.

   215 	 */

   216 	IMPORT_C CMdENamespaceDef& NamespaceDef() const;

   217 

   218     /**

   219 	 * Returns the session of the query.

   220 	 *

   221 	 * @return  Session.

   222 	 */

   223     IMPORT_C CMdESession& Session() const;

   224 

   225     /**

   226      * Returns the root of the condition tree.

   227      *

   228      * @return  Logic condition that acts as the root of the search conditions

   229      *          tree.

   230      */

   231     IMPORT_C CMdELogicCondition& Conditions() const;

   232     

   233     /**

   234      * Appends a new result ordering rule into the end of list of order rules.

   235      *

   236      * Example:

   237      *   CMdEObjectDef& objdef = iDefaultNamespaceDef->GetObjectDefL( MdeConstants::Object::KBaseObject );

   238      *   CMdEPropertyDef& propDef = objdef.GetPropertyDefL( MdeConstants::Object::KCreationDateProperty );

   239      *   TMdEOrderRule rule( *propDef, ETrue );

   240 	 *   iQuery->AppendOrderRuleL( rule ); // iQuery is CMdEQuery*

   241      * 

   242      * @param aRule  Order rule.

   243      */

   244     IMPORT_C void AppendOrderRuleL(const TMdEOrderRule& aRule);

   245 

   246     /**

   247      * Insert a new result ordering rule into the list of order rules. 

   248      * The first rule is at position zero.

   249      * 

   250      * Example:

   251      *   CMdEObjectDef& objdef = iDefaultNamespaceDef->GetObjectDefL( MdeConstants::Object::KBaseObject );

   252      *   CMdEPropertyDef& propDef = objdef.GetPropertyDefL( MdeConstants::Object::KCreationDateProperty );

   253      *   TMdEOrderRule rule( *propDef, ETrue );

   254 	 *   iQuery->InsertOrderRuleL( rule, 0 ); // iQuery is CMdEQuery*

   255      *

   256      * @param aRule  Order rule.

   257      * @param aPos   Position in the list of rules to insert into.

   258      */

   259     IMPORT_C void InsertOrderRuleL(const TMdEOrderRule& aRule, TInt aPos);

   260     

   261     /**

   262      * Returns the number of order rules currently defined.

   263      *

   264      * @return  Number of order rules.

   265      */

   266     IMPORT_C TInt OrderRuleCount() const;

   267     

   268     /**

   269      * Removes an order rule.

   270      *

   271      * @param aIndex  Index of the rule to remove.

   272      */

   273     IMPORT_C void RemoveOrderRule(TInt aIndex);

   274 

   275     /**

   276      * Gets an order rule.

   277      *

   278      * @param aIndex  Index of the rule to return.

   279      * @param aRule   Reference to the TMdEOrderRule where the rule is stored.

   280      */

   281     IMPORT_C TMdEOrderRule OrderRule(TInt aIndex) const;

   282 

   283     /**

   284 	 * Starts a query operation and returns immediately. The observers of 

   285      * the query instance will be notified when the query is completed, or 

   286      * if it fails. The query parameters (order rules, search conditions, 

   287      * property filters) must be configured before FindL() is called. 

   288      *

   289      * The caller can perform a find operation in several steps by using a

   290      * sufficiently small maximum number of result items. Notifications 

   291      * about progress of query is returned is steps, continuing the previously 

   292      * started find operation.

   293      *

   294      * @param aMaxCount     Maximum number of result items. Defaults to 

   295      *                      unlimited. 

   296      * @param aNotifyCount  Maximum number of results per observer

   297      *                      notification. Defaults to unlimited.

   298      *

   299      * @leave  KErrNotReady  The query is in the Searching state.

   300      *

   301      * @panic  TMdEPanic::EQueryStateIllegalOperation  

   302      *         Query is in a state that prohibits calling this method.

   303 	 */

   304     IMPORT_C void FindL(TUint aMaxCount = KMdEQueryDefaultMaxCount,

   305                         TUint aNotifyCount = KMdEQueryDefaultMaxCount);

   306 

   307     /**

   308 	 * Cancels the currently running query operation. Does nothing if the 

   309      * query is not currently running. 

   310 	 */

   311     IMPORT_C void Cancel();

   312 

   313     /**

   314      * Returns whether the query has been completed.

   315      *

   316      * @return  <code>ETrue</code>, if the query is not currently running.

   317      *          Otherwise <code>EFalse</code>.

   318      */

   319     IMPORT_C TBool IsComplete() const;

   320 

   321     /**

   322      * Returns the error code of the latest completed query. The same error

   323      * code has been passed to the query observer.

   324      *

   325      * @return  Error code.

   326      */

   327     IMPORT_C TInt Error() const;

   328 

   329 	/**

   330 	 * Returns the current state of the query.

   331 	 *

   332 	 * @return  Query state.

   333 	 */

   334 	IMPORT_C TState State() const;

   335 

   336     /**

   337 	 * Returns the number of received result items. This can be called at any

   338      * time during the query instance's lifetime.

   339 	 *

   340 	 * @return  The number of results.

   341 	 */

   342 	IMPORT_C TInt Count() const;

   343 	

   344     

   345     /**

   346 	 * Returns one of the result items. 

   347 	 * 

   348 	 * Example:

   349 	 *   void CExampleClass::HandleQueryCompleted( CMdEQuery& aQuery, TInt aError )

   350 	 *   {

   351 	 *     CMdEItem& mdeItem = aQuery.ResultItem( 0 );

   352 	 *     ...

   353 	 *   }

   354 	 * 

   355 	 * @param aIndex index of the returned item. 

   356 	 * @panics if aIndex is out of bounds

   357 	 * @return  Result item. 

   358 	 */

   359     IMPORT_C CMdEItem& ResultItem(TInt aIndex) const;

   360 

   361     /**

   362 	 * Returns one of the result ids. 

   363 	 * 

   364 	 * Example:

   365 	 *   void CExampleClass::HandleQueryCompleted( CMdEQuery& aQuery, TInt aError )

   366 	 *   {

   367 	 *     TItemId mdeItemId = aQuery.ResultId( 0 );

   368 	 *     ...

   369 	 *   }

   370 	 * 

   371 	 * @param aIndex index of the returned id.

   372 	 * @panics if aIndex is out of bounds

   373 	 * @return  Result id.

   374 	 */

   375     IMPORT_C TItemId ResultId(TInt aIndex) const;

   376 

   377     /**

   378 	 * Returns all of the result ids.

   379 	 *

   380 	 * @return  Result ids.

   381 	 */

   382     IMPORT_C const RArray<TItemId>& ResultIds() const;

   383 

   384     /**

   385      * Returns one of the result items. Ownership of the item is transferred 

   386      * to the caller. The results array element at the specified index will 

   387      * still point to the result item.

   388      *

   389      * @param aIndex  Result index.

   390      *

   391      * @return  Pointer to result item.

   392      */

   393     IMPORT_C CMdEItem* TakeOwnershipOfResult(TInt aIndex);

   394 

   395     /**

   396      * Determines whether the query owns a result item.

   397      * @param aIndex index of the result item which ownership is checked.

   398      * @panics if aIndex is out of bounds

   399      * @return  <code>ETrue</code>, if the query owns the item. Otherwise

   400      *          <code>EFalse</code>.

   401      */        

   402     IMPORT_C TBool OwnsResult(TInt aIndex);

   403 	

   404 	

   405     /**

   406      * Adds a new observer.

   407      *

   408      * @param  aObserver to add.

   409      */

   410     IMPORT_C void AddObserverL(MMdEQueryObserver& aObserver);

   411 

   412     /**

   413      * Removes an observer.

   414      *

   415      * @param  aObserver to remove.

   416      */

   417     IMPORT_C void RemoveObserver(MMdEQueryObserver& aObserver);

   418 

   419     /**

   420      * Sets type of query results. Whether whole items or only IDs.

   421      * Default value is EModeItem.

   422      *

   423      * @param  aMode Determines type of query results. Can be set of

   424      *         instance items or set of item IDs

   425      */

   426     IMPORT_C void SetResultMode( TQueryResultMode aMode );

   427     

   428     /**

   429      * Returns type of query results, whether whole items or only IDs.

   430      *

   431      * @return Type of query results.

   432      */

   433     IMPORT_C TQueryResultMode ResultMode() const;

   434     

   435     /**

   436 	 * Returns result object item

   437 	 *

   438 	 * @return  Result object item.

   439 	 */

   440     IMPORT_C CMdEItem& ResultObjectItem() const;

   441 

   442     /**

   443 	 * Returns one of the result distinct values

   444 	 *

   445 	 * @return  Result distinct value

   446 	 */

   447     IMPORT_C TPtrC16 ResultDistinctValue(TInt aIndex) const;

   448 

   449 	/**

   450 	 * Returns order rules

   451 	 *

   452 	 * @return  Order rules

   453 	 */

   454 	RArray<TMdEOrderRule>& OrderRules();

   455 

   456 	void SetQueryId( TUint32 aQueryId ) const

   457 		{

   458 		iQueryId = aQueryId;

   459 		}

   460 

   461 	TUint32 GetQueryId() const

   462 		{

   463 		return iQueryId;

   464 		}

   465 

   466 protected:

   467 

   468 	/* Constructors. */

   469 

   470 	/**

   471 	 * Constructor. Note that new queries should be created using the factory

   472 	 * methods in CMdESession.

   473 	 *

   474 	 * @param aType     Type of the query.

   475      * @param aSession

   476 	 */

   477 	CMdEQuery(TQueryType aType, CMdESession& aSession, CMdENamespaceDef& aNamespaceDef);

   478 	

   479 	CMdEQuery();

   480 

   481 	/**

   482 	 * Second-phase constructor. Creates the root node of the conditions tree.

   483 	 */

   484 	void QueryConstructL();

   485 

   486 

   487     /* Implementation methods. */

   488 

   489     /**

   490      * As Find().

   491      */

   492     virtual void DoFindL(TUint aMaxCount, TUint aNotifyCount){};

   493 

   494     /**

   495      * As Cancel().

   496      */

   497     virtual void DoCancel();

   498 

   499 

   500     /* Notification methods. */

   501 

   502     /**

   503      * Appends new item results to the results array. This query instance takes 

   504      * ownership of the items. 

   505 	 *

   506 	 * If a leave occurs, the query won't take ownership of any of the new 

   507      * result items. The caller is responsible for destroying the result

   508      * items in this case.

   509      *

   510      * This operation is atomic: either all of the new results are added to

   511      * the results array and the query takes ownership of them, or none of

   512      * results are added to the results array.

   513      *

   514      * @param aNewResults contains result items

   515      */

   516     virtual void NotifyNewResultsL(const RPointerArray<CMdEInstanceItem>& aNewResults);

   517 

   518     /**

   519      * Appends new ID results to the results array.

   520      * 

   521      * @param aNewResults contains results from ID query

   522      */

   523     virtual void NotifyNewResultsL(const RArray<TItemId>& aNewResults);

   524 

   525     /**

   526      * Appends distinct value results to the results array.

   527      * 

   528      * @param aResults contains results from distinct value query

   529      */

   530     virtual void NotifyNewResultsL( const CDesCArray& aNewResults );

   531 

   532 

   533     /**

   534      * Gets result from count query.

   535      * 

   536      * @param aResults contains result from count query

   537      */

   538     virtual void NotifyNewResults(TUint32 aResult);

   539         

   540     /**

   541      * Notifies observers that the query was completed.

   542      */

   543     virtual void NotifyCompleted(TInt aError);

   544 

   545 

   546 	/* Utility methods. */

   547 	

   548 	/**

   549 	 * Sets the state of the query.

   550 	 *

   551 	 * @param aState  Query state.

   552 	 */

   553     void SetState(TState aState);

   554     

   555     /** 

   556      * Panics if the state of the query is the specified state.

   557      *

   558      * @param aState  Query state.

   559      *

   560      * @panic TMdEPanic::EQueryStateIllegalOperation  The query was not 

   561      *        in the given state.

   562      */

   563     void AssertInState(TState aState);

   564     

   565     /** 

   566      * Panics if the state of the query is not the specified state.

   567      *

   568      * @param aState  Query state.

   569      *

   570      * @panic TMdEPanic::EQueryStateIllegalOperation  The query was in the 

   571      *        given state.

   572      */

   573     void AssertNotInState(TState aState);

   574 

   575     

   576 private:

   577 

   578     /* Private data structures. */

   579 

   580     //  Result item for instances

   581     struct TResult

   582         {

   583         /** Result item. */

   584         CMdEItem* iItem;

   585 

   586         /** Query has the ownership of the result item. */

   587         TBool iOwned;

   588 

   589         /** Constructor for initializing the struct. */

   590         TResult(CMdEItem* aItem) : iItem(aItem), iOwned(EFalse) {}

   591         };

   592 

   593 

   594 private:

   595 

   596     /* Private methods. */

   597 

   598     /**

   599      * Appends new result items into the results array. Does not transfer

   600      * ownership of the new results to the query.

   601      *

   602      * @param aNewResults  Array of result items.

   603      */

   604     void AppendResultsL(const RPointerArray<CMdEInstanceItem>& aNewResults);

   605 

   606     void AppendResultsL(const RArray<TItemId>& aNewResults);

   607 

   608 	/*void AppendResultsL(CMdEInstanceItem* aObjectResult,

   609     	const RPointerArray<CMdEInstanceItem>& aRelationResults, 

   610     	const RPointerArray<CMdEInstanceItem>& aEventResults);*/

   611     	

   612     void AppendResultsL(const CDesCArray& aNewResults);

   613     	

   614 private:

   615 

   616 	mutable TUint32 iQueryId;

   617 

   618     /** The session of the query. */

   619     CMdESession& iSession;

   620 

   621 	/** The namespace definition of the query */

   622 	CMdENamespaceDef& iNamespaceDef;

   623     

   624     /** Type of the query. */

   625     TQueryType iType;

   626 

   627     /** Type of results. */

   628     TQueryResultMode iResultMode;

   629 

   630     /** State of the query. */    

   631     TState iState;

   632 

   633     /** Latest error code. */

   634     TInt iError;

   635 

   636     /** Root node of the conditions tree.  Always present. */

   637     CMdELogicCondition* iConditions;

   638     

   639     /** Array of result ordering rules. */

   640     RArray<TMdEOrderRule> iOrderRules;

   641 

   642     /** Instance result items. */

   643     RArray<TResult> iResults;

   644     

   645     /** ID result items. */

   646     RArray<TItemId> iIdResults;

   647 

   648     /** Instance result object item */

   649     TResult iObjectResult;

   650 	

   651     /** Results of count query */

   652     TInt iCountResult;

   653 

   654     /** Observers. */

   655     RPointerArray<MMdEQueryObserver> iObservers;

   656     

   657     CDesCArray* iDistinctResults;

   658     

   659     TBool iDestroyed;

   660     };

   661 

   662     

   663 // includes only for client more convinient usage

   664 	#include <mdeobjectquery.h>

   665 	#include <mderelationquery.h>

   666 	#include <mdeeventquery.h>

   667 	#include <mdelogiccondition.h>

   668 	#include <mdeobjectcondition.h>

   669 	#include <mderelationcondition.h>

   670 	#include <mdeeventcondition.h>

   671 	#include <mdepropertycondition.h>

   672 	#include <mderange.h>

   673 	#include <mdeorderrule.h>

   674 // end

   675 

   676 #endif  // __MDEQUERY_H__