/*

* Copyright (c) 2007 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: This is the client side interface declaration for the

*              predictive search server.

*

*/

#ifndef __CPSREQUESTHANDLER_H__

#define __CPSREQUESTHANDLER_H__

// INCLUDE FILES

// SYSTEM INCLUDES

#include <e32base.h>

#include <e32svr.h>

#include <s32mem.h>

#include <e32property.h>

#include <MVPbkContactLink.h>

#include <CVPbkContactManager.h>

#include <CVPbkContactStoreUriArray.h>

#include <TVPbkContactStoreUriPtr.h>

#include <MVPbkContactStoreList.h>

#include <MVPbkContactStore.h>

#include <CVPbkContactIdConverter.h>

#include <VPbkContactStoreUris.h>

#include <badesca.h>

// USER INCLUDES

#include <CPcsDefs.h>

#include <CPsClientData.h>

#include <CPsQuery.h>

#include <CPsSettings.h>

#include <CPsPattern.h>

#include <RPsSession.h>

// FORWARD DECLARATIONS

class MPsResultsObserver;

class CPsPropertyHandler;

class CPsUpdateHandler;

// CLASS DECLARATION

/**

* CPSRequestHandler

* An instance of the request handler object for the Predicitve Search application

*

* @lib PsServerClientAPI.lib

* @since S60 v3.2

*/

class CPSRequestHandler : public CActive

{

    public: // Constructors and destructors

        /**

        * NewL.

        * Two-phased constructor.

        * Creates a CPSRequestHandler object using two phase construction,

        * and return a pointer to the created object.

        *

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

        */

        IMPORT_C static CPSRequestHandler* NewL();

        /**

        * NewLC.

        * Two-phased constructor.

        * Creates a CPSRequestHandler object using two phase construction,

        * and return a pointer to the created object.

        *

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

        */

        IMPORT_C static CPSRequestHandler* NewLC();

        /**

        * ~CPSRequestHandler.

        * Destructor.

        * Destroys the object and release all memory objects.

        */

        virtual ~CPSRequestHandler();

    public: // New functions

        /**

        * Version.

        * Returns the predictive search server version.

        *

        * @return The current version of predictive search server.

        */

        IMPORT_C TVersion Version() const;

        /**

        * AddObserver.

        *

        * @param aObserver The object to be used to handle updates

        * from the server.

        */

        IMPORT_C void AddObserverL( MPsResultsObserver* aObserver );

        /**

        * RemoveObserverL.

        *

        * @param aObserver The object used to handle updates from the server.

        * @return KErrNone if removed.

        *         KErrNotFound if observer not added already.

        */

        IMPORT_C TInt RemoveObserver( MPsResultsObserver* aObserver );

        /**

        * SetSearchSettingsL.

        * Set the databases and fields to be included in search.

        * Databases ids are mapped to virtual phone book URLs.

        * Fields to be searched are mapped to virutal phonebook identifiers.

        *

        * @param aSettings Holds the search settings.

        */

        IMPORT_C void SetSearchSettingsL( const CPsSettings& aSettings );

        /**

        * GetAllContentsL.

        * Sends a request to the predictive search server to get all cached contents.

        * This is a asynchronous request.

        */

        IMPORT_C void GetAllContentsL();

        /**

        * SearchL.

        * Sends a request to the predictive search server.

        * This is a asynchronous request.

        *

        * @param aSearchQuery The input search query.(Length of aSearchQuery <= KPsQueryMaxLen)

        * @param aStatus      Holds the completion status of search request.

        */

        IMPORT_C void SearchL( const CPsQuery& aSearchQuery );

        /**

        * SearchL.

        * Sends a request to the predictive search server.

        * This is a asynchronous request. It considers bookmarked contacts

        * while sending the results back to the client

        *

        * @param aSearchQuery    The input search query.(Length of aSearchQuery <= KPsQueryMaxLen)

        * @param aMarkedContacts Array of marked contacts

        * @param aContactManager Contact manager instance

        */

        IMPORT_C void SearchL( const CPsQuery& aSearchQuery,

                               RPointerArray<CPsClientData>& aMarkedContacts,

                               CVPbkContactManager* aContactManager );

        /**

        * CancelSearch.

        * Cancels ongoing search.

        */

        IMPORT_C void CancelSearch();

        /**

        * LookupL.

        * Sends a request to the predictive search server.

        * Does a predictive search in aSearchData for aSearchQuery and return

        * the matches.

        * This is a synchronous request.

        *

        * @param aSearchQuery   The input search query.(Length of aSearchQuery <= KPsQueryMaxLen)

        * @param aSearchData    The input data to be searched.

        * @param aMatchSet      The list of matches.

        * @param aMatchLocation The list matched index and length of match

        */

        IMPORT_C void LookupL( const CPsQuery& aSearchQuery,

                               const TDesC& aSearchData,

                               CDesCArray& aMatchSet,

                               RArray<TPsMatchLocation>& aMatchLocation );

        /**

        * LookupMatchL.

        * Sends a request to the predictive search server.

        * Does a predictive search in aSearchData for aSearchQuery and return

        * the match string in aMatch.

        * If there is no full match aMatch will be empty (Length()==0)

        * This is a synchronous request.

        *

        * @param aSearchQuery The input search query.(Length of aSearchQuery <= KPsQueryMaxLen)

        * @param aSearchData  The input data to be searched.

        * @param aMatch       The matched result

        */

        IMPORT_C void LookupMatchL( const CPsQuery& aSearchQuery,

                                    const TDesC& aSearchData,

                                    TDes& aMatch );

        /**

        * IsLanguageSupportedL.

        * Checks if the language variant is supported by

        * the predictive search engine.

        * This is a synchronous request.

        *

        * @param aLanguage The language which has to be checked

        * @return ETrue if the language specified is supported by PS engine

        *         EFalse otherwise

        *

        */

        IMPORT_C TBool IsLanguageSupportedL( const TLanguage aLanguage );

        /**

        * GetCachingStatusL

        * Gets the status of the caching synchronously

        *

        * @param aResultsBuffer Pointer to the result buffer.

        */

        IMPORT_C TInt GetCachingStatusL( TCachingStatus& aStatus );

        /**

        * ConvertToVpbkLinkLC.

        * Extract the VPBK contact link associated with the search result.

        * This is a synchronous request.

        *

        * @param aSearchResult PS result for which contact link is required.

        * @param aContactManager An instance of contact manager used for link extraction.

        * @return The contact link.

        */

        IMPORT_C MVPbkContactLink* ConvertToVpbkLinkLC( const CPsClientData& aSearchResult,

                                                        CVPbkContactManager& aContactManager );

        /**

        * GetDataOrderL.

        * This function returns the list of supported data fields (mapped to VPbk identifiers)

        * supported by a datastore.

        * This is a synchronous request.

        *

        * @param aDataStore The data store URI.

        * @param aDataOrder This array has the field identifiers returned from the server.

        */

        IMPORT_C void GetDataOrderL( const TDesC& aDataStore, RArray<TInt>& aDataOrder );

        /**

        * GetSortOrderL.

        * This function returns the sort order of data fields (mapped to VPbk identifiers)

        * set on a datastore.

        * This is a synchronous request.

        *

        * @param aDataStore The data store URI.

        * @param aSortOrder This array has the field identifiers returned from the server.

        */

        IMPORT_C void GetSortOrderL( const TDesC& aDataStore, RArray<TInt>& aSortOrder );

        /**

        * ChangeSortOrderL.

        * This function sets the sort order of data fields (mapped to VPbk identifiers)

        * on a datastore.

        * This is a synchronous request.

        *

        * @param aDataStore The data store URI.

        * @param aSortOrder This array has the field identifiers to be set for this store.

        */

        IMPORT_C void ChangeSortOrderL( const TDesC& aDataStore, RArray<TInt>& aSortOrder );

        /**

        * GetAdaptiveGridCharactersL.

        * This is a support method for Adaptive Search functionality.

        * As Predictive Search Engine is well suited for keeping an maintaining data

        * structures related to contacts and updated according to contacts

        * additions/modifications/deletions, like it is done already in Predictive Search

        * Engine.

        *

        * @param aDataStores   The data store URIs.

        * @param aSearchText   The text in the find box.

        * @param aCompanyName  The info if Company Name is required.

        * @param aAdaptiveGrid The returned Adaptive Grid.

        */

        IMPORT_C void GetAdaptiveGridCharactersL( const MDesCArray& aDataStores,

                                                  const TDesC& aSearchText,

                                                  const TBool aCompanyName,

                                                  TDes& aAdaptiveGrid );

        /**

        * ShutdownServerL

        * Shuts down the predictive search engine.

        *

        * CAUTION: Shutdown of predictive search server shouldn't be done for each

        * session. It should be done only when the search engine needs to be

        * completely shutdown.

        */

        IMPORT_C void ShutdownServerL();

    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();

    public:

        /**

        * Notify observers about the cahcing status

        */

        void NotifyCachingStatus( TCachingStatus aStatus, TInt aError );

    private: // Constructors and destructors

        /**

        * CPSRequestHandler.

        * Performs the first phase of two phase construction.

        */

        CPSRequestHandler();

        /**

        * ConstructL.

        * Performs the second phase construction of a

        * CPSRequestHandler object.

        */

        void ConstructL();

    private: // Internal data handlers

        /**

        * ParseResultsL.

        * Parses the results buffer and converts them to data elements.

        */

        void HandleSearchResultsL();

        /**

        * HandleBufferOverFlowL.

        * Handles internal buffer overflow event.

        */

        void HandleBufferOverFlowL();

        /**

        * HandleErrorL.

        * Handles error events.

        */

        void HandleErrorL(TInt aErrorCode);

        /**

        * AddMarkedContacts

        * Filters the bookmark results and adds them to final search result set

        */

        TInt AddMarkedContactsL(RPointerArray<CPsClientData>& searchResults);

        /**

        * RunSearchFromBufferL

        * Runs search if search query buffer ( iPendingSearchQueryBuffer ) is not empty

        */

        void RunSearchFromBufferL();

    private: // Data

        /**

        * iSession, the predictive search server session.

        */

        RPsSession iSession;

        /**

        * iObservers, observers which handles updates from the server.

        */

        RPointerArray<MPsResultsObserver> iObservers;

        /**

        * iSearchQueryBuffer, the buffer that holds the search query.

        */

        HBufC8* iSearchQueryBuffer;

        /**

         * iPendingSearchQueryBuffer, the buffer that holds the pending search query.

        */

        HBufC8* iPendingSearchQueryBuffer;

        /**

        * iSearchDataBuffer, the buffer that holds the search data.

        */

        HBufC8* iSearchDataBuffer;

        /**

        * iSearchResultsBuffer, the buffer that holds the search results.

        */

        HBufC8* iSearchResultsBuffer;

        /**

        * iConverter, instance of contact id converter

        */

        CVPbkContactIdConverter* iConverter;

        /**

        * iPropertyHandler, the handler to property which is asynchronously monitored

        */

        CPsPropertyHandler* iPropertyHandler;

        /**

        * iContactAddedHandler, handler for reacting to contact being added to cache

        */

        CPsUpdateHandler* iContactAddedHandler;

        /**

        * iContactRemovedHandler, handler for reacting to contact being removed from cache

        */

        CPsUpdateHandler* iContactRemovedHandler;

        /**

        * iContactModifiedHandler, handler for reacting to contact being modified in cache

        */

        CPsUpdateHandler* iContactModifiedHandler;

        /**

        * Not Owned

        * iBookMarkContactManager, contact manager reference received from the client

        * To be used only for handling marked contacts.

        */

        CVPbkContactManager* iBookMarkContactManager;

        /**

        * iMarkedContacts, stores the bookmarked contacts if any, sent by the client

        */

        RPointerArray<CPsClientData> iMarkedContacts;

        /**

        * ETrue, if search request was cancelled

        */

        TBool iSearchRequestCancelled;

};

#endif //__CPSREQUESTHANDLER_H__

// End of File