1 /*

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

    15 *              predictive search server.

    16 *

    17 */

    18 

    19 

    20 #ifndef __CPSREQUESTHANDLER_H__

    21 #define __CPSREQUESTHANDLER_H__

    22 

    23 // INCLUDE FILES

    24 

    25 // SYSTEM INCLUDES

    26 #include <e32base.h>

    27 #include <e32svr.h>

    28 #include <s32mem.h>

    29 #include <e32property.h>

    30 #include <MVPbkContactLink.h>

    31 #include <CVPbkContactManager.h>

    32 #include <CVPbkContactStoreUriArray.h>

    33 #include <TVPbkContactStoreUriPtr.h>

    34 #include <MVPbkContactStoreList.h>

    35 #include <MVPbkContactStore.h>

    36 #include <CVPbkContactIdConverter.h>

    37 #include <VPbkContactStoreUris.h>

    38 #include <badesca.h>

    39 

    40 // USER INCLUDES

    41 #include <CPcsDefs.h>

    42 #include <CPsClientData.h>

    43 #include <CPsQuery.h>

    44 #include <CPsSettings.h>

    45 #include <CPsPattern.h>

    46 #include <RPsSession.h>

    47 

    48 // FORWARD DECLARATIONS

    49 class MPsResultsObserver;

    50 class CPsPropertyHandler;

    51 class CPsUpdateHandler;

    52 

    53 

    54 // CLASS DECLARATION

    55 /**

    56 * CPSRequestHandler

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

    58 *

    59 * @lib PsServerClientAPI.lib

    60 * @since S60 v3.2

    61 */

    62 class CPSRequestHandler : public CActive

    63 {

    64 

    65     public: // Constructors and destructors

    66 

    67         /**

    68         * NewL.

    69         * Two-phased constructor.

    70         * Creates a CPSRequestHandler object using two phase construction,

    71         * and return a pointer to the created object.

    72         *

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

    74         */

    75         IMPORT_C static CPSRequestHandler* NewL();

    76 

    77         /**

    78         * NewLC.

    79         * Two-phased constructor.

    80         * Creates a CPSRequestHandler object using two phase construction,

    81         * and return a pointer to the created object.

    82         *

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

    84         */

    85         IMPORT_C static CPSRequestHandler* NewLC();

    86 

    87         /**

    88         * ~CPSRequestHandler.

    89         * Destructor.

    90         * Destroys the object and release all memory objects.

    91         */

    92         virtual ~CPSRequestHandler();

    93 

    94     public: // New functions

    95 

    96         /**

    97         * Version.

    98         * Returns the predictive search server version.

    99         *

   100         * @return The current version of predictive search server.

   101         */

   102         IMPORT_C TVersion Version() const;

   103 

   104         /**

   105         * AddObserver.

   106         *

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

   108         * from the server.

   109         */

   110         IMPORT_C void AddObserverL( MPsResultsObserver* aObserver );

   111 

   112         /**

   113         * RemoveObserverL.

   114         *

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

   116         * @return KErrNone if removed.

   117         *         KErrNotFound if observer not added already.

   118         */

   119         IMPORT_C TInt RemoveObserver( MPsResultsObserver* aObserver );

   120 

   121         /**

   122         * SetSearchSettingsL.

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

   124         * Databases ids are mapped to virtual phone book URLs.

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

   126         *

   127         * @param aSettings Holds the search settings.

   128         */

   129         IMPORT_C void SetSearchSettingsL( const CPsSettings& aSettings );

   130 

   131         /**

   132         * GetAllContentsL.

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

   134         * This is a asynchronous request.

   135         */

   136         IMPORT_C void GetAllContentsL();

   137 

   138         /**

   139         * SearchL.

   140         * Sends a request to the predictive search server.

   141         * This is a asynchronous request.

   142         *

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

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

   145         */

   146         IMPORT_C void SearchL( const CPsQuery& aSearchQuery );

   147 

   148         /**

   149         * SearchL.

   150         * Sends a request to the predictive search server.

   151         * This is a asynchronous request. It considers bookmarked contacts

   152         * while sending the results back to the client

   153         *

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

   155         * @param aMarkedContacts Array of marked contacts

   156         * @param aContactManager Contact manager instance

   157         */

   158         IMPORT_C void SearchL( const CPsQuery& aSearchQuery,

   159                                RPointerArray<CPsClientData>& aMarkedContacts,

   160                                CVPbkContactManager* aContactManager );

   161 

   162         /**

   163         * CancelSearch.

   164         * Cancels ongoing search.

   165         */

   166         IMPORT_C void CancelSearch();

   167 

   168         /**

   169         * LookupL.

   170         * Sends a request to the predictive search server.

   171         * Does a predictive search in aSearchData for aSearchQuery and return

   172         * the matches.

   173         * This is a synchronous request.

   174         *

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

   176         * @param aSearchData    The input data to be searched.

   177         * @param aMatchSet      The list of matches.

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

   179         */

   180         IMPORT_C void LookupL( const CPsQuery& aSearchQuery,

   181                                const TDesC& aSearchData,

   182                                CDesCArray& aMatchSet,

   183                                RArray<TPsMatchLocation>& aMatchLocation );

   184 

   185         /**

   186         * LookupMatchL.

   187         * Sends a request to the predictive search server.

   188         * Does a predictive search in aSearchData for aSearchQuery and return

   189         * the match string in aMatch.

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

   191         * This is a synchronous request.

   192         *

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

   194         * @param aSearchData  The input data to be searched.

   195         * @param aMatch       The matched result

   196         */

   197         IMPORT_C void LookupMatchL( const CPsQuery& aSearchQuery,

   198                                     const TDesC& aSearchData,

   199                                     TDes& aMatch );

   200 

   201         /**

   202         * IsLanguageSupportedL.

   203         * Checks if the language variant is supported by

   204         * the predictive search engine.

   205         * This is a synchronous request.

   206         *

   207         * @param aLanguage The language which has to be checked

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

   209         *         EFalse otherwise

   210         *

   211         */

   212         IMPORT_C TBool IsLanguageSupportedL( const TLanguage aLanguage );

   213 

   214         /**

   215         * GetCachingStatusL

   216         * Gets the status of the caching synchronously

   217         *

   218         * @param aResultsBuffer Pointer to the result buffer.

   219         */

   220         IMPORT_C TInt GetCachingStatusL( TCachingStatus& aStatus );

   221 

   222         /**

   223         * ConvertToVpbkLinkLC.

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

   225         * This is a synchronous request.

   226         *

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

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

   229         * @return The contact link.

   230         */

   231         IMPORT_C MVPbkContactLink* ConvertToVpbkLinkLC( const CPsClientData& aSearchResult,

   232                                                         CVPbkContactManager& aContactManager );

   233 

   234         /**

   235         * GetDataOrderL.

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

   237         * supported by a datastore.

   238         * This is a synchronous request.

   239         *

   240         * @param aDataStore The data store URI.

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

   242         */

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

   244 

   245         /**

   246         * GetSortOrderL.

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

   248         * set on a datastore.

   249         * This is a synchronous request.

   250         *

   251         * @param aDataStore The data store URI.

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

   253         */

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

   255 

   256         /**

   257         * ChangeSortOrderL.

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

   259         * on a datastore.

   260         * This is a synchronous request.

   261         *

   262         * @param aDataStore The data store URI.

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

   264         */

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

   266 

   267         /**

   268         * GetAdaptiveGridCharactersL.

   269         * This is a support method for Adaptive Search functionality.

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

   271         * structures related to contacts and updated according to contacts

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

   273         * Engine.

   274         *

   275         * @param aDataStores   The data store URIs.

   276         * @param aSearchText   The text in the find box.

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

   278         * @param aAdaptiveGrid The returned Adaptive Grid.

   279         */

   280         IMPORT_C void GetAdaptiveGridCharactersL( const MDesCArray& aDataStores,

   281                                                   const TDesC& aSearchText,

   282                                                   const TBool aCompanyName,

   283                                                   TDes& aAdaptiveGrid );

   284 

   285         /**

   286         * ShutdownServerL

   287         * Shuts down the predictive search engine.

   288         *

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

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

   291         * completely shutdown.

   292         */

   293         IMPORT_C void ShutdownServerL();

   294 

   295     protected: // Functions from base classes

   296 

   297         /**

   298         * From CActive, RunL.

   299         * Callback function.

   300         * Invoked to handle responses from the server.

   301         */

   302         void RunL();

   303 

   304         /**

   305         * From CActive, DoCancel.

   306         * Cancels any outstanding operation.

   307         */

   308         void DoCancel();

   309 

   310     public:

   311 

   312         /**

   313         * Notify observers about the cahcing status

   314         */

   315         void NotifyCachingStatus( TCachingStatus aStatus, TInt aError );

   316 

   317     private: // Constructors and destructors

   318 

   319         /**

   320         * CPSRequestHandler.

   321         * Performs the first phase of two phase construction.

   322         */

   323         CPSRequestHandler();

   324 

   325         /**

   326         * ConstructL.

   327         * Performs the second phase construction of a

   328         * CPSRequestHandler object.

   329         */

   330         void ConstructL();

   331 

   332     private: // Internal data handlers

   333 

   334         /**

   335         * ParseResultsL.

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

   337         */

   338         void HandleSearchResultsL();

   339 

   340         /**

   341         * HandleBufferOverFlowL.

   342         * Handles internal buffer overflow event.

   343         */

   344         void HandleBufferOverFlowL();

   345 

   346         /**

   347         * HandleErrorL.

   348         * Handles error events.

   349         */

   350         void HandleErrorL(TInt aErrorCode);

   351 

   352         /**

   353         * AddMarkedContacts

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

   355         */

   356         TInt AddMarkedContactsL(RPointerArray<CPsClientData>& searchResults);

   357 

   358         /**

   359         * RunSearchFromBufferL

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

   361         */

   362         void RunSearchFromBufferL();

   363 

   364     private: // Data

   365 

   366         /**

   367         * iSession, the predictive search server session.

   368         */

   369         RPsSession iSession;

   370 

   371         /**

   372         * iObservers, observers which handles updates from the server.

   373         */

   374         RPointerArray<MPsResultsObserver> iObservers;

   375 

   376         /**

   377         * iSearchQueryBuffer, the buffer that holds the search query.

   378         */

   379         HBufC8* iSearchQueryBuffer;

   380 

   381         /**

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

   383         */

   384         HBufC8* iPendingSearchQueryBuffer;

   385 

   386         /**

   387         * iSearchDataBuffer, the buffer that holds the search data.

   388         */

   389         HBufC8* iSearchDataBuffer;

   390 

   391         /**

   392         * iSearchResultsBuffer, the buffer that holds the search results.

   393         */

   394         HBufC8* iSearchResultsBuffer;

   395 

   396         /**

   397         * iConverter, instance of contact id converter

   398         */

   399         CVPbkContactIdConverter* iConverter;

   400 

   401         /**

   402         * iPropertyHandler, the handler to property which is asynchronously monitored

   403         */

   404         CPsPropertyHandler* iPropertyHandler;

   405 

   406         /**

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

   408         */

   409         CPsUpdateHandler* iContactAddedHandler;

   410 

   411         /**

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

   413         */

   414         CPsUpdateHandler* iContactRemovedHandler;

   415 

   416         /**

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

   418         */

   419         CPsUpdateHandler* iContactModifiedHandler;

   420 

   421         /**

   422         * Not Owned

   423         * iBookMarkContactManager, contact manager reference received from the client

   424         * To be used only for handling marked contacts.

   425         */

   426         CVPbkContactManager* iBookMarkContactManager;

   427 

   428         /**

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

   430         */

   431         RPointerArray<CPsClientData> iMarkedContacts;

   432 

   433         /**

   434         * ETrue, if search request was cancelled

   435         */

   436         TBool iSearchRequestCancelled;

   437 

   438 };

   439 

   440 

   441 #endif //__CPSREQUESTHANDLER_H__

   442 

   443 // End of File