/*

* Copyright (c) 2010 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: 

*

*/

#ifndef __CCPIXSEARCHER_H__

#define __CCPIXSEARCHER_H__

// INCLUDE FILES

#include <e32base.h>

#include "RSearchServerSession.h"

/**

 * @file

 * @ingroup ClientAPI

 * @brief Contains CCPixSearcher used for searching

 */

// FORWARD DECLARATIONS

class MCPixOpenDatabaseRequestObserver;

class MCPixSearchRequestObserver;

class MCPixNextDocumentRequestObserver;

class MCPixSetAnalyzerRequestObserver;

class MCPixSetQueryParserRequestObserver;

// CLASS DECLARATION

/**

 * @brief Used for committing searches into an index database

 * @ingroup ClientAPI

 * 

 * An instance of CCPixSearcher is used to commit search operations to CSearchServer

 * 

 * Link against: CPixSearchClient.lib 

 */

class CCPixSearcher : public CActive

	{

	public: 

		enum TQueryParser {

			/**

			 * Database query parser provides advanced syntax support

			 * for creating complex and powerful queries. This query parser

			 * is intended for accessing the CPix databases. It is not

			 * localized and it should not be used to form queries

			 * directly from user input. It may simply fail with some

			 * locales.  

			 */

			EDatabaseQueryParser = 0,

			/**

			 * Query parser aimed for incremental queries provided directly

			 * by user. This query parser is localized and should 

			 * work properly for all locales. The language accepted

			 * by this parser is always the language specified by 

			 * the current locale. May behave internally somewhat 

			 * differently depending of language, but as a rule it 

			 * should always provides meaningful results for direct

			 * user input.    

			 */

			EIncrementalQueryParser = 1

		};

	public: // Constructors and destructors

	    /**

	    * NewL.

	    * Two-phase constructor.

	    * Creates a CCPixSearcher object using two phase construction,

	    * and return a pointer to the created object.

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

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

	    */

	    IMPORT_C static CCPixSearcher* NewL(RSearchServerSession& aSearchServerSession, const TDesC& aDefaultSearchField = KCpixDefaultField);

	    /**

	    * NewLC.

	    * Two-phase constructor.

	    * Creates a CCPixSearcher object using two phase construction,

	    * and return a pointer to the created object.

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

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

	    */

	    IMPORT_C static CCPixSearcher* NewLC(RSearchServerSession& aSearchServerSession, const TDesC& aDefaultSearchField = KCpixDefaultField);

	    /**

	    * ~CCPixSearcher.

	    * Destructor.

	    * Destroys the object and release memory.

	    */

	    IMPORT_C virtual ~CCPixSearcher();

	public: // New functions

		/**

		 * Returns true, if OpenDatabaseL method has been called succesfully. 

		 */

		IMPORT_C TBool IsDatabaseOpen() const; 

		/**

		 * Returns KNullDesC if database not open, otherwise the base app class for the opened database 

		 */		

		IMPORT_C const TDesC& GetBaseAppClass() const;

	    /**

	     * OpenDatabaseL. Synchronous version

	     * Opens a database to be searched by this searcher. Leaves with KErrInUse, 

	     * if asynchronous request is pending.

		 *

		 * Database must be succesfully opened before any searching functionality can be used. 

		 * Method can be used, if database has already been opened. In this case, connection to the old 

		 * database is closed.

		 * 

	     * @param aBaseAppClass Base application class that identifies the database this searcher is connected to.

	     */

		IMPORT_C void OpenDatabaseL(const TDesC& aBaseAppClass);

		/**

		 * OpenDatabaseL. Asynchronous version

		 * Requests opening a database to be searched by this searcher. When the request

		 * has completed or failed, the error code is passed to the HandleOpenDatabaseResultL-

		 * method of the observer. Leaves with KErrInUse, if asynchronous request is pending. 

		 * 

		 * Database must be succesfully opened before any searching functionality can be used. 

		 * Method can be used, if a database has already been opened. In this case, connection 

		 * to the old database is closed.

		 * 

		 * @param aObserver The observer to notify of the request's completion or failure

		 * @param aBaseAppClass Base application class that identifies the database this searcher is connected to.

		 */

		IMPORT_C void OpenDatabaseL(MCPixOpenDatabaseRequestObserver& aObserver, const TDesC& aBaseAppClass);

	    /**

	     * SetAnalyzer. Synchronous version

	     */

		IMPORT_C void SetAnalyzerL( const TDesC& aAnalyzer ); 

	    /**

	     * SetAnalyzer. Asynchronous version

	     */

		IMPORT_C void SetAnalyzerL( MCPixSetAnalyzerRequestObserver& aObserver, const TDesC& aAnalyzer );

	    /**

	     * SetAnalyzer. Synchronous version

	     * 

	     * The set QueryParser defines the query syntax used for searching. Two

	     * different query parsers are supported for two main use cases, that 

	     * are powerful accessing of the database for document and the other is

	     *     

	     * 

	     * @note SetAnalyzerL MUST NOT be used, when searching using discovery services

	     */

		IMPORT_C void SetQueryParserL( TQueryParser aQueryParser ); 

	    /**

	     * SetQueryParser. Synchronous version

	     * 

	     * @note Query parser cannot be set for discovery service

	     */

		IMPORT_C void SetQueryParserL( MCPixSetQueryParserRequestObserver& aObserver, TQueryParser aQueryParser ); 

	    /**

	     * SearchL. Synchronous version. 

	     * Commits a search and prepares a list of documents matching the query to be retrieved

	     * from the server. Use NextDocumentL to iterate throught the document list. 

		 *

	     * Leaves with KErrInUse, if asynchronous request is already pending and 

	     * KErrNotReady, if no database has been succefullly opened.

	     * @param aQueryString Query string, e.g. "j* smith". May include wild card characters '*' or '?'. See documentation for exact syntax

	     * @param aSearchField Database field where the keywords are searched from. If not given, default field is used.

	     * @return Estimated hit document count, so the number of documents matching the query

	     * 

	     * @note Is the search field necessary? Search field can also be embedded into the query 

	     * string and in case it already is there, and given search parameter is added there

	     * as an addition, an error may raise or the user may be suprised that the field 

	     * he sought to search over was not searched. 

	     */

		IMPORT_C TInt SearchL(const TDesC& aQueryString, const TDesC& aSearchField = KNullDesC);

		/**

		 * SearchL. Asynchronous version. 

	     * Issues a search request. When request has been completed a callback to 

	     * MSearchObserver::HandleSearchResultL is issued. 

	     * 

	     * Leaves with KErrInUse, if asynchronous request is already pending and 

	     * KErrNotReady, if no database has been succefullly opened.

	     * 

	     * @param aObserver The observer, which receives the result of this request

	     * @param aQueryString Query string, e.g. "j* smith". May include wild card characters '*' or '?'. See documentation for exact syntax

	     * @param aSearchField Database field where the keywords are searched from. If not given, default field is used.

	     * 

	     * @note Is the search field necessary? Search field can also be embedded into the query 

	     * string and in case it already is there, and given search parameter is added there

	     * as an addition, an error may raise or the user may be suprised that the field 

	     * he sought to search over was not searched. 

	     */

		IMPORT_C void SearchL(MCPixSearchRequestObserver& aObserver, const TDesC& aQuery, const TDesC& aSearchField = KNullDesC);

	    /**

	     * GetDocumentL

	     * Iterates throught the search result's document list (hits), that is stored in the 

	     * server side. The accessed list is ranked and the best matching document is heading 

	     * the result lest. First call of this method, return best matching, then second best 

	     * matching and so forth until all documents have been found. Method returns NULL, 

	     * when no more documents can be found.

	     *

	     * Leaves with KErrInUse, if asynchronous request is pending and 

	     * KErrNotReady, if no database has been succefullly opened.

         *

         * @todo Having also GetDocumentLC would be nice

         * @return Next available document or NULL, if no more documents can be found. Ownership is transferred

	     */

		IMPORT_C CSearchDocument* GetDocumentL(TInt aIndex);

		/**

	     * GetDocumentL

		 * Iterates throught the search result's document list (hits), that is stored in the 

	     * server side. The accessed list is ranked and the best matching document isheading 

	     * the result lest. When the request has been completed a callback to 

	     * MSearchObserver::HandleDocumentL is issued. 

	     *

	     * Leaves with KErrInUse, if asynchronous request is pending and 

	     * KErrNotReady, if no database has been succefullly opened.

	     *

         * @return Next available document or NULL, if no more documents can be found

		 */

		IMPORT_C void GetDocumentL(TInt aIndex, MCPixNextDocumentRequestObserver& aObserver);

	protected: // Functions from base classes

	    /**

	    * From CActive, RunL.

	    * Callback function.

	    * Invoked to handle responses from the server.

	    */

	    void RunL();

	    /**

	    * From CActive, DoCancel.

	    * Cancels any outstanding operation.

	    */

	    void DoCancel();

	    /**

	    * From CActive, RunError.

	    * Don't propagate error.

	    */

	    TInt RunError(TInt aError);

	protected: // Supporting functionality

		/**

		 * Used to form a CLucene query targeting the field identified by 'aField'

		 */

		HBufC* FormQueryStringL(const TDesC& aQueryString, const TDesC& aField); 

	private: // Constructors and destructors

	    /**

	    * CCPixSearcher.

	    * Performs the first phase of two phase construction.

	    */

		CCPixSearcher(RSearchServerSession& aSearchServerSession);

	    /**

	    * ConstructL.

	    * Performs the second phase construction of a

	    * CCPixSearcher object.

	    */

	    void ConstructL(const TDesC& aDefaultSearchField);

	private: // Data

		enum TState 

			{ 

			EStateNone = 0,

			EStateOpenDatabase, 

			EStateSearch, 

			EStateGetDocument,

			EStateSetAnalyzer,

			EStateSetQueryParser

			};

		union TObserver 

			{

			void* iAny; 

			MCPixOpenDatabaseRequestObserver* iOpenDatabase; 

			MCPixSearchRequestObserver* iSearch; 

			MCPixNextDocumentRequestObserver* iNextDocument; 

			MCPixSetAnalyzerRequestObserver* iSetAnalyzer;

			MCPixSetQueryParserRequestObserver* iSetQueryParser;

			};

	private:

		/**

		 * iState, the internal state

		 */

		TState iState;

		/**

		 * State for checking whether database is open

		 */

		TBool iIsDatabaseOpen; 

	    /**

	    * iSession, the time server session.

	    */

		RSearchServerSession& iSearchServerSession;

	    RSearchServerSubSession iSubSession;

	    /**

	     * Stores the assigned default search field for future OpenDatabase

	     * requests

	     */

	    HBufC* iDefaultSearchField;

	    /**

	     * Stores asynchronous request argument until the request 

	     * has finished

	     */

	    HBufC* iQueryString;

	    /**

	     * iEstimatedResultsCount, contains the estimated results count.

	     */

	    TInt iEstimatedResultsCount;

	    /**

	    * iObserver, observer which handles updates from the server.

	    */

	    TObserver iObserver;

	    /**

	     * Used to store the base application class

	     */

	    HBufC* iBaseAppClass; 	    

	    /**

	     * Used to store the analyzer definition

	     */

	    HBufC* iAnalyzer; 

	};

#endif //__CCPIXSEARCHER_H__

// End of File