--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contacts_plat/virtual_phonebook_engine_api/inc/CVPbkContactManager.h Wed Sep 01 12:29:52 2010 +0100
@@ -0,0 +1,415 @@
+/*
+* Copyright (c) 2002-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: The contact manager for accessing different stores.
+* Initialization: a client gives an array of store URIs (Virtual
+* offers some URIs, see VPbkStoreUriLiterals.h) when creating
+* a manager. The client uses store list to open all stores.
+*
+*/
+
+
+#ifndef CVPBKCONTACTMANAGER_H
+#define CVPBKCONTACTMANAGER_H
+
+
+// INCLUDES
+#include <e32base.h>
+#include <f32file.h>
+#include <bamdesca.h>
+#include <badesca.h>
+
+// FORWARD DECLARATIONS
+class MVPbkFieldTypeList;
+class MVPbkContactManagerObserver;
+class MVPbkContactStoreList;
+class CVPbkContactStoreList;
+class MVPbkStoreContact;
+class MVPbkContactLink;
+class MVPbkContactOperationBase;
+class MVPbkSingleContactOperationObserver;
+class MVPbkBatchOperationObserver;
+class MVPbkContactFindObserver;
+class MVPbkContactViewBase;
+class CVPbkContactViewDefinition;
+class MVPbkContactStore;
+class TVPbkContactStoreUriPtr;
+class CVPbkContactStoreDomainList;
+class MVPbkContactViewObserver;
+class MVPbkContactLinkArray;
+class MVPbkContactAttributeManager;
+class CVPbkContactStoreUriArray;
+class MVPbkContactFindFromStoresObserver;
+
+// CLASS DECLARATIONS
+
+/**
+ * Virtual Phonebook Contact Manager. Contact Manager is the root access point
+ * to Virtual Phonebook engine functionality. The client can specify the list
+ * of stores in the constructor he/she is interested in or load additional
+ * plug-ins later on. In addition to loading the implementing plug-ins the
+ * client must open the stores. Clients should share the contact manager
+ * instance within their context, otherwise e.g. field types from two
+ * different instances will not produce the matches as the matching is
+ * based on pointer comparison.
+ *
+ * Examples of absolute URI stores:
+ * Default contact database: "cntdb://contacts.cdb"
+ * LDAP store: "ldap://www.telnumbers.com/"
+ * The URI scheme name is used to resolve a store capable of supporting
+ * this type of store. The actual store implementations are ECom plugins.
+ *
+ * @lib VPbkEng.lib
+ */
+class CVPbkContactManager : public CBase
+ {
+ public: // Constructors and destructor
+ /**
+ * Creates a contact manager instance and loads the plug-ins that can
+ * handle the stores corresponding to the aURIList.
+ * @param aURIList Universal Resource Identifier list of the stores
+ * to be loaded initially.
+ * @param aFs File system handle. NULL opens a new connection.
+ * @return Contact manager instance.
+ */
+ IMPORT_C static CVPbkContactManager* NewL(
+ const CVPbkContactStoreUriArray& aURIList,
+ RFs* aFs = NULL);
+
+ /**
+ * Creates a contact manager instance and loads the plug-ins that can
+ * handle the stores corresponding to the aURIList.
+ * @param aSecurityInfo Security info from caller to be passed for stores.
+ * Stores can check security info and deside
+ * if client can use service.
+ * @param aURIList Universal Resource Identifier list of the stores
+ * to be loaded initially.
+ * @param aFs File system handle. NULL opens a new connection.
+ * @return Contact manager instance.
+ */
+ IMPORT_C static CVPbkContactManager* NewL(
+ TSecurityInfo aSecurityInfo,
+ const CVPbkContactStoreUriArray& aURIList,
+ RFs* aFs = NULL);
+
+ /**
+ * Destructor.
+ */
+ ~CVPbkContactManager();
+
+ public: // Interface
+ /**
+ * The contact manager owns a master list of field types that clients
+ * use. The store implementation then maps their native types
+ * to Virtual Phonebook types. Clients don't create field type objects
+ * themselves but use always references to types offered
+ * by this function.
+ *
+ * @return The global list of field types.
+ */
+ IMPORT_C const MVPbkFieldTypeList& FieldTypes() const;
+
+ /**
+ * The contact store list is used to handle a set of stores.
+ * After creation of manager the client can use the list to open
+ * all stores.
+ *
+ * @return The list of available contact stores.
+ */
+ IMPORT_C MVPbkContactStoreList& ContactStoresL();
+
+ /**
+ * Loads a store plug-in for given URI and adds aURI
+ * to the list of stores handled by this manager.
+ * If there is no store plug-in for the aURI then nothing changes.
+ *
+ * @param aURI the store URI to be loaded.
+ */
+ IMPORT_C void LoadContactStoreL(const TVPbkContactStoreUriPtr& aURI);
+
+ /**
+ * Attribute manager is used for handling contact attributes like
+ * speed dialing or defaults.
+ *
+ * @returns The contact attribute manager.
+ */
+ IMPORT_C MVPbkContactAttributeManager& ContactAttributeManagerL();
+
+ /**
+ * Creates a new contact view specified by the view definition.
+ * The view can not be used before it has notified the observer
+ * that it is ready.
+ *
+ * @param aObserver the observer for view events.
+ * @param aViewDefinition Definition of the view to create
+ * @param aSortOrder a list of field types that defines fields
+ * that are used in sorting. View contacts
+ * have these fields. However, the store can have restrictions
+ * for types that can be used in the sort order.
+ * The sort order has no effect for shared views that have
+ * already been created.
+ *
+ * @see CVPbkSortOrder
+ * @return Newly created view.
+ * If NULL CleanupStack pop is still needed
+ */
+ IMPORT_C MVPbkContactViewBase* CreateContactViewLC(
+ MVPbkContactViewObserver& aObserver,
+ const CVPbkContactViewDefinition& aViewDefinition,
+ const MVPbkFieldTypeList& aSortOrder) const;
+
+ /**
+ * Retrieves asynchronously a contact that is individualized by
+ * a contact link. Delete the operation for canceling.
+ *
+ * @param aLink a link to the contact
+ * @param aObserver operation observer
+ * @return New handle to the operation
+ * @Asynchronous
+ */
+ IMPORT_C MVPbkContactOperationBase* RetrieveContactL(
+ const MVPbkContactLink& aLink,
+ MVPbkSingleContactOperationObserver& aObserver) const;
+
+ /**
+ * Creates an array of links corresponding to a packaged link or links.
+ * Packed links have been obtained by packing a link or a link array
+ * and they can be used for example for IPC but not for saving links.
+ * Loads the store plug-ins that are capable of creating the
+ * appropriate links.
+ *
+ * @param aPackedLinks packed links
+ * @return A link array.
+ * @see MVPbkContactLink::PackLC
+ * @see MVPbkContactLinkArray::PackLC
+ */
+ IMPORT_C MVPbkContactLinkArray* CreateLinksLC(
+ const TDesC8& aPackedLinks) const;
+
+ /**
+ * Internalizes a permanent link or links. An externalized link
+ * has been created using MVPbkStreamable interface from
+ * MVPbkContactLink.
+ * Loads the store plug-ins that are capable of creating the
+ * appropriate links.
+ *
+ * @param aStream a stream that contains a link or links.
+ * @return A link array
+ * @see MVPbkContactLink::Streamable
+ */
+ IMPORT_C MVPbkContactLinkArray* CreateLinksLC(
+ RReadStream& aStream) const;
+
+ /**
+ * Deletes contacts defined in link array asynchronously.
+ *
+ * @param aContactLinks Contacts to delete
+ * @param aObserver Operation observer
+ * @return New handle to the operation
+ */
+ IMPORT_C MVPbkContactOperationBase* DeleteContactsL(
+ const MVPbkContactLinkArray& aContactLinks,
+ MVPbkBatchOperationObserver& aObserver);
+
+ /**
+ * Commits all contacts in aContacts asynchronously.
+ *
+ * @see MVPbkStoreContact::CommitL
+ * @param aContacts Contacts to commit.
+ * @param aObserver Operation observer.
+ * @return New handle to the operation.
+ */
+ IMPORT_C MVPbkContactOperationBase* CommitContactsL(
+ const TArray<MVPbkStoreContact*>& aContacts,
+ MVPbkBatchOperationObserver& aObserver);
+
+ /**
+ * Copies all contacts in aContactLinks to aTargetStore asynchronously.
+ * If aTargetStore is NULL, contacts are copied to the store where
+ * they already are, ie. the contacts are duplicated.
+ *
+ * @param aContactLinks Array of contact links to duplicate.
+ * @param aTargetStore Target store to copy contacts to.
+ * If NULL this behaves like duplicate.
+ * @param aObserver Observer for the copying process.
+ * @return New handle to the operation.
+ */
+ IMPORT_C MVPbkContactOperationBase* CopyContactsL(
+ const MVPbkContactLinkArray& aContactLinks,
+ MVPbkContactStore* aTargetStore,
+ MVPbkBatchOperationObserver& aObserver);
+
+ /**
+ * Searches the contact stores for a phone number using
+ * defined amount of digits from the end of the number asynchronously.
+ * The store implementations determine, which field types are included
+ * in the search.
+ *
+ * @param aPhoneNumber Phone number to search for.
+ * @param aMaxMatchDigits Maximum number of digits to match
+ * from the end of the number.
+ * @param aObserver Observer for the find process.
+ * @return New handle to the find operation.
+ */
+ IMPORT_C MVPbkContactOperationBase* MatchPhoneNumberL(
+ const TDesC& aPhoneNumber,
+ TInt aMaxMatchDigits,
+ MVPbkContactFindObserver& aObserver);
+
+ /**
+ * Searches the contact stores for a contact that contains
+ * the given string in one of the field defined by given
+ * field type list asynchronously.
+ * NOTE: In some cases the find matches also other fields than
+ * those specified in aFieldTypes. Always loop through the
+ * results to check match in the required fields.
+ *
+ * @param aSearchString String to search for.
+ * @param aFieldTypes List of field types that the search will include.
+ * a field type list: use CVPbkFieldTypeRefsList and
+ * append the types that are needed from
+ * the master field type list (FieldTypes())
+ * to the reference list. Selection can be done
+ * in a dynamic way using CVPbkFieldTypeSelector or
+ * static way using resource ids of the field types.
+ * @param aObserver Observer for the find process.
+ * @return New handle to the find operation.
+ */
+ IMPORT_C MVPbkContactOperationBase* FindL(
+ const TDesC& aSearchString,
+ const MVPbkFieldTypeList& aFieldTypes,
+ MVPbkContactFindObserver& aObserver);
+
+ /**
+ * Finds a string containing text that is stored in one or more
+ * fields asynchronously. Client can give multiple find words.
+ * All the words must match to separated data. E.g. if there are
+ * two find words: "Jo" and "Jo" then field data "John Johnson"
+ * matches but "John Doe" doesn't if the word parser uses
+ * white space as a word separator.
+ *
+ * NOTE: The accuracy of the results depends on the implementation
+ * of the store to carry out the find operation. The performance
+ * can also vary depending on the store.
+ *
+ * @param aSearchStrings strings that are compared to field data.
+ * @param aFieldTypes types of the fields that are used. Constructing
+ * a fieldtype list: use CVPbkFieldTypeRefsList and
+ * append the types that are needed from
+ * the master fieldtype list (FieldTypes())
+ * to the reference list. Selection can be done
+ * in a dynamic way using CVPbkFieldTypeSelector or
+ * static way using resource ids of the fieldtypes.
+ *
+ * @param aObserver an observer for asynchronous operation.
+ * @param aWordParserCallBack a client implementation of word parser
+ * function that separates the field data
+ * into words. Parameter to function is
+ * TVPbkWordParserParam.
+ * @return New handle to the find operation.
+ */
+ IMPORT_C MVPbkContactOperationBase* FindL(
+ const MDesC16Array& aSearchStrings,
+ const MVPbkFieldTypeList& aFieldTypes,
+ MVPbkContactFindFromStoresObserver& aObserver,
+ const TCallBack& aWordParserCallBack );
+
+ /**
+ * Compresses all stores asynchronously.
+ * NOTE: Not all stores are able to implement compression to their
+ * repositories.
+ *
+ * @param aObserver Operation observer.
+ * @return New handle to the operation.
+ */
+ IMPORT_C MVPbkContactOperationBase* CompressStoresL(
+ MVPbkBatchOperationObserver& aObserver);
+
+ /**
+ * Returns the file server session of the contact manager.
+ *
+ * @return File server session of the contact manager.
+ */
+ IMPORT_C RFs& FsSession();
+
+
+ /**
+ * Finds a string containing text that is stored in one or more
+ * fields asynchronously. Client can give multiple find words.
+ * All the words must match to separated data. E.g. if there are
+ * two find words: "Jo" and "Jo" then field data "John Johnson"
+ * matches but "John Doe" doesn't if the word parser uses
+ * white space as a word separator.
+ *
+ * NOTE: The accuracy of the results depends on the implementation
+ * of the store to carry out the find operation. The performance
+ * can also vary depending on the store.
+ *
+ * @param aSearchStrings strings that are compared to field data.
+ * @param aFieldTypes types of the fields that are used. Constructing
+ * a fieldtype list: use CVPbkFieldTypeRefsList and
+ * append the types that are needed from
+ * the master fieldtype list (FieldTypes())
+ * to the reference list. Selection can be done
+ * in a dynamic way using CVPbkFieldTypeSelector or
+ * static way using resource ids of the fieldtypes.
+ *
+ * @param aObserver an observer for asynchronous operation.
+ * @param aWordParserCallBack a client implementation of word parser
+ * function that separates the field data
+ * into words. Parameter to function is
+ * TVPbkWordParserParam.
+ * @param aStoreEntriesArray an array that lists the store entries
+ * @return New handle to the find operation or NULL if it could not be created.
+ */
+ IMPORT_C MVPbkContactOperationBase* FindL(
+ const MDesC16Array& aSearchStrings,
+ const MVPbkFieldTypeList& aFieldTypes,
+ MVPbkContactFindFromStoresObserver& aObserver,
+ const TCallBack& aWordParserCallBack,
+ const CDesC16ArrayFlat& aStoreEntriesArray );
+
+ private: // Implementation
+ CVPbkContactManager( TSecurityInfo aSecurityInfo, RFs* aFs );
+ void ConstructL(const CVPbkContactStoreUriArray& aURIList);
+ MVPbkContactStore* FindStore(const TVPbkContactStoreUriPtr& aURI) const;
+ MVPbkContactViewBase* CreateOptimizedCompositeViewLC(
+ MVPbkContactViewObserver& aObserver,
+ const CVPbkContactViewDefinition& aViewDefinition,
+ const MVPbkFieldTypeList& aSortOrder) const;
+ MVPbkContactViewBase* CreateCompositeViewLC(
+ MVPbkContactViewObserver& aObserver,
+ const CVPbkContactViewDefinition& aViewDefinition,
+ const MVPbkFieldTypeList& aSortOrder) const;
+
+ private: // Data
+ /// Own: Security info for client.
+ TSecurityInfo iSecurityInfo;
+ /// Own: File system handle
+ RFs iFs;
+ /// Own: File system handle that is owned
+ RFs iOwnFs;
+ /// Own: Global Phonebook field types
+ MVPbkFieldTypeList* iFieldTypes;
+ /// Own: List of contact stores
+ CVPbkContactStoreDomainList* iContactStoreDomains;
+ /// Own: Contact attribute manager
+ MVPbkContactAttributeManager* iAttributeManager;
+ /// Own: an internal class for loading stores
+ class CContactStoreLoader;
+ CContactStoreLoader* iStoreLoader;
+ };
+
+#endif // CVPBKCONTACTMANAGER_H
+
+// End of file