1 /*

     2 * Copyright (c) 2002-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:  The contact manager for accessing different stores.

    15 *                Initialization: a client gives an array of store URIs (Virtual

    16 *                offers some URIs, see VPbkStoreUriLiterals.h) when creating

    17 *                a manager. The client uses store list to open all stores.

    18 *

    19 */

    20 

    21 

    22 #ifndef CVPBKCONTACTMANAGER_H

    23 #define CVPBKCONTACTMANAGER_H

    24 

    25 

    26 // INCLUDES

    27 #include <e32base.h>

    28 #include <f32file.h>

    29 #include <bamdesca.h>

    30 #include <badesca.h> 

    31 

    32 // FORWARD DECLARATIONS

    33 class MVPbkFieldTypeList;

    34 class MVPbkContactManagerObserver;

    35 class MVPbkContactStoreList;

    36 class CVPbkContactStoreList;

    37 class MVPbkStoreContact;

    38 class MVPbkContactLink;

    39 class MVPbkContactOperationBase;

    40 class MVPbkSingleContactOperationObserver;

    41 class MVPbkBatchOperationObserver;

    42 class MVPbkContactFindObserver;

    43 class MVPbkContactViewBase;

    44 class CVPbkContactViewDefinition;

    45 class MVPbkContactStore;

    46 class TVPbkContactStoreUriPtr;

    47 class CVPbkContactStoreDomainList;

    48 class MVPbkContactViewObserver;

    49 class MVPbkContactLinkArray;

    50 class MVPbkContactAttributeManager;

    51 class CVPbkContactStoreUriArray;

    52 class MVPbkContactFindFromStoresObserver;

    53 

    54 // CLASS DECLARATIONS

    55 

    56 /**

    57  * Virtual Phonebook Contact Manager. Contact Manager is the root access point

    58  * to Virtual Phonebook engine functionality. The client can specify the list

    59  * of stores in the constructor he/she is interested in or load additional 

    60  * plug-ins later on. In addition to loading the implementing plug-ins the 

    61  * client must open the stores. Clients should share the contact manager 

    62  * instance within their context, otherwise e.g. field types from two 

    63  * different instances will not produce the matches as the matching is

    64  * based on pointer comparison.

    65  *

    66  * Examples of absolute URI stores:

    67  * Default contact database: "cntdb://contacts.cdb"

    68  * LDAP store: "ldap://www.telnumbers.com/"

    69  * The URI scheme name is used to resolve a store capable of supporting 

    70  * this type of store. The actual store implementations are ECom plugins.

    71  *

    72  *  @lib VPbkEng.lib

    73  */

    74 class CVPbkContactManager : public CBase

    75     {

    76     public:  // Constructors and destructor

    77         /**

    78          * Creates a contact manager instance and loads the plug-ins that can 

    79          * handle the stores corresponding to the aURIList.

    80          * @param aURIList  Universal Resource Identifier list of the stores 

    81          *                  to be loaded initially. 

    82          * @param aFs       File system handle. NULL opens a new connection.

    83          * @return	Contact manager instance.

    84          */

    85         IMPORT_C static CVPbkContactManager* NewL(

    86                 const CVPbkContactStoreUriArray& aURIList,

    87                 RFs* aFs = NULL);

    88                 

    89         /**

    90          * Creates a contact manager instance and loads the plug-ins that can 

    91          * handle the stores corresponding to the aURIList.

    92          * @param aSecurityInfo Security info from caller to be passed for stores.

    93          *                      Stores can check security info and deside

    94          *                      if client can use service.

    95          * @param aURIList      Universal Resource Identifier list of the stores 

    96          *                      to be loaded initially. 

    97          * @param aFs           File system handle. NULL opens a new connection.

    98          * @return              Contact manager instance.

    99          */

   100         IMPORT_C static CVPbkContactManager* NewL(

   101                 TSecurityInfo aSecurityInfo,

   102                 const CVPbkContactStoreUriArray& aURIList,

   103                 RFs* aFs = NULL);

   104 

   105         /**

   106          * Destructor.

   107          */

   108         ~CVPbkContactManager();

   109 

   110     public: // Interface

   111         /**

   112          * The contact manager owns a master list of field types that clients

   113          * use. The store implementation then maps their native types

   114          * to Virtual Phonebook types. Clients don't create field type objects

   115          * themselves but use always references to types offered 

   116          * by this function.

   117          *

   118          * @return The global list of field types.

   119          */

   120         IMPORT_C const MVPbkFieldTypeList& FieldTypes() const;

   121 

   122         /**

   123          * The contact store list is used to handle a set of stores.

   124          * After creation of manager the client can use the list to open

   125          * all stores.

   126          *

   127          * @return The list of available contact stores.

   128          */

   129         IMPORT_C MVPbkContactStoreList& ContactStoresL();

   130 

   131         /**

   132          * Loads a store plug-in for given URI and adds aURI 

   133          * to the list of stores handled by this manager.

   134          * If there is no store plug-in for the aURI then nothing changes.

   135          *

   136          * @param aURI the store URI to be loaded.

   137          */

   138         IMPORT_C void LoadContactStoreL(const TVPbkContactStoreUriPtr& aURI);

   139 

   140         /**

   141          * Attribute manager is used for handling contact attributes like

   142          * speed dialing or defaults.

   143          *

   144          * @returns The contact attribute manager.

   145          */

   146         IMPORT_C MVPbkContactAttributeManager& ContactAttributeManagerL();

   147 

   148         /**

   149          * Creates a new contact view specified by the view definition.

   150          * The view can not be used before it has notified the observer 

   151          * that it is ready.

   152          *

   153          * @param aObserver the observer for view events.

   154          * @param aViewDefinition Definition of the view to create

   155          * @param aSortOrder a list of field types that defines fields

   156          *        that are used in sorting. View contacts

   157          *        have these fields. However, the store can have restrictions

   158          *        for types that can be used in the sort order.

   159          *        The sort order has no effect for shared views that have

   160          *        already been created.

   161          *

   162          * @see CVPbkSortOrder

   163          * @return Newly created view. 

   164          *         If NULL CleanupStack pop is still needed

   165          */

   166         IMPORT_C MVPbkContactViewBase* CreateContactViewLC(

   167                 MVPbkContactViewObserver& aObserver,

   168                 const CVPbkContactViewDefinition& aViewDefinition, 

   169                 const MVPbkFieldTypeList& aSortOrder) const;

   170 

   171         /**

   172          * Retrieves asynchronously a contact that is individualized by 

   173          * a contact link. Delete the operation for canceling.

   174          *

   175          * @param aLink a link to the contact

   176          * @param aObserver operation observer

   177          * @return New handle to the operation

   178          * @Asynchronous

   179          */

   180         IMPORT_C MVPbkContactOperationBase* RetrieveContactL(

   181                 const MVPbkContactLink& aLink,

   182                 MVPbkSingleContactOperationObserver& aObserver) const;

   183         

   184         /**

   185          * Creates an array of links corresponding to a packaged link or links.

   186          * Packed links have been obtained by packing a link or a link array

   187          * and they can be used for example for IPC but not for saving links. 

   188          * Loads the store plug-ins that are capable of creating the 

   189          * appropriate links.

   190          *

   191          * @param aPackedLinks packed links

   192          * @return A link array.

   193          * @see MVPbkContactLink::PackLC

   194          * @see MVPbkContactLinkArray::PackLC

   195          */

   196         IMPORT_C MVPbkContactLinkArray* CreateLinksLC(

   197             const TDesC8& aPackedLinks) const;

   198         

   199         /**

   200          * Internalizes a permanent link or links. An externalized link

   201          * has been created using MVPbkStreamable interface from

   202          * MVPbkContactLink.

   203          * Loads the store plug-ins that are capable of creating the 

   204          * appropriate links.

   205          *

   206          * @param aStream a stream that contains a link or links.

   207          * @return A link array

   208          * @see MVPbkContactLink::Streamable

   209          */

   210         IMPORT_C MVPbkContactLinkArray* CreateLinksLC(

   211             RReadStream& aStream) const;

   212             

   213         /**

   214          * Deletes contacts defined in link array asynchronously.

   215          *

   216          * @param aContactLinks Contacts to delete

   217          * @param aObserver Operation observer

   218          * @return New handle to the operation

   219          */

   220         IMPORT_C MVPbkContactOperationBase* DeleteContactsL(

   221                 const MVPbkContactLinkArray& aContactLinks, 

   222                 MVPbkBatchOperationObserver& aObserver);

   223 

   224         /**

   225          * Commits all contacts in aContacts asynchronously.

   226          *

   227          * @see MVPbkStoreContact::CommitL

   228          * @param aContacts Contacts to commit.

   229          * @param aObserver Operation observer.

   230          * @return New handle to the operation.

   231          */

   232         IMPORT_C MVPbkContactOperationBase* CommitContactsL(

   233                 const TArray<MVPbkStoreContact*>& aContacts, 

   234                 MVPbkBatchOperationObserver& aObserver);

   235 

   236         /**

   237          * Copies all contacts in aContactLinks to aTargetStore asynchronously. 

   238          * If aTargetStore is NULL, contacts are copied to the store where 

   239          * they already are, ie. the contacts are duplicated.

   240          *

   241          * @param aContactLinks Array of contact links to duplicate.

   242          * @param aTargetStore Target store to copy contacts to.

   243          *                     If NULL this behaves like duplicate.

   244          * @param aObserver Observer for the copying process.

   245          * @return New handle to the operation.

   246          */

   247         IMPORT_C MVPbkContactOperationBase* CopyContactsL(

   248                 const MVPbkContactLinkArray& aContactLinks,

   249                 MVPbkContactStore* aTargetStore,

   250                 MVPbkBatchOperationObserver& aObserver);

   251 

   252         /**

   253          * Searches the contact stores for a phone number using 

   254          * defined amount of digits from the end of the number asynchronously.

   255          * The store implementations determine, which field types are included 

   256          * in the search. 

   257          * 

   258          * @param aPhoneNumber Phone number to search for.

   259          * @param aMaxMatchDigits Maximum number of digits to match 

   260          * 						  from the end of the number.

   261          * @param aObserver Observer for the find process.

   262          * @return New handle to the find operation.

   263          */

   264         IMPORT_C MVPbkContactOperationBase* MatchPhoneNumberL(

   265                 const TDesC& aPhoneNumber, 

   266                 TInt aMaxMatchDigits,

   267                 MVPbkContactFindObserver& aObserver);

   268 

   269         /**

   270          * Searches the contact stores for a contact that contains

   271          * the given string in one of the field defined by given 

   272          * field type list asynchronously.

   273          * NOTE: In some cases the find matches also other fields than 

   274          *       those specified in aFieldTypes. Always loop through the

   275          *       results to check match in the required fields.

   276          *

   277          * @param aSearchString String to search for.

   278          * @param aFieldTypes List of field types that the search will include.

   279          *                    a field type list: use CVPbkFieldTypeRefsList and

   280          *                    append the types that are needed from 

   281          *                    the master field type list (FieldTypes()) 

   282          *                    to the reference list. Selection can be done

   283          *                    in a dynamic way using CVPbkFieldTypeSelector or

   284          *                    static way using resource ids of the field types.

   285          * @param aObserver Observer for the find process.

   286          * @return New handle to the find operation.

   287          */

   288         IMPORT_C MVPbkContactOperationBase* FindL(

   289                 const TDesC& aSearchString,

   290                 const MVPbkFieldTypeList& aFieldTypes,

   291                 MVPbkContactFindObserver& aObserver);

   292         

   293         /**

   294          * Finds a string containing text that is stored in one or more 

   295          * fields asynchronously. Client can give multiple find words. 

   296          * All the words must match to separated data. E.g. if there are 

   297          * two find words: "Jo" and "Jo" then field data "John Johnson" 

   298          * matches but "John Doe" doesn't if the word parser uses

   299          * white space as a word separator.

   300          *

   301          * NOTE: The accuracy of the results depends on the implementation 

   302          * of the store to carry out the find operation. The performance 

   303          * can also vary depending on the store. 

   304          *

   305          * @param aSearchStrings strings that are compared to field data.

   306          * @param aFieldTypes types of the fields that are used. Constructing

   307          *                    a fieldtype list: use CVPbkFieldTypeRefsList and

   308          *                    append the types that are needed from 

   309          *                    the master fieldtype list (FieldTypes()) 

   310          *                    to the reference list. Selection can be done

   311          *                    in a dynamic way using CVPbkFieldTypeSelector or

   312          *                    static way using resource ids of the fieldtypes.

   313          * 

   314          * @param aObserver an observer for asynchronous operation.

   315          * @param aWordParserCallBack a client implementation of word parser 

   316          *                            function that separates the field data 

   317          *                            into words. Parameter to function is 

   318          *                            TVPbkWordParserParam.

   319          * @return New handle to the find operation.

   320          */

   321         IMPORT_C MVPbkContactOperationBase* FindL(

   322                 const MDesC16Array& aSearchStrings, 

   323                 const MVPbkFieldTypeList& aFieldTypes, 

   324                 MVPbkContactFindFromStoresObserver& aObserver, 

   325                 const TCallBack& aWordParserCallBack );

   326         

   327         /**

   328          * Compresses all stores asynchronously.

   329          * NOTE: Not all stores are able to implement compression to their

   330          * repositories.

   331          * 

   332          * @param aObserver Operation observer.

   333          * @return New handle to the operation.

   334          */

   335         IMPORT_C MVPbkContactOperationBase* CompressStoresL(

   336         		MVPbkBatchOperationObserver& aObserver);

   337 

   338         /**

   339          * Returns the file server session of the contact manager.

   340          * 

   341          * @return File server session of the contact manager.

   342          */

   343         IMPORT_C RFs& FsSession();

   344         

   345         

   346         /**

   347          * Finds a string containing text that is stored in one or more 

   348          * fields asynchronously. Client can give multiple find words. 

   349          * All the words must match to separated data. E.g. if there are 

   350          * two find words: "Jo" and "Jo" then field data "John Johnson" 

   351          * matches but "John Doe" doesn't if the word parser uses

   352          * white space as a word separator.

   353          *

   354          * NOTE: The accuracy of the results depends on the implementation 

   355          * of the store to carry out the find operation. The performance 

   356          * can also vary depending on the store. 

   357          *

   358          * @param aSearchStrings strings that are compared to field data.

   359          * @param aFieldTypes types of the fields that are used. Constructing

   360          *                    a fieldtype list: use CVPbkFieldTypeRefsList and

   361          *                    append the types that are needed from 

   362          *                    the master fieldtype list (FieldTypes()) 

   363          *                    to the reference list. Selection can be done

   364          *                    in a dynamic way using CVPbkFieldTypeSelector or

   365          *                    static way using resource ids of the fieldtypes.

   366          * 

   367          * @param aObserver an observer for asynchronous operation.

   368          * @param aWordParserCallBack a client implementation of word parser 

   369          *                            function that separates the field data 

   370          *                            into words. Parameter to function is 

   371          *                            TVPbkWordParserParam.

   372          * @param aStoreEntriesArray an array that lists the store entries

   373          * @return New handle to the find operation or NULL if it could not be created.

   374          */

   375         IMPORT_C MVPbkContactOperationBase* FindL(

   376                 const MDesC16Array& aSearchStrings, 

   377                 const MVPbkFieldTypeList& aFieldTypes, 

   378                 MVPbkContactFindFromStoresObserver& aObserver, 

   379                 const TCallBack& aWordParserCallBack,

   380                 const CDesC16ArrayFlat& aStoreEntriesArray );

   381 

   382     private: // Implementation

   383         CVPbkContactManager( TSecurityInfo aSecurityInfo, RFs* aFs );

   384         void ConstructL(const CVPbkContactStoreUriArray& aURIList);

   385         MVPbkContactStore* FindStore(const TVPbkContactStoreUriPtr& aURI) const;

   386         MVPbkContactViewBase* CreateOptimizedCompositeViewLC(

   387                 MVPbkContactViewObserver& aObserver,

   388                 const CVPbkContactViewDefinition& aViewDefinition, 

   389                 const MVPbkFieldTypeList& aSortOrder) const;

   390         MVPbkContactViewBase* CreateCompositeViewLC(

   391                 MVPbkContactViewObserver& aObserver,

   392                 const CVPbkContactViewDefinition& aViewDefinition, 

   393                 const MVPbkFieldTypeList& aSortOrder) const;

   394 

   395     private: // Data

   396         /// Own: Security info for client.

   397         TSecurityInfo iSecurityInfo;

   398         /// Own: File system handle

   399         RFs iFs;

   400         /// Own: File system handle that is owned

   401         RFs iOwnFs;

   402         /// Own: Global Phonebook field types

   403         MVPbkFieldTypeList* iFieldTypes;

   404         /// Own: List of contact stores

   405         CVPbkContactStoreDomainList* iContactStoreDomains;

   406         /// Own: Contact attribute manager

   407         MVPbkContactAttributeManager* iAttributeManager;

   408         /// Own: an internal class for loading stores

   409         class CContactStoreLoader;

   410         CContactStoreLoader* iStoreLoader;

   411     };

   412 

   413 #endif  // CVPBKCONTACTMANAGER_H

   414 

   415 // End of file