1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/CVPbkContactManager.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,415 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: The contact manager for accessing different stores.
1.18 +* Initialization: a client gives an array of store URIs (Virtual
1.19 +* offers some URIs, see VPbkStoreUriLiterals.h) when creating
1.20 +* a manager. The client uses store list to open all stores.
1.21 +*
1.22 +*/
1.23 +
1.24 +
1.25 +#ifndef CVPBKCONTACTMANAGER_H
1.26 +#define CVPBKCONTACTMANAGER_H
1.27 +
1.28 +
1.29 +// INCLUDES
1.30 +#include <e32base.h>
1.31 +#include <f32file.h>
1.32 +#include <bamdesca.h>
1.33 +#include <BADESCA.H>
1.34 +
1.35 +// FORWARD DECLARATIONS
1.36 +class MVPbkFieldTypeList;
1.37 +class MVPbkContactManagerObserver;
1.38 +class MVPbkContactStoreList;
1.39 +class CVPbkContactStoreList;
1.40 +class MVPbkStoreContact;
1.41 +class MVPbkContactLink;
1.42 +class MVPbkContactOperationBase;
1.43 +class MVPbkSingleContactOperationObserver;
1.44 +class MVPbkBatchOperationObserver;
1.45 +class MVPbkContactFindObserver;
1.46 +class MVPbkContactViewBase;
1.47 +class CVPbkContactViewDefinition;
1.48 +class MVPbkContactStore;
1.49 +class TVPbkContactStoreUriPtr;
1.50 +class CVPbkContactStoreDomainList;
1.51 +class MVPbkContactViewObserver;
1.52 +class MVPbkContactLinkArray;
1.53 +class MVPbkContactAttributeManager;
1.54 +class CVPbkContactStoreUriArray;
1.55 +class MVPbkContactFindFromStoresObserver;
1.56 +
1.57 +// CLASS DECLARATIONS
1.58 +
1.59 +/**
1.60 + * Virtual Phonebook Contact Manager. Contact Manager is the root access point
1.61 + * to Virtual Phonebook engine functionality. The client can specify the list
1.62 + * of stores in the constructor he/she is interested in or load additional
1.63 + * plug-ins later on. In addition to loading the implementing plug-ins the
1.64 + * client must open the stores. Clients should share the contact manager
1.65 + * instance within their context, otherwise e.g. field types from two
1.66 + * different instances will not produce the matches as the matching is
1.67 + * based on pointer comparison.
1.68 + *
1.69 + * Examples of absolute URI stores:
1.70 + * Default contact database: "cntdb://contacts.cdb"
1.71 + * LDAP store: "ldap://www.telnumbers.com/"
1.72 + * The URI scheme name is used to resolve a store capable of supporting
1.73 + * this type of store. The actual store implementations are ECom plugins.
1.74 + *
1.75 + * @lib VPbkEng.lib
1.76 + */
1.77 +class CVPbkContactManager : public CBase
1.78 + {
1.79 + public: // Constructors and destructor
1.80 + /**
1.81 + * Creates a contact manager instance and loads the plug-ins that can
1.82 + * handle the stores corresponding to the aURIList.
1.83 + * @param aURIList Universal Resource Identifier list of the stores
1.84 + * to be loaded initially.
1.85 + * @param aFs File system handle. NULL opens a new connection.
1.86 + * @return Contact manager instance.
1.87 + */
1.88 + IMPORT_C static CVPbkContactManager* NewL(
1.89 + const CVPbkContactStoreUriArray& aURIList,
1.90 + RFs* aFs = NULL);
1.91 +
1.92 + /**
1.93 + * Creates a contact manager instance and loads the plug-ins that can
1.94 + * handle the stores corresponding to the aURIList.
1.95 + * @param aSecurityInfo Security info from caller to be passed for stores.
1.96 + * Stores can check security info and deside
1.97 + * if client can use service.
1.98 + * @param aURIList Universal Resource Identifier list of the stores
1.99 + * to be loaded initially.
1.100 + * @param aFs File system handle. NULL opens a new connection.
1.101 + * @return Contact manager instance.
1.102 + */
1.103 + IMPORT_C static CVPbkContactManager* NewL(
1.104 + TSecurityInfo aSecurityInfo,
1.105 + const CVPbkContactStoreUriArray& aURIList,
1.106 + RFs* aFs = NULL);
1.107 +
1.108 + /**
1.109 + * Destructor.
1.110 + */
1.111 + ~CVPbkContactManager();
1.112 +
1.113 + public: // Interface
1.114 + /**
1.115 + * The contact manager owns a master list of field types that clients
1.116 + * use. The store implementation then maps their native types
1.117 + * to Virtual Phonebook types. Clients don't create field type objects
1.118 + * themselves but use always references to types offered
1.119 + * by this function.
1.120 + *
1.121 + * @return The global list of field types.
1.122 + */
1.123 + IMPORT_C const MVPbkFieldTypeList& FieldTypes() const;
1.124 +
1.125 + /**
1.126 + * The contact store list is used to handle a set of stores.
1.127 + * After creation of manager the client can use the list to open
1.128 + * all stores.
1.129 + *
1.130 + * @return The list of available contact stores.
1.131 + */
1.132 + IMPORT_C MVPbkContactStoreList& ContactStoresL();
1.133 +
1.134 + /**
1.135 + * Loads a store plug-in for given URI and adds aURI
1.136 + * to the list of stores handled by this manager.
1.137 + * If there is no store plug-in for the aURI then nothing changes.
1.138 + *
1.139 + * @param aURI the store URI to be loaded.
1.140 + */
1.141 + IMPORT_C void LoadContactStoreL(const TVPbkContactStoreUriPtr& aURI);
1.142 +
1.143 + /**
1.144 + * Attribute manager is used for handling contact attributes like
1.145 + * speed dialing or defaults.
1.146 + *
1.147 + * @returns The contact attribute manager.
1.148 + */
1.149 + IMPORT_C MVPbkContactAttributeManager& ContactAttributeManagerL();
1.150 +
1.151 + /**
1.152 + * Creates a new contact view specified by the view definition.
1.153 + * The view can not be used before it has notified the observer
1.154 + * that it is ready.
1.155 + *
1.156 + * @param aObserver the observer for view events.
1.157 + * @param aViewDefinition Definition of the view to create
1.158 + * @param aSortOrder a list of field types that defines fields
1.159 + * that are used in sorting. View contacts
1.160 + * have these fields. However, the store can have restrictions
1.161 + * for types that can be used in the sort order.
1.162 + * The sort order has no effect for shared views that have
1.163 + * already been created.
1.164 + *
1.165 + * @see CVPbkSortOrder
1.166 + * @return Newly created view.
1.167 + * If NULL CleanupStack pop is still needed
1.168 + */
1.169 + IMPORT_C MVPbkContactViewBase* CreateContactViewLC(
1.170 + MVPbkContactViewObserver& aObserver,
1.171 + const CVPbkContactViewDefinition& aViewDefinition,
1.172 + const MVPbkFieldTypeList& aSortOrder) const;
1.173 +
1.174 + /**
1.175 + * Retrieves asynchronously a contact that is individualized by
1.176 + * a contact link. Delete the operation for canceling.
1.177 + *
1.178 + * @param aLink a link to the contact
1.179 + * @param aObserver operation observer
1.180 + * @return New handle to the operation
1.181 + * @Asynchronous
1.182 + */
1.183 + IMPORT_C MVPbkContactOperationBase* RetrieveContactL(
1.184 + const MVPbkContactLink& aLink,
1.185 + MVPbkSingleContactOperationObserver& aObserver) const;
1.186 +
1.187 + /**
1.188 + * Creates an array of links corresponding to a packaged link or links.
1.189 + * Packed links have been obtained by packing a link or a link array
1.190 + * and they can be used for example for IPC but not for saving links.
1.191 + * Loads the store plug-ins that are capable of creating the
1.192 + * appropriate links.
1.193 + *
1.194 + * @param aPackedLinks packed links
1.195 + * @return A link array.
1.196 + * @see MVPbkContactLink::PackLC
1.197 + * @see MVPbkContactLinkArray::PackLC
1.198 + */
1.199 + IMPORT_C MVPbkContactLinkArray* CreateLinksLC(
1.200 + const TDesC8& aPackedLinks) const;
1.201 +
1.202 + /**
1.203 + * Internalizes a permanent link or links. An externalized link
1.204 + * has been created using MVPbkStreamable interface from
1.205 + * MVPbkContactLink.
1.206 + * Loads the store plug-ins that are capable of creating the
1.207 + * appropriate links.
1.208 + *
1.209 + * @param aStream a stream that contains a link or links.
1.210 + * @return A link array
1.211 + * @see MVPbkContactLink::Streamable
1.212 + */
1.213 + IMPORT_C MVPbkContactLinkArray* CreateLinksLC(
1.214 + RReadStream& aStream) const;
1.215 +
1.216 + /**
1.217 + * Deletes contacts defined in link array asynchronously.
1.218 + *
1.219 + * @param aContactLinks Contacts to delete
1.220 + * @param aObserver Operation observer
1.221 + * @return New handle to the operation
1.222 + */
1.223 + IMPORT_C MVPbkContactOperationBase* DeleteContactsL(
1.224 + const MVPbkContactLinkArray& aContactLinks,
1.225 + MVPbkBatchOperationObserver& aObserver);
1.226 +
1.227 + /**
1.228 + * Commits all contacts in aContacts asynchronously.
1.229 + *
1.230 + * @see MVPbkStoreContact::CommitL
1.231 + * @param aContacts Contacts to commit.
1.232 + * @param aObserver Operation observer.
1.233 + * @return New handle to the operation.
1.234 + */
1.235 + IMPORT_C MVPbkContactOperationBase* CommitContactsL(
1.236 + const TArray<MVPbkStoreContact*>& aContacts,
1.237 + MVPbkBatchOperationObserver& aObserver);
1.238 +
1.239 + /**
1.240 + * Copies all contacts in aContactLinks to aTargetStore asynchronously.
1.241 + * If aTargetStore is NULL, contacts are copied to the store where
1.242 + * they already are, ie. the contacts are duplicated.
1.243 + *
1.244 + * @param aContactLinks Array of contact links to duplicate.
1.245 + * @param aTargetStore Target store to copy contacts to.
1.246 + * If NULL this behaves like duplicate.
1.247 + * @param aObserver Observer for the copying process.
1.248 + * @return New handle to the operation.
1.249 + */
1.250 + IMPORT_C MVPbkContactOperationBase* CopyContactsL(
1.251 + const MVPbkContactLinkArray& aContactLinks,
1.252 + MVPbkContactStore* aTargetStore,
1.253 + MVPbkBatchOperationObserver& aObserver);
1.254 +
1.255 + /**
1.256 + * Searches the contact stores for a phone number using
1.257 + * defined amount of digits from the end of the number asynchronously.
1.258 + * The store implementations determine, which field types are included
1.259 + * in the search.
1.260 + *
1.261 + * @param aPhoneNumber Phone number to search for.
1.262 + * @param aMaxMatchDigits Maximum number of digits to match
1.263 + * from the end of the number.
1.264 + * @param aObserver Observer for the find process.
1.265 + * @return New handle to the find operation.
1.266 + */
1.267 + IMPORT_C MVPbkContactOperationBase* MatchPhoneNumberL(
1.268 + const TDesC& aPhoneNumber,
1.269 + TInt aMaxMatchDigits,
1.270 + MVPbkContactFindObserver& aObserver);
1.271 +
1.272 + /**
1.273 + * Searches the contact stores for a contact that contains
1.274 + * the given string in one of the field defined by given
1.275 + * field type list asynchronously.
1.276 + * NOTE: In some cases the find matches also other fields than
1.277 + * those specified in aFieldTypes. Always loop through the
1.278 + * results to check match in the required fields.
1.279 + *
1.280 + * @param aSearchString String to search for.
1.281 + * @param aFieldTypes List of field types that the search will include.
1.282 + * a field type list: use CVPbkFieldTypeRefsList and
1.283 + * append the types that are needed from
1.284 + * the master field type list (FieldTypes())
1.285 + * to the reference list. Selection can be done
1.286 + * in a dynamic way using CVPbkFieldTypeSelector or
1.287 + * static way using resource ids of the field types.
1.288 + * @param aObserver Observer for the find process.
1.289 + * @return New handle to the find operation.
1.290 + */
1.291 + IMPORT_C MVPbkContactOperationBase* FindL(
1.292 + const TDesC& aSearchString,
1.293 + const MVPbkFieldTypeList& aFieldTypes,
1.294 + MVPbkContactFindObserver& aObserver);
1.295 +
1.296 + /**
1.297 + * Finds a string containing text that is stored in one or more
1.298 + * fields asynchronously. Client can give multiple find words.
1.299 + * All the words must match to separated data. E.g. if there are
1.300 + * two find words: "Jo" and "Jo" then field data "John Johnson"
1.301 + * matches but "John Doe" doesn't if the word parser uses
1.302 + * white space as a word separator.
1.303 + *
1.304 + * NOTE: The accuracy of the results depends on the implementation
1.305 + * of the store to carry out the find operation. The performance
1.306 + * can also vary depending on the store.
1.307 + *
1.308 + * @param aSearchStrings strings that are compared to field data.
1.309 + * @param aFieldTypes types of the fields that are used. Constructing
1.310 + * a fieldtype list: use CVPbkFieldTypeRefsList and
1.311 + * append the types that are needed from
1.312 + * the master fieldtype list (FieldTypes())
1.313 + * to the reference list. Selection can be done
1.314 + * in a dynamic way using CVPbkFieldTypeSelector or
1.315 + * static way using resource ids of the fieldtypes.
1.316 + *
1.317 + * @param aObserver an observer for asynchronous operation.
1.318 + * @param aWordParserCallBack a client implementation of word parser
1.319 + * function that separates the field data
1.320 + * into words. Parameter to function is
1.321 + * TVPbkWordParserParam.
1.322 + * @return New handle to the find operation.
1.323 + */
1.324 + IMPORT_C MVPbkContactOperationBase* FindL(
1.325 + const MDesC16Array& aSearchStrings,
1.326 + const MVPbkFieldTypeList& aFieldTypes,
1.327 + MVPbkContactFindFromStoresObserver& aObserver,
1.328 + const TCallBack& aWordParserCallBack );
1.329 +
1.330 + /**
1.331 + * Compresses all stores asynchronously.
1.332 + * NOTE: Not all stores are able to implement compression to their
1.333 + * repositories.
1.334 + *
1.335 + * @param aObserver Operation observer.
1.336 + * @return New handle to the operation.
1.337 + */
1.338 + IMPORT_C MVPbkContactOperationBase* CompressStoresL(
1.339 + MVPbkBatchOperationObserver& aObserver);
1.340 +
1.341 + /**
1.342 + * Returns the file server session of the contact manager.
1.343 + *
1.344 + * @return File server session of the contact manager.
1.345 + */
1.346 + IMPORT_C RFs& FsSession();
1.347 +
1.348 +
1.349 + /**
1.350 + * Finds a string containing text that is stored in one or more
1.351 + * fields asynchronously. Client can give multiple find words.
1.352 + * All the words must match to separated data. E.g. if there are
1.353 + * two find words: "Jo" and "Jo" then field data "John Johnson"
1.354 + * matches but "John Doe" doesn't if the word parser uses
1.355 + * white space as a word separator.
1.356 + *
1.357 + * NOTE: The accuracy of the results depends on the implementation
1.358 + * of the store to carry out the find operation. The performance
1.359 + * can also vary depending on the store.
1.360 + *
1.361 + * @param aSearchStrings strings that are compared to field data.
1.362 + * @param aFieldTypes types of the fields that are used. Constructing
1.363 + * a fieldtype list: use CVPbkFieldTypeRefsList and
1.364 + * append the types that are needed from
1.365 + * the master fieldtype list (FieldTypes())
1.366 + * to the reference list. Selection can be done
1.367 + * in a dynamic way using CVPbkFieldTypeSelector or
1.368 + * static way using resource ids of the fieldtypes.
1.369 + *
1.370 + * @param aObserver an observer for asynchronous operation.
1.371 + * @param aWordParserCallBack a client implementation of word parser
1.372 + * function that separates the field data
1.373 + * into words. Parameter to function is
1.374 + * TVPbkWordParserParam.
1.375 + * @param aStoreEntriesArray an array that lists the store entries
1.376 + * @return New handle to the find operation or NULL if it could not be created.
1.377 + */
1.378 + IMPORT_C MVPbkContactOperationBase* FindL(
1.379 + const MDesC16Array& aSearchStrings,
1.380 + const MVPbkFieldTypeList& aFieldTypes,
1.381 + MVPbkContactFindFromStoresObserver& aObserver,
1.382 + const TCallBack& aWordParserCallBack,
1.383 + const CDesC16ArrayFlat& aStoreEntriesArray );
1.384 +
1.385 + private: // Implementation
1.386 + CVPbkContactManager( TSecurityInfo aSecurityInfo, RFs* aFs );
1.387 + void ConstructL(const CVPbkContactStoreUriArray& aURIList);
1.388 + MVPbkContactStore* FindStore(const TVPbkContactStoreUriPtr& aURI) const;
1.389 + MVPbkContactViewBase* CreateOptimizedCompositeViewLC(
1.390 + MVPbkContactViewObserver& aObserver,
1.391 + const CVPbkContactViewDefinition& aViewDefinition,
1.392 + const MVPbkFieldTypeList& aSortOrder) const;
1.393 + MVPbkContactViewBase* CreateCompositeViewLC(
1.394 + MVPbkContactViewObserver& aObserver,
1.395 + const CVPbkContactViewDefinition& aViewDefinition,
1.396 + const MVPbkFieldTypeList& aSortOrder) const;
1.397 +
1.398 + private: // Data
1.399 + /// Own: Security info for client.
1.400 + TSecurityInfo iSecurityInfo;
1.401 + /// Own: File system handle
1.402 + RFs iFs;
1.403 + /// Own: File system handle that is owned
1.404 + RFs iOwnFs;
1.405 + /// Own: Global Phonebook field types
1.406 + MVPbkFieldTypeList* iFieldTypes;
1.407 + /// Own: List of contact stores
1.408 + CVPbkContactStoreDomainList* iContactStoreDomains;
1.409 + /// Own: Contact attribute manager
1.410 + MVPbkContactAttributeManager* iAttributeManager;
1.411 + /// Own: an internal class for loading stores
1.412 + class CContactStoreLoader;
1.413 + CContactStoreLoader* iStoreLoader;
1.414 + };
1.415 +
1.416 +#endif // CVPBKCONTACTMANAGER_H
1.417 +
1.418 +// End of file