--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/videocollection/mpxmyvideoscollection/tsrc/ut_vcxmyvideosmdsdb/inc/mdequery.h Tue May 25 12:44:54 2010 +0300
@@ -0,0 +1,676 @@
+/*
+* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Query base class
+*
+*/
+
+
+#ifndef __MDEQUERY_H__
+#define __MDEQUERY_H__
+
+
+#include <e32base.h>
+#include <badesca.h>
+
+#include <mdccommon.h>
+
+
+/* Forward declarations. */
+class CMdESession;
+class CMdEQuery;
+class CMdELogicCondition;
+class TMdEOrderRule;
+class CMdENamespaceDef;
+class CMdEItem;
+class CMdEInstanceItem;
+
+
+/**
+ * Observer interface for MdE database queries.
+ *
+ * Example of doing a query to metadata database:
+ *
+ * A class needs to implement MMdEQueryObserver interface if it is going to do a query to MdE database.
+ *
+ * class CMdEQueryExample : public MMdEQueryObserver
+ * {
+ * void HandleQueryNewResults(CMdEQuery& aQuery, TInt aFirstNewItemIndex, TInt aNewItemCount);
+ * void HandleQueryCompleted(CMdEQuery& aQuery, TInt aError);
+ * ...
+ * CMdESession* iMdeSession; // session to MdE, created before trying to do the query
+ * CMdEQuery* iQuery;
+ * };
+ *
+ * void CMdEQueryExample::DoQuery()
+ * {
+ * CMdENamespaceDef& defNS = iMdeSession->GetDefaultNamespaceDefL();
+ *
+ * // In this function we create a query with following conditions:
+ * // Right object in relation must be a location object.
+ * // Left object in relation must have id 6.
+ *
+ * // First create an object query. We want to find location objects so let's give that
+ * // as a condition to the query.
+ * CMdEObjectDef& rightObjDef = defNS.GetObjectDefL(
+ * MdeConstants::Location::KLocationObject );
+ * iQuery = iMdeSession->NewObjectQueryL( defNS, rightObjDef, this );
+ *
+ * // Result mode EQueryResultModeItem means we want the query to return items.
+ * // Other options are: EQueryResultModeId, EQueryResultModeCount,
+ * // EQueryResultModeDistinctValues and EQueryResultModeObjectWithFreetexts.
+ * iQuery->SetResultMode( EQueryResultModeItem );
+ *
+ * // ELogicConditionOperatorAnd means we want all conditions to be true.
+ * iQuery->Conditions().SetOperator( ELogicConditionOperatorAnd );
+ *
+ * // Add a relation condition to the query. The location object is the right side object of
+ * // the relation.
+ * CMdERelationCondition& filterCond = iQuery->Conditions().
+ * AddRelationConditionL( ERelationConditionSideRight );
+ *
+ * // The object on the left side of the relation must have ID 6.
+ * filterCond.LeftL().AddObjectConditionL( 6 );
+ *
+ * iQuery->FindL( 10, 1 ); // Start the query! The first parameter is maximum number of result items.
+ * // The second parameter is number of results per observer
+ * // notification. This query returns maximum of 10 location items
+ * // and gives a notification (HandleQueryNewResults) for each.
+ * }
+ *
+ * void CMdEQueryExample::HandleQueryCompleted( CMdEQuery& aQuery, TInt aError )
+ * {
+ * // query is completed
+ * if( aQuery.Count() > 0 && aError == KErrNone )
+ * {
+ * // some items were found!
+ * }
+ * }
+ *
+ * void CMdEQueryExample::HandleQueryNewResults(CMdEQuery& aQuery, TInt aFirstNewItemIndex,
+ * TInt aNewItemCount)
+ * {
+ * // query is not yet completed but new results were found
+ * }
+ *
+ * @see CMdEQuery::FindL
+ */
+class MMdEQueryObserver
+ {
+public:
+
+ /**
+ * Called to notify the observer that new results have been received
+ * in the query.
+ *
+ * @param aQuery Query instance that received new results.
+ * @param aFirstNewItemIndex Index of the first new item that was added
+ * to the result item array.
+ * @param aNewItemCount Number of items added to the result item
+ * array.
+ */
+ virtual void HandleQueryNewResults(CMdEQuery& aQuery,
+ TInt aFirstNewItemIndex,
+ TInt aNewItemCount) = 0;
+
+
+
+ /**
+ * Called to notify the observer that the query has been completed,
+ * or that an error has occured.
+ *
+ * @param aQuery Query instance.
+ * @param aError <code>KErrNone</code>, if the query was completed
+ * successfully. Otherwise one of the system-wide error
+ * codes.
+ */
+ virtual void HandleQueryCompleted(CMdEQuery& aQuery, TInt aError) = 0;
+
+ };
+
+
+/** Default count for finding items. */
+static const TUint KMdEQueryDefaultMaxCount = KMaxTUint;
+
+
+/**
+ * MdE database query. This is the abstract base class for all metadata engine
+ * database queries. Instances of a query class own all the result items
+ * fetched from the database; when the query instance is destroyed, the
+ * results will be destroyed as well.
+ *
+ * If a query is restarted by calling FindL() after a previous query operation
+ * has been completed, any new results are appended to the end of the result
+ * item list. The previous results are not affected by subsequent calls to
+ * FindL().
+ *
+ * The query parameters (order rules, search conditions, property filters)
+ * must be configured before FindL() is called. FindL() may be called several
+ * times, but the query parameters that were in effect for the first Find()
+ * are used for all FindL()s.
+ */
+
+NONSHARABLE_CLASS(CMdEQuery) : public CBase
+ {
+public:
+
+ /**
+ * Query states.
+ */
+ enum TState
+ {
+ EStateFirst = 0x0000,
+
+ /** The query has been created. The query parameters are specified
+ during this state. */
+ EStateNew,
+
+ /** The query has been started with Find(). All the results received
+ so far are available to the user. */
+ EStateSearching,
+
+ /** All the results have been found and they are available to
+ the user. */
+ EStateCompleted,
+
+ /** An error has occured. */
+ EStateError,
+
+ EStateLast
+ };
+
+ /* Constants. */
+
+ /* Constructors and destructor. */
+
+ /**
+ * Destructor.
+ */
+ virtual ~CMdEQuery();
+
+
+ /* Methods. */
+
+ /**
+ * Returns the type of the query.
+ *
+ * @return Query type.
+ */
+ IMPORT_C TQueryType Type() const;
+
+ /**
+ * Returns the namespace definition of the query.
+ *
+ * @return Namespace definition.
+ */
+ IMPORT_C CMdENamespaceDef& NamespaceDef() const;
+
+ /**
+ * Returns the session of the query.
+ *
+ * @return Session.
+ */
+ IMPORT_C CMdESession& Session() const;
+
+ /**
+ * Returns the root of the condition tree.
+ *
+ * @return Logic condition that acts as the root of the search conditions
+ * tree.
+ */
+ IMPORT_C CMdELogicCondition& Conditions() const;
+
+ /**
+ * Appends a new result ordering rule into the end of list of order rules.
+ *
+ * Example:
+ * CMdEObjectDef& objdef = iDefaultNamespaceDef->GetObjectDefL( MdeConstants::Object::KBaseObject );
+ * CMdEPropertyDef& propDef = objdef.GetPropertyDefL( MdeConstants::Object::KCreationDateProperty );
+ * TMdEOrderRule rule( *propDef, ETrue );
+ * iQuery->AppendOrderRuleL( rule ); // iQuery is CMdEQuery*
+ *
+ * @param aRule Order rule.
+ */
+ IMPORT_C void AppendOrderRuleL(const TMdEOrderRule& aRule);
+
+ /**
+ * Insert a new result ordering rule into the list of order rules.
+ * The first rule is at position zero.
+ *
+ * Example:
+ * CMdEObjectDef& objdef = iDefaultNamespaceDef->GetObjectDefL( MdeConstants::Object::KBaseObject );
+ * CMdEPropertyDef& propDef = objdef.GetPropertyDefL( MdeConstants::Object::KCreationDateProperty );
+ * TMdEOrderRule rule( *propDef, ETrue );
+ * iQuery->InsertOrderRuleL( rule, 0 ); // iQuery is CMdEQuery*
+ *
+ * @param aRule Order rule.
+ * @param aPos Position in the list of rules to insert into.
+ */
+ IMPORT_C void InsertOrderRuleL(const TMdEOrderRule& aRule, TInt aPos);
+
+ /**
+ * Returns the number of order rules currently defined.
+ *
+ * @return Number of order rules.
+ */
+ IMPORT_C TInt OrderRuleCount() const;
+
+ /**
+ * Removes an order rule.
+ *
+ * @param aIndex Index of the rule to remove.
+ */
+ IMPORT_C void RemoveOrderRule(TInt aIndex);
+
+ /**
+ * Gets an order rule.
+ *
+ * @param aIndex Index of the rule to return.
+ * @param aRule Reference to the TMdEOrderRule where the rule is stored.
+ */
+ IMPORT_C TMdEOrderRule OrderRule(TInt aIndex) const;
+
+ /**
+ * Starts a query operation and returns immediately. The observers of
+ * the query instance will be notified when the query is completed, or
+ * if it fails. The query parameters (order rules, search conditions,
+ * property filters) must be configured before FindL() is called.
+ *
+ * The caller can perform a find operation in several steps by using a
+ * sufficiently small maximum number of result items. Notifications
+ * about progress of query is returned is steps, continuing the previously
+ * started find operation.
+ *
+ * @param aMaxCount Maximum number of result items. Defaults to
+ * unlimited.
+ * @param aNotifyCount Maximum number of results per observer
+ * notification. Defaults to unlimited.
+ *
+ * @leave KErrNotReady The query is in the Searching state.
+ *
+ * @panic TMdEPanic::EQueryStateIllegalOperation
+ * Query is in a state that prohibits calling this method.
+ */
+ IMPORT_C void FindL(TUint aMaxCount = KMdEQueryDefaultMaxCount,
+ TUint aNotifyCount = KMdEQueryDefaultMaxCount);
+
+ /**
+ * Cancels the currently running query operation. Does nothing if the
+ * query is not currently running.
+ */
+ IMPORT_C void Cancel();
+
+ /**
+ * Returns whether the query has been completed.
+ *
+ * @return <code>ETrue</code>, if the query is not currently running.
+ * Otherwise <code>EFalse</code>.
+ */
+ IMPORT_C TBool IsComplete() const;
+
+ /**
+ * Returns the error code of the latest completed query. The same error
+ * code has been passed to the query observer.
+ *
+ * @return Error code.
+ */
+ IMPORT_C TInt Error() const;
+
+ /**
+ * Returns the current state of the query.
+ *
+ * @return Query state.
+ */
+ IMPORT_C TState State() const;
+
+ /**
+ * Returns the number of received result items. This can be called at any
+ * time during the query instance's lifetime.
+ *
+ * @return The number of results.
+ */
+ IMPORT_C TInt Count() const;
+
+
+ /**
+ * Returns one of the result items.
+ *
+ * Example:
+ * void CExampleClass::HandleQueryCompleted( CMdEQuery& aQuery, TInt aError )
+ * {
+ * CMdEItem& mdeItem = aQuery.ResultItem( 0 );
+ * ...
+ * }
+ *
+ * @param aIndex index of the returned item.
+ * @panics if aIndex is out of bounds
+ * @return Result item.
+ */
+ IMPORT_C CMdEItem& ResultItem(TInt aIndex) const;
+
+ /**
+ * Returns one of the result ids.
+ *
+ * Example:
+ * void CExampleClass::HandleQueryCompleted( CMdEQuery& aQuery, TInt aError )
+ * {
+ * TItemId mdeItemId = aQuery.ResultId( 0 );
+ * ...
+ * }
+ *
+ * @param aIndex index of the returned id.
+ * @panics if aIndex is out of bounds
+ * @return Result id.
+ */
+ IMPORT_C TItemId ResultId(TInt aIndex) const;
+
+ /**
+ * Returns all of the result ids.
+ *
+ * @return Result ids.
+ */
+ IMPORT_C const RArray<TItemId>& ResultIds() const;
+
+ /**
+ * Returns one of the result items. Ownership of the item is transferred
+ * to the caller. The results array element at the specified index will
+ * still point to the result item.
+ *
+ * @param aIndex Result index.
+ *
+ * @return Pointer to result item.
+ */
+ IMPORT_C CMdEItem* TakeOwnershipOfResult(TInt aIndex);
+
+ /**
+ * Determines whether the query owns a result item.
+ * @param aIndex index of the result item which ownership is checked.
+ * @panics if aIndex is out of bounds
+ * @return <code>ETrue</code>, if the query owns the item. Otherwise
+ * <code>EFalse</code>.
+ */
+ IMPORT_C TBool OwnsResult(TInt aIndex);
+
+
+ /**
+ * Adds a new observer.
+ *
+ * @param aObserver to add.
+ */
+ IMPORT_C void AddObserverL(MMdEQueryObserver& aObserver);
+
+ /**
+ * Removes an observer.
+ *
+ * @param aObserver to remove.
+ */
+ IMPORT_C void RemoveObserver(MMdEQueryObserver& aObserver);
+
+ /**
+ * Sets type of query results. Whether whole items or only IDs.
+ * Default value is EModeItem.
+ *
+ * @param aMode Determines type of query results. Can be set of
+ * instance items or set of item IDs
+ */
+ IMPORT_C void SetResultMode( TQueryResultMode aMode );
+
+ /**
+ * Returns type of query results, whether whole items or only IDs.
+ *
+ * @return Type of query results.
+ */
+ IMPORT_C TQueryResultMode ResultMode() const;
+
+ /**
+ * Returns result object item
+ *
+ * @return Result object item.
+ */
+ IMPORT_C CMdEItem& ResultObjectItem() const;
+
+ /**
+ * Returns one of the result distinct values
+ *
+ * @return Result distinct value
+ */
+ IMPORT_C TPtrC16 ResultDistinctValue(TInt aIndex) const;
+
+ /**
+ * Returns order rules
+ *
+ * @return Order rules
+ */
+ RArray<TMdEOrderRule>& OrderRules();
+
+ void SetQueryId( TUint32 aQueryId ) const
+ {
+ iQueryId = aQueryId;
+ }
+
+ TUint32 GetQueryId() const
+ {
+ return iQueryId;
+ }
+
+protected:
+
+ /* Constructors. */
+
+ /**
+ * Constructor. Note that new queries should be created using the factory
+ * methods in CMdESession.
+ *
+ * @param aType Type of the query.
+ * @param aSession
+ */
+ CMdEQuery(TQueryType aType, CMdESession& aSession, CMdENamespaceDef& aNamespaceDef);
+
+ CMdEQuery();
+
+ /**
+ * Second-phase constructor. Creates the root node of the conditions tree.
+ */
+ void QueryConstructL();
+
+
+ /* Implementation methods. */
+
+ /**
+ * As Find().
+ */
+ virtual void DoFindL(TUint aMaxCount, TUint aNotifyCount){};
+
+ /**
+ * As Cancel().
+ */
+ virtual void DoCancel();
+
+
+ /* Notification methods. */
+
+ /**
+ * Appends new item results to the results array. This query instance takes
+ * ownership of the items.
+ *
+ * If a leave occurs, the query won't take ownership of any of the new
+ * result items. The caller is responsible for destroying the result
+ * items in this case.
+ *
+ * This operation is atomic: either all of the new results are added to
+ * the results array and the query takes ownership of them, or none of
+ * results are added to the results array.
+ *
+ * @param aNewResults contains result items
+ */
+ virtual void NotifyNewResultsL(const RPointerArray<CMdEInstanceItem>& aNewResults);
+
+ /**
+ * Appends new ID results to the results array.
+ *
+ * @param aNewResults contains results from ID query
+ */
+ virtual void NotifyNewResultsL(const RArray<TItemId>& aNewResults);
+
+ /**
+ * Appends distinct value results to the results array.
+ *
+ * @param aResults contains results from distinct value query
+ */
+ virtual void NotifyNewResultsL( const CDesCArray& aNewResults );
+
+
+ /**
+ * Gets result from count query.
+ *
+ * @param aResults contains result from count query
+ */
+ virtual void NotifyNewResults(TUint32 aResult);
+
+ /**
+ * Notifies observers that the query was completed.
+ */
+ virtual void NotifyCompleted(TInt aError);
+
+
+ /* Utility methods. */
+
+ /**
+ * Sets the state of the query.
+ *
+ * @param aState Query state.
+ */
+ void SetState(TState aState);
+
+ /**
+ * Panics if the state of the query is the specified state.
+ *
+ * @param aState Query state.
+ *
+ * @panic TMdEPanic::EQueryStateIllegalOperation The query was not
+ * in the given state.
+ */
+ void AssertInState(TState aState);
+
+ /**
+ * Panics if the state of the query is not the specified state.
+ *
+ * @param aState Query state.
+ *
+ * @panic TMdEPanic::EQueryStateIllegalOperation The query was in the
+ * given state.
+ */
+ void AssertNotInState(TState aState);
+
+
+private:
+
+ /* Private data structures. */
+
+ // Result item for instances
+ struct TResult
+ {
+ /** Result item. */
+ CMdEItem* iItem;
+
+ /** Query has the ownership of the result item. */
+ TBool iOwned;
+
+ /** Constructor for initializing the struct. */
+ TResult(CMdEItem* aItem) : iItem(aItem), iOwned(EFalse) {}
+ };
+
+
+private:
+
+ /* Private methods. */
+
+ /**
+ * Appends new result items into the results array. Does not transfer
+ * ownership of the new results to the query.
+ *
+ * @param aNewResults Array of result items.
+ */
+ void AppendResultsL(const RPointerArray<CMdEInstanceItem>& aNewResults);
+
+ void AppendResultsL(const RArray<TItemId>& aNewResults);
+
+ /*void AppendResultsL(CMdEInstanceItem* aObjectResult,
+ const RPointerArray<CMdEInstanceItem>& aRelationResults,
+ const RPointerArray<CMdEInstanceItem>& aEventResults);*/
+
+ void AppendResultsL(const CDesCArray& aNewResults);
+
+private:
+
+ mutable TUint32 iQueryId;
+
+ /** The session of the query. */
+ CMdESession& iSession;
+
+ /** The namespace definition of the query */
+ CMdENamespaceDef& iNamespaceDef;
+
+ /** Type of the query. */
+ TQueryType iType;
+
+ /** Type of results. */
+ TQueryResultMode iResultMode;
+
+ /** State of the query. */
+ TState iState;
+
+ /** Latest error code. */
+ TInt iError;
+
+ /** Root node of the conditions tree. Always present. */
+ CMdELogicCondition* iConditions;
+
+ /** Array of result ordering rules. */
+ RArray<TMdEOrderRule> iOrderRules;
+
+ /** Instance result items. */
+ RArray<TResult> iResults;
+
+ /** ID result items. */
+ RArray<TItemId> iIdResults;
+
+ /** Instance result object item */
+ TResult iObjectResult;
+
+ /** Results of count query */
+ TInt iCountResult;
+
+ /** Observers. */
+ RPointerArray<MMdEQueryObserver> iObservers;
+
+ CDesCArray* iDistinctResults;
+
+ TBool iDestroyed;
+ };
+
+
+// includes only for client more convinient usage
+ #include <mdeobjectquery.h>
+ #include <mderelationquery.h>
+ #include <mdeeventquery.h>
+ #include <mdelogiccondition.h>
+ #include <mdeobjectcondition.h>
+ #include <mderelationcondition.h>
+ #include <mdeeventcondition.h>
+ #include <mdepropertycondition.h>
+ #include <mderange.h>
+ #include <mdeorderrule.h>
+// end
+
+#endif // __MDEQUERY_H__