1 /*

     2 * Copyright (c) 2008 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:  Contact metching class

    15 *

    16 */

    17 

    18 

    19 #ifndef HGCONTACTMATCHER_H

    20 #define HGCONTACTMATCHER_H

    21 

    22 // System includes

    23 #include <e32base.h>

    24 #include <e32std.h>

    25 #include <bamdesca.h>

    26 #include <badesca.h>

    27 

    28 #include <MVPbkSingleContactOperationObserver.h>

    29 #include <MVPbkContactStoreListObserver.h>

    30 #include <MVPbkContactFindObserver.h>

    31 #include <MVPbkFieldType.h>

    32 #include <CVPbkPhoneNumberMatchStrategy.h>

    33 #include <MVPbkContactFindFromStoresObserver.h>

    34 #include <MVPbkContactViewObserver.h>

    35 

    36 #include <finditemengine.h>

    37 

    38 // Classes referenced

    39 class RFs;

    40 class CActiveSchedulerWait;

    41 class CVPbkContactManager;

    42 class MVPbkContactLink;

    43 class CVPbkContactLinkArray;

    44 class CVPbkContactStoreUriArray;

    45 class MVPbkContactOperationBase;

    46 class MVPbkFieldType;

    47 class MVPbkFieldTypeList;

    48 class MVPbkStoreContact;

    49 class MVPbkStoreContactField;

    50 class CVPbkFieldTypeRefsList;

    51 class MVPbkStoreContactFieldCollection;

    52 class MVPbkContactFieldSelector;

    53 

    54 class CPbk2SortOrderManager;

    55 class MPbk2ContactNameFormatter;

    56 class CFbsBitmap;

    57 

    58 /**

    59  * Observer interface for contact added/changed/deleted notifications.

    60  */

    61 class MHgCtxContactObserver

    62     {

    63 public:

    64     /**

    65      * Called when a contact is added, changed, or deleted.

    66      */

    67     virtual void HandleContactEventL() = 0;

    68     };

    69     

    70 /**

    71 * CHgCtxContactMatcher class is an API for contact matching.

    72 *

    73 * Before a method starts executing a Virtual Phonebook operation,

    74 * it checks if there's an older asynchronous operation already in execution.

    75 * If there is, synchronous methods leave with error code KErrInUse.

    76 * Asynchronous methods complete the request with same error code.

    77 *

    78 * If phone backup/restore has been detected, using methods which

    79 * require Virtual Phonebook is not possible normally. 

    80 * Instead those methods leave with error code KErrAccessDenied.

    81 * Once EStoreBackupRestoreCompleted event has been received,

    82 * methods can be called normally.

    83 *

    84 * @lib hgcontextservicesutils.lib

    85 */

    86 

    87 NONSHARABLE_CLASS( CHgCtxContactMatcher ) : public CBase,

    88 	public MVPbkSingleContactOperationObserver,

    89 	public MVPbkContactStoreListObserver,

    90 	public MVPbkContactFindObserver, 

    91 	public MVPbkContactFindFromStoresObserver,

    92 	public MVPbkContactViewObserver

    93     {

    94 public: // Construct & destruct

    95 

    96     /**

    97     * Two-phase constructor for CHgCtxContactMatcher class.

    98     *

    99     * @param  aFsSession File server session.

   100     *

   101     * @return CHgCtxContactMatcher* Pointer to newly created instance.

   102     */

   103     IMPORT_C static CHgCtxContactMatcher* NewL( RFs* aFsSession = 0 );

   104 

   105     /**

   106     * Two-phase constructor for CHgCtxContactMatcher class.

   107     * Like NewL(), but also places instance on cleanup stack.

   108     *

   109     * @return CHgCtxContactMatcher* Pointer to newly created instance.

   110     */

   111     IMPORT_C static CHgCtxContactMatcher* NewLC( RFs* aFsSession = 0 );

   112 

   113     /**

   114     * C++ destructor.

   115     */

   116     IMPORT_C ~CHgCtxContactMatcher();

   117 

   118 private: // Internal construct

   119 

   120     /**

   121     * C++ Constructor.

   122     */

   123     CHgCtxContactMatcher( RFs* aFsSession );

   124 

   125     /**

   126     * Second phase constructor

   127     */

   128     void ConstructL();

   129 

   130 public: // API methods

   131 

   132     /**

   133     * Opens one or more contact stores for future match operations.

   134     *

   135     * @param aUriArray  Array of contact store URIs to be opened.

   136     *

   137     * @exception KErrNotSupported when none of the stores opens

   138     * @exception KErrGeneral if some stores are already open

   139     */

   140     IMPORT_C void OpenStoreL( const CVPbkContactStoreUriArray& aUriArray );

   141 

   142     /**

   143     * Opens one or more contact stores for future match operations.

   144     * Asynchronous version.

   145     *

   146     * @param aUriArray  Array of contact store URIs to be opened.

   147     * @param aStatus  Completion status of the request.

   148     *                 KErrNone - at least one store opened successfully

   149     *                 KErrNotSupported - all stores failed to open

   150     *                 KErrGeneral - if some stores are already open

   151     */		    

   152     IMPORT_C void OpenStoreL( const CVPbkContactStoreUriArray& aUriArray,

   153         TRequestStatus& aStatus );			    

   154 

   155     /**

   156     * Opens all contact stores for future match operations.

   157     * NOTE: does not open OwnNumber store.

   158     *

   159     * @exception KErrNotSupported when none of the stores opens

   160     * @exception KErrGeneral if some stores are already open

   161     */

   162     IMPORT_C void OpenAllStoresL();

   163 

   164     /**

   165     * Opens all contact stores for future match operations.

   166     * Asynchronous version.

   167     * NOTE: does not open OwnNumber store.

   168     *

   169     * @param aStatus  Completion status of the request.

   170     *                 KErrNone - at least one store opened successfully

   171     *                 KErrNotSupported - all stores failed to open

   172     *                 KErrGeneral - if some stores are already open

   173     */

   174     IMPORT_C void OpenAllStoresL( TRequestStatus& aStatus );			

   175 

   176     /**

   177     * Opens default contact stores for future match operations.

   178     * Used to find local aliases to phone numbers and email addresses

   179     * NOTE: does not open OwnNumber store or fixed dialing store

   180     * Opens the stores in the default preference order

   181     *

   182     * @exception KErrNotSupported when none of the stores opens

   183     * @exception KErrGeneral if some stores are already open

   184     */

   185     IMPORT_C void OpenDefaultMatchStoresL();

   186 

   187     /**

   188     * Opens default contact stores for future match operations.

   189     * Used to find local aliases to phone numbers and email addresses

   190     * Asynchronous version.

   191     * NOTE: does not open OwnNumber store or fixed dialing store

   192     * Opens the stores in the default preference order

   193     *

   194     * @param aStatus  Completion status of the request.

   195     *                 KErrNone - at least one store opened successfully

   196     *                 KErrNotSupported - all stores failed to open

   197     *                 KErrGeneral - if some stores are already open

   198     */

   199     IMPORT_C void OpenDefaultMatchStoresL( TRequestStatus& aStatus );

   200 

   201     /**

   202     * Opens all OwnNumber stores for future match operations.

   203     *

   204     * @exception KErrNotSupported when none of the stores opens

   205     * @exception KErrGeneral if some stores are already open

   206     */

   207     IMPORT_C void OpenOwnNumberStoresL();

   208 

   209     /**

   210     * Opens all OwnNumber stores for future match operations.       

   211     *

   212     * @param aStatus  Completion status of the request.

   213     *                 KErrNone - at least one store opened successfully

   214     *                 KErrNotSupported - all stores failed to open

   215     *                 KErrGeneral - if some stores are already open

   216     */	

   217     IMPORT_C void OpenOwnNumberStoresL( TRequestStatus& aStatus );	

   218 

   219     /**

   220     * Closes all currently open contact stores

   221     * including OwnNumber stores.

   222     *

   223     * @return Leaves on error.

   224     */

   225     IMPORT_C void CloseStoresL();

   226 

   227     /**

   228     * Determines whether a phone number is OwnNumber. Synchronous version.

   229     * The method searches for the number from currently open stores.

   230     * In order to use SIM's ISDN store, it should be the only open store.

   231     * Can be opened with OpenOwnNumberStoresL().

   232     *

   233     * @param aSearch  Phone number to search for

   234     * @param aResult  Boolean result.

   235     */

   236     IMPORT_C void IsOwnNumberL( const TDesC& aSearch, TBool& aResult );

   237 

   238     /**

   239     * Determines whether a phone number is OwnNumber. Asynchronous version.

   240     * The method searches for the number from currently open stores.

   241     * In order to use SIM's ISDN store, it should be the only open store.

   242     * Can be opened with OpenOwnNumberStoresL().

   243     *

   244     * @param aSearch  Phone number to search for

   245     * @param aStatus  Request status containing the result and 

   246     *                 possible error code.

   247     *                 KErrNone     = TRUE,

   248     *                 KErrNotFound = FALSE,

   249     *                 other value  = system wide error code.        

   250     */

   251     IMPORT_C void IsOwnNumberL( const TDesC& aSearch, TRequestStatus& aStatus );

   252 

   253     /**

   254     * Finds contacts with phone numbers that match the search string.

   255     * Synchronous version.

   256     * Contacts are searched from all currently open contact stores.

   257     * Matching is done from the end of the phone number.

   258     * Note: If the search string is shorter than 7 digits, matching from

   259     * Phone memory contact store works ONLY if the phone number is

   260     * exactly the same as the search string.

   261     * Example:

   262     * Search string "567" would find phone number "567", but not "1234567".

   263     * From SIM stores both numbers would be found.

   264     *

   265     * @param aSearch  Search string

   266     * @param aDigits  Number of digits to match from the end of phone number.

   267     * @param aFlags   Search all or stop at first match.

   268     *                 See enum values from CVPbkPhoneNumberMatchStrategy.h

   269     * @param aLinkArray  Links to matching contacts are returned in this

   270     *                 array that method caller provides.

   271     *

   272     * @return KErrNone = success, otherwise an error code. ,,list of codes

   273     */

   274     IMPORT_C void MatchPhoneNumberL( const TDesC& aSearch, TInt aDigits,

   275         CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags aFlags,

   276         CVPbkContactLinkArray& aLinkArray );

   277 

   278     /**

   279     * Finds contacts with phone numbers that match the search string.

   280     * Asynchronous version.

   281     * Searching is done according to parameters like in the synchronous version,

   282     * but status code is returned in aStatus.

   283     *

   284     * @param aStatus  Completion status of the request.

   285     *                 Values: KErrNone = success, otherwise an error code.

   286     */

   287     IMPORT_C void MatchPhoneNumberL( const TDesC& aSearch, TInt aDigits,

   288         CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags aFlags,

   289         CVPbkContactLinkArray& aLinkArray, TRequestStatus& aStatus );

   290 

   291     /**

   292     * Returns the global list of possible field types.

   293     *

   294     * @return List of field types

   295     */

   296     IMPORT_C const MVPbkFieldTypeList& FieldTypes() const;

   297                 

   298     /**

   299     * Gets a store contact from a contact link.

   300     * @param aContactLink  The link from which store contact should be returned.

   301     * @param aStoreContact Pointer to store contact.

   302     *                      Client must take the ownership immediately.

   303     */

   304     IMPORT_C void GetStoreContactL( const MVPbkContactLink& aContactLink,

   305         MVPbkStoreContact** aStoreContact );

   306         

   307     /**

   308     * Gets a store contact from a contact link.

   309     * Asynchronous version.

   310     * Parameters like in the synchronous version,

   311     * but status code is returned in aStatus.

   312     *

   313     * @param aStatus  Completion status of the request.

   314     *                 Values: KErrNone = success, otherwise an error code.

   315     */

   316     IMPORT_C void GetStoreContactL( const MVPbkContactLink& aContactLink,

   317         MVPbkStoreContact** aStoreContact, TRequestStatus& aStatus );

   318 

   319     /**

   320     * Returns a pointer to contact's field data of given field type.

   321     * If the field type isn't found from contact, return value is KNullDesC.

   322     * NOTE: this works only for field types of storage type 

   323     * EVPbkFieldStorageTypeText.

   324     * For other types, leaves with error code KErrArgument.

   325     *

   326     * @param  aStoreContact The contact from which field data should be returned.

   327     * @param  aFieldType    Field's type.

   328     * @return TPtrC pointer to field's data.

   329     */

   330     IMPORT_C TPtrC GetFieldDataTextL( const MVPbkStoreContact& aStoreContact,

   331         const MVPbkFieldType& aFieldType ) const; 

   332 

   333     /**

   334     * Returns a pointer to contact's field data of given field type.

   335     * If the field type isn't found from contact, return value is

   336     * "1.1.1111". (d.m.yyyy).

   337     * NOTE: this works only for field types of storage type 

   338     * EVPbkFieldStorageTypeDateTime.

   339     * For other types, leaves with error code KErrArgument.

   340     *

   341     * @param  aStoreContact The contact from which field data should be returned.

   342     * @param  aFieldType    Field's type.

   343     * @return TTime pointer to field's data.

   344     */

   345     IMPORT_C TTime GetFieldDataDateTimeL( const MVPbkStoreContact& aStoreContact,

   346         const MVPbkFieldType& aFieldType ) const; 

   347 

   348     /**

   349     * Returns a pointer to contact's field data of given field type.

   350     * If the field type isn't found from contact, return value is KNullDesC8.

   351     * NOTE: this works only for field types of storage type 

   352     * EVPbkFieldStorageTypeBinary.

   353     * For other types, leaves with error code KErrArgument.

   354     *

   355     * @param  aStoreContact The contact from which field data should be returned.

   356     * @param  aFieldType    Field's type.

   357     * @return TPtrC8 pointer to field's data.

   358     */

   359     IMPORT_C TPtrC8 GetFieldDataBinaryL(  const MVPbkStoreContact& aStoreContact,

   360         const MVPbkFieldType& aFieldType ) const; 		    		    

   361 

   362     /**

   363     * Cancels asynchronous operation.

   364     */	

   365     IMPORT_C void CancelOperation();

   366 

   367     /**

   368     * Returns the used contact store list, needed for e.g. aiw fetch

   369     * @return The used contact store list

   370     */

   371     IMPORT_C MVPbkContactStoreList& GetContactStoresL();

   372 

   373     /**

   374     * Returns the name of the contact in the same format as MPbk2ContactNameFormatter

   375     * @param  aFieldCollection The fieldcollection of the contact

   376     * @return HBufC* the name of the contact or null

   377     */

   378     IMPORT_C HBufC* GetNameL(

   379         MVPbkStoreContactFieldCollection& aFieldCollection );

   380 

   381     /**

   382     * Returns reference to the contactmanager

   383     * @return reference to the contact manager

   384     */

   385     IMPORT_C CVPbkContactManager& GetContactManager();

   386     

   387     /**

   388     * Finds contacts with field data that match the search string.

   389     * Contacts are searched from all currently open contact stores.

   390     * Matching is done from field types given by the method caller.

   391     * The list of all possible field types can be fetched from the wrapper

   392     * using FieldTypes().

   393     *

   394     * @param aSearch  Search string

   395     * @param aFieldTypes  List of field types included in matching.

   396     * @param aLinkArray  Links to matching contacts are returned 

   397     *                    in this array that method caller provides.

   398     *

   399     * @return KErrNone = success, otherwise an error code. ,,list of codes

   400     */

   401     IMPORT_C void MatchDataL( const TDesC& aSearch, const MVPbkFieldTypeList& aFieldTypes, 		

   402         CVPbkContactLinkArray& aLinkArray);

   403 

   404     /**

   405     * Finds contacts with field data that match the search string.

   406     * Contacts are searched from all currently open contact stores.

   407     * Matching is done from field types given by the method caller.

   408     * The list of all possible field types can be fetched from the wrapper

   409     * using FieldTypes().

   410     *

   411     * @param aSearchStrings  Search strings

   412     * @param aFieldTypes  List of field types included in matching.

   413     * @param aLinkArray  Links to matching contacts are returned

   414     *                    in this array that method caller provides.

   415     * @param aWordParserCallBack is the callback function to the parser

   416     *

   417     * @return KErrNone = success, otherwise an error code.

   418     */

   419     IMPORT_C void MatchDataL( const MDesC16Array& aSearchStrings, 

   420         const MVPbkFieldTypeList& aFieldTypes,

   421         CVPbkContactLinkArray& aLinkArray,

   422         const TCallBack& aWordParserCallBack );		   

   423 

   424     /**

   425     * Finds contacts with field data that match the search string.

   426     * Asynchronous version.

   427     * Searching is done according to parameters like in the synchronous version,

   428     * but status code is returned in aStatus.

   429     *

   430     * @param aStatus  Completion status of the request.

   431     *                 Values: KErrNone = success, otherwise an error code.

   432     */

   433     IMPORT_C void MatchDataL( const TDesC& aSearch, const MVPbkFieldTypeList& aFieldTypes, 		

   434         CVPbkContactLinkArray& aLinkArray, TRequestStatus& aStatus );

   435         

   436      /**

   437     * Returns reference to the contact name formatter. Object is created if not used earlier.

   438     * @return reference to the contact name formatter

   439     */

   440     IMPORT_C MPbk2ContactNameFormatter& ContactNameFormatterL();

   441     

   442     /**

   443      * Splits the input to words and then performs a MatchDataL using the same

   444      * splitter callback function.

   445      *

   446      * LookupL and this are the preferred functions to do text-based lookups from Hg code.

   447      *

   448      * @see MatchDataL

   449      * @see LookupL

   450      */

   451     IMPORT_C void SplitAndMatchL( const TDesC& aData,

   452         const MVPbkFieldTypeList& aFieldTypes,

   453         CVPbkContactLinkArray& aLinkArray );

   454         

   455     /**

   456      * Registers for getting notifications when a contact is added, changed, or deleted.

   457      * Does nothing if already added.

   458      * @param   aObserver   ref to observer

   459      */

   460     IMPORT_C void RegisterContactObserverL( MHgCtxContactObserver& aObserver );

   461     

   462     /**

   463      * Unregisters the given observer.

   464      * Does nothing if the given observer has not been registered before.

   465      * @param   aObserver   ref to observer

   466      */

   467     IMPORT_C void UnregisterContactObserver( MHgCtxContactObserver& aObserver );

   468     

   469     /**

   470      * Looks up a contact based on

   471      *   - name, or

   472      *   - phone number, or

   473      *   - email address, or

   474      *   - service id

   475      *

   476      * Also handles the "name <number>" or "name <email>" format.

   477      *

   478      * For service IDs the full uri must be given, e.g. if a contact

   479      * has an Ovi ID in phonebook set to "somebody" then the search will

   480      * only succeed if aData contains "Ovi:somebody" (unless of course

   481      * the string "somebody" matches some name fields).

   482      *

   483      * @param   aData           name or phone number of email address

   484      * @param   aLinkArray      array to which the result links are added,

   485      *                          no items are appended if not found

   486      */

   487     IMPORT_C void LookupL( const TDesC& aData, CVPbkContactLinkArray& aLinkArray );

   488 

   489     /**

   490     * Returns the phone numbers of the contact.

   491     * @param  aFieldCollection The fieldcollection of the contact

   492     * @param    aArray         Phone numbers are appended to this. (not resetted)

   493     */

   494     IMPORT_C void GetNumbersL(

   495         MVPbkStoreContactFieldCollection& aFieldCollection,

   496         CDesCArray& aArray );

   497  

   498     /**

   499     * Returns the email addresses of the contact.

   500     * @param  aFieldCollection The fieldcollection of the contact

   501     * @param    aArray          Email addresses are appended to this. (not resetted)

   502     */

   503     IMPORT_C void GetEmailAddressesL(

   504         MVPbkStoreContactFieldCollection& aFieldCollection,

   505         CDesCArray& aArray );

   506 

   507     /**

   508     * Constructs the address (e.g. street, city, country) for the contact.

   509     * The elements are combined into one string, using space as separator.

   510     * aArray will have 0-3 items appended: nothing, or general and/or work and/or home address.

   511     * @param  aFieldCollection The fieldcollection of the contact

   512     * @param  aArray           Addresses are appended to this. (not resetted)

   513     */

   514     IMPORT_C void GetAddressesL(

   515         MVPbkStoreContactFieldCollection& aFieldCollection,

   516         CDesCArray& aArray );

   517 

   518     enum TWebAddressesType

   519         {

   520         EWebAddresses, //for general web adress

   521         EWebAddressesHome, //for home web adress

   522         EWebAddressesWork //for work web adress

   523         };

   524     

   525     /**

   526     * Gets the prefered web address for the contact.

   527     * 

   528     * aArray can have 0 or more items appended.

   529     * 

   530     * @param  aFieldCollection The fieldcollection of the contact

   531     * @param  aArray           Web addresses are appended to this. (not resetted)

   532     * @param  aType            Determinates which web adress return, @see TWebAddressesType

   533     */

   534     IMPORT_C void GetWebAddressesL(

   535         MVPbkStoreContactFieldCollection& aFieldCollection,

   536         CDesCArray& aArray,

   537         TWebAddressesType aType );   

   538       

   539     

   540     /**

   541     * Gets the thumbnail for a contact.

   542     * @param  aFieldCollection The fieldcollection of the contact

   543     * @return bitmap or null (null if not found)

   544     */

   545     IMPORT_C CFbsBitmap* GetThumbnailL(

   546         MVPbkStoreContactFieldCollection& aFieldCollection );

   547 

   548     /**

   549      * Checks if the given string is a phone number.

   550      */

   551     IMPORT_C static TBool IsPhoneNumberL( const TDesC& aData );

   552     

   553     /**

   554      * Checks if the given string is an email address.

   555      */

   556     IMPORT_C static TBool IsEmailAddressL( const TDesC& aData );

   557     

   558     /**

   559      * Appends content of name fields to the given array.

   560      * Uses less fields than LookupL, here only family and given name

   561      * are taken and returned.

   562      *

   563      * @param   aFieldCollection        fields to check

   564      * @param   aArray                  array to which strings are appended

   565      */

   566     IMPORT_C void GetNamesForFindL(

   567         MVPbkStoreContactFieldCollection& aFieldCollection,

   568         CDesCArray& aArray );

   569         

   570     /**

   571      * Gets content of name fields.

   572      * Overload for getting results in one string instead of an array.

   573      * @param   aFieldCollection    fields to check

   574      * @return  content of name fields in no particular order separated by a space

   575      */

   576     IMPORT_C HBufC* GetNamesForFindL(

   577         MVPbkStoreContactFieldCollection& aFieldCollection );

   578         

   579     /**

   580      * Splits a string into parts.

   581      * Space, comma, and semicolon are treated as separators.

   582      */

   583     IMPORT_C static CDesCArray* SplitFindStringL(const TDesC& aFindString);

   584     

   585     /**

   586      * Splits a "name1 name2 ... <something>" into two parts:

   587      * "name1 name2 ..." and "something".

   588      * < and > characters are removed.

   589      * The resulting strings are appended to the given arrray.

   590      * Such format is used by messaging components and this function

   591      * is useful if a search has to be made based on both the name and

   592      * the phone number / email address.

   593      * @param   aString     input string

   594      * @param   aArray      array to append to

   595      */

   596     IMPORT_C static void SplitMsgContactL( const TDesC& aString, CDesCArray& aArray );

   597 

   598     /**

   599      * Appends the values from all matching text fields to a given array.

   600      * @param   aFieldCollection    fields to scan through

   601      * @param   aArray              destination array

   602      * @param   aVersitName         versit property name

   603      * @param   aVersitParam        versit property parameter

   604      */

   605     IMPORT_C void GetCustomFieldL(

   606         MVPbkStoreContactFieldCollection& aFieldCollection,

   607         CDesCArray& aArray,

   608         TVPbkFieldTypeName aVersitName,

   609         TVPbkFieldTypeParameter aVersitParam );

   610 

   611     /**

   612      * Returns a matching field type for the given versit name/parameter.

   613      * The returned list is empty if no matching field types were found.

   614      * @param   aVersitName         versit property name

   615      * @param   aVersitParam        versit property parameter

   616      * @return  field type list, also on the cleanup stack

   617      */

   618     IMPORT_C CVPbkFieldTypeRefsList* GetCustomFieldTypeLC(

   619         TVPbkFieldTypeName aVersitName,

   620         TVPbkFieldTypeParameter aVersitParam );

   621 

   622     /**

   623      * Finds impp field data.

   624      * @param   aFieldCollection    fields to scan

   625      * @param   aSchemeOnlyAray     if non-null then scheme parts are appended to here

   626      * @param   aUriOnlyArray       if non-null then uri parts are appended to here

   627      * @param   aFullArray          if non-null then full field contents are appended to here

   628      */

   629     IMPORT_C void GetImppFieldL(

   630         MVPbkStoreContactFieldCollection& aFieldCollection,

   631         CDesCArray* aSchemeOnlyArray,

   632         CDesCArray* aUriOnlyArray,

   633         CDesCArray* aFullArray );

   634 

   635     /**

   636      * Finds all contacts that have a birthday on the given month/day.

   637      * Other components from aDate - like year, hours, etc. - are ignored.

   638      * @param   aDate       date to look for

   639      * @param   aLinkArray  links are appended to this array

   640      * If no matching contacts are found then aLinkArray is left untouched.

   641      */

   642     IMPORT_C void FindContactWithBirthdayL( const TTime& aDate,

   643         CVPbkContactLinkArray& aLinkArray );

   644         

   645 private: // from MVPbkContactStoreListObserver, MVPbkContactStoreObserver

   646 

   647     /**

   648     * Called when the opening process is complete, ie. all stores have

   649     * been reported either failed or successfully opened.

   650     */

   651     void OpenComplete();

   652 

   653     /**

   654     * Called when a contact store is ready for use.

   655     */

   656     void StoreReady( MVPbkContactStore& aContactStore );

   657 

   658     /**

   659     * Called when a contact store becomes unavailable.

   660     * Client may inspect the reason of the unavailability and decide whether or not

   661     * it will keep the store opened (ie. listen to the store events).

   662     * @param aContactStore The store that became unavailable.

   663     * @param aReason The reason why the store is unavailable.

   664     *                This is one of the system wide error codes.

   665     */

   666     void StoreUnavailable( MVPbkContactStore& aContactStore, TInt aReason );

   667 

   668     /**

   669     * Called when changes occur in the contact store.

   670     * @see TVPbkContactStoreEvent, MVPbkContactStoreObserver.h

   671     *

   672     * @param aContactStore

   673     * @param aStoreEvent Event that has occured.

   674     */

   675     void HandleStoreEventL( MVPbkContactStore& aContactStore,

   676         TVPbkContactStoreEvent aStoreEvent );

   677 

   678 private: // from MVPbkContactFindFromStoresObserver

   679     /**

   680     * Called when find is complete on a single store. Callee takes

   681     * ownership of the results. In case of an error during find,

   682     * the aResultsFromStore may contain only partial results of the find.

   683     *

   684     * @param aStore is the store from which the contacts were searched from

   685     *

   686     * @param aResultsFromStore Array of contact links that matched the find.

   687     *                 Callee must take ownership of this object in

   688     *                 the end of the function, ie. in case the function

   689     *                 does not leave.

   690     */

   691     void FindFromStoreSucceededL( MVPbkContactStore& aStore,

   692         MVPbkContactLinkArray* aResultsFromStore );

   693                         

   694     /**

   695     * This function is called if/when there were errors while searching

   696     * from a store.

   697     * @param aStore is the store from which the search was done.

   698     * @param aError is the error code.

   699     */

   700     void FindFromStoreFailed( MVPbkContactStore& aStore, TInt aError );

   701 

   702     /**

   703     * Called when find is complete.

   704     */

   705     void FindFromStoresOperationComplete();

   706 

   707 private: // from MVPbkContactFindObserver

   708 

   709     /**

   710     * Called when find is complete. Callee takes ownership of the results.

   711     * In case of an error during find, the aResults may contain only

   712     * partial results of the find.

   713     *

   714     * @param aResults Array of contact links that matched the find.

   715     *                 Callee must take ownership of this object in

   716     *                 the end of the function, ie. in case the function

   717     *                 does not leave.

   718     */

   719     void FindCompleteL( MVPbkContactLinkArray* aResults );

   720 

   721     /**

   722     * Called in case the find fails for some reason.

   723     * 

   724     * @param aError One of the system wide error codes.

   725     */

   726     void FindFailed( TInt aError );

   727 

   728 private: // from MVPbkSingleContactOperationObserver

   729 

   730     /**

   731     * Called when operation is completed.

   732     *

   733     * @param aOperation the completed operation.

   734     * @param aContact  the contact returned by the operation.

   735     *                  Client must take the ownership immediately.

   736     */

   737     void VPbkSingleContactOperationComplete(

   738         MVPbkContactOperationBase& aOperation, MVPbkStoreContact* aContact );

   739 

   740     /**

   741     * Called if the operation fails.

   742     *

   743     * @param aOperation    the failed operation.

   744     * @param aError        error code of the failure.

   745     */

   746     void VPbkSingleContactOperationFailed(

   747         MVPbkContactOperationBase& aOperation, TInt aError );        

   748 

   749 private: // from MVPbkContactViewObserver

   750     void ContactViewReady(

   751             MVPbkContactViewBase& aView );

   752     void ContactViewUnavailable(

   753             MVPbkContactViewBase& aView );

   754     void ContactAddedToView(

   755             MVPbkContactViewBase& aView, 

   756             TInt aIndex, 

   757             const MVPbkContactLink& aContactLink );

   758     void ContactRemovedFromView(

   759             MVPbkContactViewBase& aView, 

   760             TInt aIndex, 

   761             const MVPbkContactLink& aContactLink );

   762     void ContactViewError(

   763             MVPbkContactViewBase& aView, 

   764             TInt aError, 

   765             TBool aErrorNotified );

   766 

   767 private: // Constants

   768 

   769     // Wrapper method IDs for calls that have an asynchronous version

   770     enum TMethodId

   771         {

   772         ENoMethod = 0,

   773         EMatchPhoneNumber,

   774         EMatchData,

   775         EGetStoreContact,

   776         EOpenStore, 

   777         ECloseStores 

   778         };

   779 

   780     // Wrapper method processing status.

   781     enum TMethodStatus

   782         {

   783         EIdle = 0,

   784         EExecuting,

   785         EFinished

   786         };

   787 

   788 private: // Methods

   789     const MVPbkStoreContactField* FindField( const MVPbkStoreContact& aContact,

   790         const MVPbkFieldType& aFType ) const;

   791     static CVPbkContactStoreUriArray* GetStoreArrayLC(

   792         const TDesC& (* const aFuncPtrs[])() );

   793     void OpenStoreL( const TDesC& (* const aFuncPtrs[])() );

   794     void OpenStoreL( const TDesC& (* const aFuncPtrs[])(),

   795         TRequestStatus&  aStatus );

   796     void FreeOldOperation();

   797 

   798     // Copies the entries to the existing recipient array

   799     void CopyFindResultsL( MVPbkContactLinkArray* aResults );

   800 

   801     // Open store, code common to sync/async versions.

   802     void OpenStoreCommonL( const CVPbkContactStoreUriArray& aUriArray );

   803 

   804     // Match phonenumber, code common to sync/async versions.

   805     void MatchPhoneNumberCommonL( const TDesC& aData, TInt aDigits,

   806         CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags aFlags );

   807 

   808     void InitOperationL( TMethodId aApiMethod );

   809     void InitOperationL( TMethodId aApiMethod, TRequestStatus* aStatus );

   810     void InitOperation( TRequestStatus* aStatus );

   811     void OperationComplete( TInt ErrorCode = KErrNone );

   812     void OperationFailed( TInt aError );

   813     void CleanupNumberMatch();

   814     void RemoveSimilarEmailAddressesL( const TDesC& aData, CVPbkContactLinkArray& aLinkArray, const MVPbkFieldTypeList& aFieldTypes );

   815 

   816     void TryTextLookupL( const TDesC& aName, CVPbkContactLinkArray& aLinkArray );

   817     void TryNumberLookupL( const TDesC& aName, CVPbkContactLinkArray& aLinkArray );

   818 

   819     void PreCreateNameFieldTypesL();

   820     void PreCreateEmailFieldTypesL();

   821     void PreCreateXspIdFieldTypesL();

   822     void PreCreateNumberFieldTypesL();

   823     void PreCreateAddressFieldTypesL();

   824     void PreCreateWebAddressFieldTypesL();

   825     void PreCreateWebAddressHomeFieldTypesL();

   826     void PreCreateWebAddressWorkFieldTypesL();

   827     void PreCreateWorkAddressFieldTypesL();

   828     void PreCreateHomeAddressFieldTypesL();

   829     

   830     void GetTextFieldsL( const CVPbkFieldTypeRefsList& aList,

   831         const MVPbkStoreContactFieldCollection& aFieldCollection, CDesCArray& aArray );

   832 

   833 private: // Data

   834 

   835     // Used members

   836 

   837     RFs* iFsSession;

   838     TBool iFsSessionOwned;

   839     MVPbkStoreContact** iResultStoreContact; // result of GetStoreContact

   840     CVPbkContactLinkArray* iResultContactLinkArray; // result of matching operations

   841     TInt iResultContactLinkCnt; // number of links found in matching operations

   842     TRequestStatus* iClientStatus; // request status used in asynch calls

   843 

   844     // Own members

   845     CVPbkContactManager* iContactManager;

   846     MVPbkContactOperationBase* iOperation;  // CM operation being processed

   847     CActiveSchedulerWait iASchedulerWait;   // used in asynch calls

   848     CVPbkContactStoreUriArray* iStoreUris;  // used in matching

   849     CVPbkPhoneNumberMatchStrategy* iMatchStrategy; // used in matching

   850     CVPbkPhoneNumberMatchStrategy::TConfig* iStratConfig;  // used in matching

   851     TBool iSync;  // is this wrapper call Synchronous (1) or Asynchronous (0) 

   852     TInt iError;  // error code used while processing VPbk-operations

   853     TBool iBackup;// contact store backup/restore in progress

   854     // API method ID. Needed for cleanup after method finishes.

   855     TMethodId iApiMethod;

   856     // API method status. Needed to know processing has finished.

   857     TMethodStatus iApiMethodStatus;

   858 

   859     CPbk2SortOrderManager* iSortOrderManager;

   860     MPbk2ContactNameFormatter* iNameFormatter;

   861     

   862     RPointerArray<MHgCtxContactObserver> iContactObservers; // ptrs not owned

   863     CVPbkFieldTypeRefsList* iNameFieldTypes;

   864     CVPbkFieldTypeRefsList* iEmailFieldTypes;

   865     CVPbkFieldTypeRefsList* iXspIdFieldTypes;

   866     CVPbkFieldTypeRefsList* iNumberFieldTypes;

   867     CVPbkFieldTypeRefsList* iAddressFieldTypes;

   868     CVPbkFieldTypeRefsList* iWebAddressFieldTypes;

   869     CVPbkFieldTypeRefsList* iWebAddressHomeFieldTypes;

   870     CVPbkFieldTypeRefsList* iWebAddressWorkFieldTypes;

   871     CVPbkFieldTypeRefsList* iWorkAddressFieldTypes;

   872     CVPbkFieldTypeRefsList* iHomeAddressFieldTypes;

   873     };

   874 

   875 /**

   876 * Panic codes used in CHgCtxContactMatcher.

   877 *

   878 * @since 3.1u

   879 */

   880 class HgContactMatcherPanics

   881     {

   882 public: // API

   883         

   884     /**

   885     * Panic codes

   886     */

   887     enum TPanic

   888         {

   889         EPanNullPointer = 0,

   890         EPanInvalidParam,

   891         EPanInvalidOp

   892         };

   893 

   894 public:

   895 

   896     /**

   897     * Panic

   898     */

   899     static void Panic( TPanic aPanic );

   900     };

   901 

   902 #endif

   903 

   904 // End of File