searchsrv_plat/cpix_framework_api/inc/ccpixsearcher.h
author Dremov Kirill (Nokia-D-MSW/Tampere) <kirill.dremov@nokia.com>
Wed, 18 Aug 2010 10:53:26 +0300
changeset 15 cf5c74390b98
parent 10 afe194b6b1cd
permissions -rw-r--r--
Revision: 201031 Kit: 201033

/*
* 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);
		
		/**
	     * GetBatchDocumentL
	     * 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 list. 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** GetBatchDocumentL(TInt aIndex, TInt& aReturnDoc, TInt aCount = 1);
		
		/**
	     * GetBatchDocumentL
		 * 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 GetBatchDocumentL(TInt aIndex, MCPixNextDocumentRequestObserver& aObserver, TInt aCount = 1);
				
	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,
			EStateGetBatchDocument,
			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