1 /*

     2 * Copyright (c) 2010 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:  Qt search APIs

    15 *

    16 */

    17 

    18 #ifndef _CPIXSEARCHER_H

    19 #define _CPIXSEARCHER_H

    20 

    21 //Uncomment the following line to enable performance measurements

    22 //#define OST_TRACE_COMPILER_IN_USE

    23 

    24 #ifdef OST_TRACE_COMPILER_IN_USE

    25 

    26 #include <qdatetime.h>

    27 #include <qdebug.h>

    28 #define PERF_SEARCH_START_TIMER  searchTimer.start();

    29 #define PERF_SEARCH_RESTART_TIMER searchTimer.restart();

    30 #define PERF_SEARCH_ENDLOG qDebug() << "Search QT API took: " << searchTimer.elapsed() << "msec";

    31 

    32 #define PERF_GETDOC_START_TIMER  getDocumentTimer.start();

    33 #define PERF_GETDOC_RESTART_TIMER getDocumentTimer.restart();

    34 #define PERF_GETDOC_ENDLOG qDebug() << "Search QT API took: " << getDocumentTimer.elapsed() << "msec";

    35 

    36 #define PERF_TIME_NOW(message) qDebug() << "Search QT API: " << QString(message) << ": " << QTime::currentTime().toString("hh:mm:ss.zzz");

    37 

    38 #else 

    39 

    40 #define PERF_SEARCH_START_TIMER  

    41 #define PERF_SEARCH_RESTART_TIMER 

    42 #define PERF_SEARCH_ENDLOG 

    43 #define PERF_GETDOC_START_TIMER

    44 #define PERF_GETDOC_RESTART_TIMER

    45 #define PERF_GETDOC_ENDLOG

    46 #define PERF_TIME_NOW(message)

    47 

    48 #endif

    49 

    50 /**

    51  * @file

    52  * @ingroup Search Client API fpr Qt Clients

    53  * @brief Contains CCPixSearcher used for searching

    54  */

    55 

    56 #ifdef BUILD_DLL

    57 #define DLL_EXPORT Q_DECL_EXPORT

    58 #else

    59 #define DLL_EXPORT Q_DECL_IMPORT

    60 #endif

    61 

    62 #include <QObject>

    63 #include <cpixcommon.h>

    64 

    65 //forward declarations

    66 class CpixDocument;

    67 class CpixSearcherPrivate;

    68 

    69 // CLASS DECLARATION

    70 /**

    71  * @brief Used for searching.

    72  * @ingroup Qt Search Client API

    73  * Link against: cpixsearch.lib 

    74  * 

    75  * An instance of CpixSearcher is used to commit search operations.

    76  * 

    77  * Example code:

    78  * 

    79  * Usecase 1: Sync calls. 

    80  * \code

    81  * CpixSearcher* searcher = CpixSearcher::newInstance("root");

    82  * if(searcher){

    83  *      int hitCount = searcher->search("search for me");

    84  *      for(int i=0; i<hitCount; i++) {

    85  *      CpixDocument* doc = document(0);

    86  *      // do something with doc.

    87  *      delete doc;

    88  *      }

    89  *  }

    90  * \endcode

    91  * 

    92  * Usecase 2: Sync calls with explicit SetDatabase().

    93  * \code

    94  * CpixSearcher* searcher = CpixSearcher::newInstance();

    95  * searcher->SetDatabase("root");

    96  * int hitCount = searcher->search("search for me");

    97  * for(int i=0; i<hitCount; i++) {

    98  *      try{

    99  *          CpixDocument* doc = document(i);

   100  *          // do something with doc.

   101  *          delete doc;

   102  *      catch(...){

   103  *      //Do Cleanup

   104  *      }

   105  * }

   106  * \endcode

   107  * 

   108  * Usecase 3: Async Calls

   109  * \code

   110  * 

   111  * iCurrentDocumentCount = 0;

   112  * 

   113  * CpixSearcher* searcher = CpixSearcher::newInstance("root");

   114  * connect(searcher, SIGNAL(handleSearchResults(int,int)), this, SLOT(ClientHandleSearchCompleteSlot(int,int)) );

   115  * connect(searcher, SIGNAL(handleDocument(int,CpixDocument*)), this, SLOT(ClientHandleGetDocumentCompleteSlot(int,CpixDocument*)) );

   116  * int hitCount = searcher->search("search for me");

   117  * GetDocumentAsync( iCurrentDocumentCount++ );

   118  * 

   119  * ClientClass::ClientHandleGetDocumentCompleteSlot(int aError, CpixDocument* aDocument){

   120  *  if( KErrNone != aError ){

   121  *  //do something with aDocument

   122  *  }

   123  *  documentAsync( iCurrentDocumentCount++ ); //Now get the next document.

   124  * }

   125  * 

   126  * \endcode

   127  * 

   128  */

   129 class DLL_EXPORT CpixSearcher: public QObject

   130     {

   131     Q_OBJECT

   132 public:

   133     /**

   134        * Constructor.

   135        * Creates a CpixSearcher object and return a pointer to the created object.

   136        * @return A pointer to the created instance of CCPixSearcher.

   137        * 

   138        * @note After using this constructor, the client has to mandatorily call 

   139        * SetDatabase() before invoking any search.

   140        */

   141     static CpixSearcher* newInstance();

   142     

   143     /**

   144      * Overloaded constructor

   145      * Creates a CCPixSearcher object and return a pointer to the created object.

   146      * If this constructor is used, the client can directly invoke Search without

   147      * the need to call SetDatabase.

   148      * @param aBaseAppClass The baseAppClass on which to invoke searches on.

   149      * @param aDefaultSearchField Default field where the keywords are searched from.

   150      * @return A pointer to the created instance of CCPixSearcher.

   151      */

   152     static CpixSearcher* newInstance( QString aBaseAppClass, QString aDefaultSearchField=NULL );

   153 

   154     /**

   155      * Destructor. 

   156      */

   157     ~CpixSearcher();

   158     

   159     /**

   160      * Synchronously set (or change the database, if already set) on which to invoke subsequent searches.

   161      * @param aBaseAppClass baseAppClass whose corresponding database is to be opened.

   162      */

   163     void setDatabase(QString aBaseAppClass) THROWS_EXCEPTION;

   164 

   165     /**

   166      * Asynchronously set (or change the database, if already set) on which to invoke subsequent searches.

   167      * @param aBaseAppClass baseAppClass whose corresponding database is to be opened.

   168      *

   169      * @note Client is notified on completion of this call via HandleDatabaseSet signal.

   170      */

   171     void setDatabaseAsync(QString aBaseAppClass) THROWS_EXCEPTION;

   172 

   173     /**

   174      * Syncronously search for aSearchString.

   175      * @param aSearchString keywords to be searched for.

   176      * @param aDefaultSearchField Default field where the keywords are searched from.

   177      * @return Estimated number of documents containing aSearchString.

   178      */

   179     int search(QString aSearchString, QString aDefaultSearchField=NULL) THROWS_EXCEPTION;

   180 

   181     /**

   182      * Asyncronously search for aSearchString.

   183      * @param aSearchString keywords to be searched for.

   184      * @param aDefaultSearchField Default field where the keywords are searched from.

   185      * @return Estimated number of documents containing aSearchString.

   186      *

   187      * @note Client is notified on completion of this call via HandleSearchResults signal.

   188      */

   189     void searchAsync(QString aSearchString, QString aDefaultSearchField=NULL) THROWS_EXCEPTION;

   190 

   191     /**

   192      * Synchronously get the document with index aIndex.

   193      * @param aIndex Index of document to be retrieved

   194      * @return A pointer to CpixDocument that has been retrieved. Null on error.

   195      *

   196      * @note This should be called only after the synchronous search call has returned

   197      *      and aIndex should be between 0 and estimated count returned by Search().

   198      */     

   199     CpixDocument* document(int aIndex) THROWS_EXCEPTION;

   200 

   201     /**

   202      * Asynchronously get the document with index aIndex.

   203      * @param aIndex Index of document to be retrieved

   204      *

   205      * @note This should be called only after the synchronous search call has returned

   206      *      and aIndex should be between 0 and estimated count returned by Search().

   207      */     

   208     void documentAsync(int aIndex) THROWS_EXCEPTION;

   209 	

   210 	/**

   211      * Synchronously get the count,aCount of batch documens with index aIndex.

   212      * @param aIndex starting Index of document to be retrieved

   213 	 * @param aCount number of documents requested

   214 	 * @param aReturnDoc number of documents returned

   215      * @return A double pointer to CpixDocument that has been retrieved. Null on error.

   216      *

   217      * @note This should be called only after the synchronous search call has returned

   218      *      and aIndex should be between 0 and estimated count returned by Search().

   219 	 *      It is the client duty to free the memory allocated for the returned CpixDocument**

   220 	 *      deallocation of the memory can be done based on the value returned in aReturnDoc

   221      */     

   222     CpixDocument** batchdocument(int aIndex,int& aReturnDoc, int aCount = 1) THROWS_EXCEPTION;

   223 

   224     /**

   225      * Asynchronously get the batch documents with index aIndex.

   226      * @param aIndex Starting Index of documents to be retrieved

   227 	 * @param aCount number of documents requested

   228      *

   229      * @note This should be called only after the synchronous search call has returned

   230      *      and aIndex should be between 0 and estimated count returned by Search().

   231      */     

   232     void batchdocumentAsync(int aIndex, int aCount = 1) THROWS_EXCEPTION;

   233     

   234     /**

   235      * Cancels any outstanding searches.

   236      */

   237     void cancelSearch();

   238 

   239 signals:

   240     /**

   241      * Notify completion of SetDatabaseAsyc

   242      * @param aError Completion (error) code of SetDatabaseAsync

   243      */

   244     void handleDatabaseSet(int aError);

   245 

   246     /**

   247      * Notify completion of SearchAsyc

   248      * @param aError Completion (error) code of SearchAsyc

   249      * @param aEstimatedResultCount Estimated number of documents found after SearchAsync

   250      */     

   251     void handleSearchResults(int aError, int aEstimatedResultCount);

   252 

   253     /**

   254      * Notify completion of documentAsyc

   255      * @param aError Completion (error) code of GetDatabaseAsyc

   256      * @param aDocument The requested document.

   257      */     

   258     void handleDocument(int aError, CpixDocument* aDocument);

   259 	

   260 	/**

   261      * Notify completion of BatchdocumentAsyc

   262      * @param aError Completion (error) code of GetDatabaseAsyc

   263      * @param aDocument The requested document.

   264      */     

   265     void handleBatchDocuments(int aError,int aRetCount, CpixDocument** aDocument);

   266 

   267 private:

   268     /**

   269        * Defaul constructor.

   270        * Creates a CpixSearcher object and return a pointer to the created object.

   271        * @return A pointer to the created instance of CCPixSearcher.

   272        */

   273     CpixSearcher();

   274     

   275     CpixSearcherPrivate* const iPvtImpl;

   276     Q_DECLARE_PRIVATE_D( iPvtImpl, CpixSearcher )

   277     

   278 #ifdef OST_TRACE_COMPILER_IN_USE

   279     QTime searchTimer; 

   280     QTime getDocumentTimer;

   281 #endif

   282     };

   283 

   284 #endif //_CPIXSEARCHER_H