1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/CPbkContactEngine.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,790 @@
1.4 +/*
1.5 +* Copyright (c) 2002 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:
1.18 +* Represents a connection to the Phonebook contact database
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef __CPBKCONTACTENGINE_H__
1.24 +#define __CPBKCONTACTENGINE_H__
1.25 +
1.26 +// INCLUDES
1.27 +#include <e32base.h> // CBase
1.28 +#include <cntdef.h> // TContactItemId
1.29 +#include <cntdbobs.h> // MContactDbObserver
1.30 +#include <f32file.h> // RFs
1.31 +#include "PbkFields.hrh" // TPbkFieldId
1.32 +
1.33 +
1.34 +// FORWARD DECLARATIONS
1.35 +class CContactDatabase;
1.36 +class MIdleFindObserver;
1.37 +class MPbkContactDbObserver;
1.38 +class CContactGroup;
1.39 +class CPbkFieldsInfo;
1.40 +class CPbkContactItem;
1.41 +class CPbkContactIter;
1.42 +class CPbkContactChangeNotifier;
1.43 +class CPbkIdleFinder;
1.44 +class MPbkCompressUi;
1.45 +class CPbkConstants;
1.46 +class MPbkContactNameFormat;
1.47 +class MPbkFieldDataArray;
1.48 +class CContactViewBase;
1.49 +class CContactItem;
1.50 +class RSharedDataClient;
1.51 +class TResourceReader;
1.52 +class CPbkEngineExtension;
1.53 +class CPbkSortOrderManager;
1.54 +class CPbkSINDHandlerInterface;
1.55 +
1.56 +
1.57 +// CLASS DECLARATION
1.58 +
1.59 +/**
1.60 + * The main entrypoint to the Phonebook contact engine. The Phonebook
1.61 + * contact engine builds on top of the Symbian Contacts model and
1.62 + * implements platform specific functionality and policies that can be
1.63 + * reused and followed by clients to implement functionality that is
1.64 + * better integrated to the platform functionality. Functionality like
1.65 + * contact field typing is implemented by this engine.
1.66 + */
1.67 +class CPbkContactEngine :
1.68 + public CBase,
1.69 + private MContactDbObserver
1.70 + {
1.71 + public: // Constructors and destructor
1.72 + /**
1.73 + * Creates a new Phonebook engine object and connects to the default
1.74 + * contact database. If the default database does not exist it is
1.75 + * created.
1.76 + *
1.77 + * @param aFs An open file server connection. If !=NULL aFs is used
1.78 + * instead of a locally created RFs connection. aFs must
1.79 + * remain connected for the lifetime of the returned
1.80 + * object.
1.81 + * @return A new instance of this class.
1.82 + * @exception KErrCorrupt if the database is corrupted.
1.83 + */
1.84 + IMPORT_C static CPbkContactEngine* NewL(RFs* aFs=NULL);
1.85 +
1.86 + /**
1.87 + * @internal
1.88 + * TESTING ONLY
1.89 + * Creates a new engine object and connects it to a specified
1.90 + * database file. If the database file does not exist it is created.
1.91 + *
1.92 + * @param aFileName The database filename.
1.93 + * @param aReplace If ETrue replaces exisiting file with an empty one.
1.94 + * PLEASE NOTE: all data in the existing file
1.95 + * will be lost!
1.96 + * @param aFs An open file server connection. If !=NULL aFs is used
1.97 + * instead of a locally created RFs connection. aFs must
1.98 + * remain connected for the lifetime of the returned
1.99 + * object.
1.100 + * @return A new instance of this class.
1.101 + * @exception KErrCorrupt if the database is corrupted.
1.102 + * @deprecated
1.103 + */
1.104 + IMPORT_C static CPbkContactEngine* NewL
1.105 + (const TDesC& aFileName, TBool aReplace=EFalse, RFs* aFs=NULL);
1.106 +
1.107 + /**
1.108 + * Replaces the default contact database and connects to it. See
1.109 + * Symbian Contacs model documentation for CContactDatabase::ReplaceL
1.110 + * for possible leave codes.
1.111 + * PLEASE NOTE: all data in the existing database will be lost!
1.112 + *
1.113 + * @param aFs An open file server connection. If !=NULL aFs is used
1.114 + * instead of a locally created RFs connection. aFs must
1.115 + * remain connected for the lifetime of the returned
1.116 + * object.
1.117 + * @return A new instance of this class.
1.118 + * @see CContactDatabase::ReplaceL
1.119 + */
1.120 + IMPORT_C static CPbkContactEngine* ReplaceL(RFs* aFs=NULL);
1.121 +
1.122 + /**
1.123 + * Destructor. Destroys this object and closes the contact database
1.124 + * connection. REComSession::FinalClose() is called. Notice that
1.125 + * FinalClose -call releases resource handles of already destroyed ECom
1.126 + * plugins also outside CPbkContactEngine. See REComSession
1.127 + * documentation.
1.128 + */
1.129 + ~CPbkContactEngine();
1.130 +
1.131 + public: // Accessors
1.132 + /**
1.133 + * Returns the global Phonebook engine instance, NULL if no instance
1.134 + * created yet.
1.135 + * Note1: Uses thread local storage (TLS), which is slow. Cache the
1.136 + * returned pointer if it is used more than one time!
1.137 + * Note2: Only the first engine instance created in calling thread can
1.138 + * be accessed with this function.
1.139 + * @return Global Phonebook engine instance.
1.140 + */
1.141 + IMPORT_C static CPbkContactEngine* Static();
1.142 +
1.143 + /**
1.144 + * Returns the underlying CContactDatabase object. Use only if this class's API
1.145 + * is not enough for your purposes.
1.146 + *
1.147 + * @return The underlying Symbian Contacts model CContactDatabase instance.
1.148 + * @see CContactDatabase
1.149 + */
1.150 + IMPORT_C CContactDatabase& Database();
1.151 +
1.152 + /**
1.153 + * Returns the field type info array.
1.154 + * @return All the Phonebook field types.
1.155 + * @see CPbkFieldsInfo
1.156 + */
1.157 + IMPORT_C const CPbkFieldsInfo& FieldsInfo();
1.158 +
1.159 + /**
1.160 + * Returns an open file server session.
1.161 + * @return A handle to a file server session.
1.162 + */
1.163 + IMPORT_C RFs& FsSession() const;
1.164 +
1.165 + public: // Creating contacts
1.166 + /**
1.167 + * Returns a new contact card with default fields.
1.168 + * @return A new empty contact item object.
1.169 + */
1.170 + IMPORT_C CPbkContactItem* CreateEmptyContactL();
1.171 +
1.172 + /**
1.173 + * Adds a new contact to the contact database.
1.174 + *
1.175 + * @param aContact The new contact item to add.
1.176 + * @param aImmediateNotify Send notification to observers immediately.
1.177 + * NOTE: send immediately will result in
1.178 + * observers (MPbkContactDbObserver) receiving
1.179 + * the event twice!
1.180 + * @return The id of the new contact item.
1.181 + * @see CContactDatabase::AddNewContactL
1.182 + */
1.183 + IMPORT_C TContactItemId AddNewContactL
1.184 + (CPbkContactItem& aContact, TBool aImmediateNotify=EFalse);
1.185 +
1.186 + /**
1.187 + * Duplicates a contact in the database.
1.188 + *
1.189 + * @param aId Id of the contact to duplicate.
1.190 + * @param aImmediateNotify Send notification to observers immediately.
1.191 + * NOTE: send immediately will result in
1.192 + * observers (MPbkContactDbObserver) receiving
1.193 + * the event twice!
1.194 + * @return Contact id of the new duplicate.
1.195 + */
1.196 + IMPORT_C TContactItemId DuplicateContactL
1.197 + (TContactItemId aId, TBool aImmediateNotify=EFalse);
1.198 +
1.199 + public: // Reading contacts
1.200 + /**
1.201 + * Reads a contact and returns a phonebook contact item.
1.202 + *
1.203 + * @param aContactId Contact item id to be read.
1.204 + * @param aFieldTypes Array of types of fields to read in, all
1.205 + * fields are read if NULL (which is default).
1.206 + * NOTE: when using this parameter ReadContactL
1.207 + * may return more fields than expected; for example
1.208 + * if aFieldTypes contains any phonenumber the
1.209 + * method may return all phone number fields
1.210 + * of the contact.
1.211 + * @return A new Phonebook contact item.
1.212 + * @see CContactDatabase::ReadContactL
1.213 + */
1.214 + IMPORT_C CPbkContactItem* ReadContactL
1.215 + (TContactItemId aContactId, const CPbkFieldIdArray* aFieldTypes=NULL);
1.216 +
1.217 + /**
1.218 + * Same as ReadContactL, but leaves the returned contact item
1.219 + * on the cleanup stack.
1.220 + *
1.221 + * @param aContactId Contact item id to be read.
1.222 + * @param aFieldTypes Array of types of fields to read in, all
1.223 + * fields are read if NULL (which is default).
1.224 + * NOTE: when using this parameter ReadContactL
1.225 + * may return more fields than expected; for example
1.226 + * if aFieldTypes contains any phonenumber the
1.227 + * method may return all phone number fields
1.228 + * of the contact.
1.229 + * @return A new Phonebook contact item.
1.230 + */
1.231 + IMPORT_C CPbkContactItem* ReadContactLC
1.232 + (TContactItemId aContactId, const CPbkFieldIdArray* aFieldTypes=NULL);
1.233 +
1.234 + /**
1.235 + * Same as ReadContactLC but reads only minimal information. See
1.236 + * Symbian Contacts Model documentation for definition of "minimal" in this
1.237 + * case.
1.238 + *
1.239 + * @param aContactId Contact item id to be read.
1.240 + * @return A new phonebook contact item. Leaves the item on the cleanup stack.
1.241 + * @see CContactDatabase::ReadMinimalContactL
1.242 + */
1.243 + IMPORT_C CPbkContactItem* ReadMinimalContactLC(TContactItemId aContactId);
1.244 +
1.245 + /**
1.246 + * Returns a Phonebook contact iterator.
1.247 + * @param aUseMinimalRead If ETrue the iterator will use the Symbian
1.248 + * Contacts model CContactDatabase::ReadMinimalContactL, EFalse will read
1.249 + * all the contact fields. Default behaviour is to read all fields.
1.250 + * @see CPbkContactIter::NewL.
1.251 + * @see CContactDatabase::ReadMinimalContactL
1.252 + */
1.253 + IMPORT_C CPbkContactIter* CreateContactIteratorLC
1.254 + (TBool aUseMinimalRead=EFalse);
1.255 +
1.256 + public: // Modifying contacts
1.257 + /**
1.258 + * Opens a contact and returns a phonebook contact item.
1.259 + * @param aContactId Contact item id to be opened.
1.260 + * @return A Phonebook contact item that is marked as open in the database.
1.261 + * @see CContactDatabase::OpenContactL
1.262 + */
1.263 + IMPORT_C CPbkContactItem* OpenContactL(TContactItemId aContactId);
1.264 +
1.265 + /**
1.266 + * Same as OpenContactL, but leaves a lock record AND the opened
1.267 + * contact object on the cleanup stack.
1.268 + * Use CleanupStack::PopAndDestroy(2) to close the contact and destroy
1.269 + * the returned object. First pop pops the contact object and second
1.270 + * the lock object.
1.271 + * @param aContactId Contact item id to open.
1.272 + * @return A Phonebook contact item that is marked as open in the database.
1.273 + * @see CContactDatabase::OpenContactLX
1.274 + */
1.275 + IMPORT_C CPbkContactItem* OpenContactLCX(TContactItemId aContactId);
1.276 +
1.277 + /**
1.278 + * Commit changes to a previously opened contact item into the contact
1.279 + * database.
1.280 + *
1.281 + * @param aContact Contact item to be updated in the database.
1.282 + * @param aImmediateNotify Send notification to observers immediately.
1.283 + * NOTE: send immediately will result in
1.284 + * observers (MPbkContactDbObserver) receiving
1.285 + * the event twice!
1.286 + * @see CContactDatabase::CommitContactL
1.287 + */
1.288 + IMPORT_C void CommitContactL
1.289 + (CPbkContactItem& aContact, TBool aImmediateNotify=EFalse);
1.290 +
1.291 + /**
1.292 + * Closes a previously opened contact item without saving changes.
1.293 + * @param aContactId Contact item to be closed.
1.294 + * @see CContactDatabase::CloseContactL
1.295 + */
1.296 + IMPORT_C void CloseContactL(TContactItemId aContactId);
1.297 +
1.298 + public: // Deleting contacts
1.299 + /**
1.300 + * Deletes a contact item from the database.
1.301 + * @param aContactId Contact item to be deleted.
1.302 + * @param aImmediateNotify Send notification to observers immediately.
1.303 + * NOTE: send immediately will result in
1.304 + * observers (MPbkContactDbObserver) receiving
1.305 + * the event twice!
1.306 + * @see CContactDatabase::DeleteContactL
1.307 + */
1.308 + IMPORT_C void DeleteContactL
1.309 + (TContactItemId aContactId, TBool aImmediateNotify=EFalse);
1.310 +
1.311 + /**
1.312 + * Deletes multiple contact items from the database.
1.313 + * @param aContactIds Contact items to be deleted.
1.314 + * @param aImmediateNotify Send notification to observers immediately.
1.315 + * NOTE: send immediately will result in
1.316 + * observers (MPbkContactDbObserver) receiving
1.317 + * the event twice!
1.318 + * @see CContactDatabase::DeleteContactsL
1.319 + */
1.320 + IMPORT_C void DeleteContactsL
1.321 + (const CContactIdArray& aContactIds, TBool aImmediateNotify=EFalse);
1.322 +
1.323 + /**
1.324 + * Deletes multiple contacts from the database in an active object
1.325 + * -driven asynchronous background process.
1.326 + *
1.327 + * @param aContactIds Contacts to delete.
1.328 + */
1.329 + IMPORT_C void DeleteContactsOnBackgroundL
1.330 + (const CContactIdArray& aContactIds);
1.331 +
1.332 + public: // Contact groups
1.333 + /**
1.334 + * Creates a new contact group.
1.335 + *
1.336 + * @param aGroupLabel Group name.
1.337 + * @param aInTransaction See Symbian Contacts Model documentation
1.338 + * for CContactDatabase::CreateContactGroupL documentation.
1.339 + * @see CContactDatabase::CreateContactGroupL
1.340 + */
1.341 + IMPORT_C CContactGroup* CreateContactGroupL
1.342 + (const TDesC& aGroupLabel,TBool aInTransaction=EFalse);
1.343 +
1.344 + /**
1.345 + * Adds a Contact to a group.
1.346 + *
1.347 + * @param aItemId Contact to be added to group.
1.348 + * @param aGroupId Group where the contact will be added to.
1.349 + * @see CContactDatabase::AddContactToGroupL
1.350 + */
1.351 + IMPORT_C void AddContactToGroupL
1.352 + (TContactItemId aItemId, TContactItemId aGroupId);
1.353 +
1.354 + /**
1.355 + * Removes a contact from a group
1.356 + *
1.357 + * @param aItemId Contact to be removed from group.
1.358 + * @param aGroupId Group where the contact will be removed from.
1.359 + * @see CContactDatabase::RemoveContactFromGroupL
1.360 + */
1.361 + IMPORT_C void RemoveContactFromGroupL
1.362 + (TContactItemId aItemId, TContactItemId aGroupId);
1.363 +
1.364 + /**
1.365 + * Reads a Contact group.
1.366 + *
1.367 + * @param aId Group id.
1.368 + * @return Contact group object.
1.369 + * @see CContactDatabase::ReadContactL
1.370 + */
1.371 + IMPORT_C CContactGroup* ReadContactGroupL(TContactItemId aId);
1.372 +
1.373 + /**
1.374 + * Opens a Contact group for modification.
1.375 + *
1.376 + * @param aId Groups id
1.377 + * @return Contact group object.
1.378 + * @see CContactDatabase::OpenContactL
1.379 + */
1.380 + IMPORT_C CContactGroup* OpenContactGroupL(TContactItemId aId);
1.381 +
1.382 + /**
1.383 + * Opens a Contact group for modification. Pushes the returned
1.384 + * contact group object and a lock item on the cleanup stack.
1.385 + *
1.386 + * @param aId Groups id
1.387 + * @return Contact group object.
1.388 + * @see CContactDatabase::OpenContactLX
1.389 + */
1.390 + IMPORT_C CContactGroup* OpenContactGroupLCX(TContactItemId aId);
1.391 +
1.392 + /**
1.393 + * Commits changes to a contact group to the database.
1.394 + *
1.395 + * @param aId Groups id
1.396 + * @param aImmediateNotify Send notification to observers immediately.
1.397 + * NOTE: send immediately will result in
1.398 + * observers (MPbkContactDbObserver) receiving
1.399 + * the event twice!
1.400 + * @see CContactDatabase::CommitContactL
1.401 + */
1.402 + IMPORT_C void CommitContactGroupL(CContactGroup& aGroup, TBool aImmediateNotify=EFalse);
1.403 +
1.404 + /**
1.405 + * Deletes a contact group from the database.
1.406 + * @param aContactId Contact group to be deleted.
1.407 + * @param aImmediateNotify Send notification to observers immediately.
1.408 + * NOTE: send immediately will result in
1.409 + * observers (MPbkContactDbObserver) receiving
1.410 + * the event twice!
1.411 + * @see CContactDatabase::DeleteContactL
1.412 + */
1.413 + IMPORT_C void DeleteContactGroupL
1.414 + (TContactItemId aContactId, TBool aImmediateNotify=EFalse);
1.415 +
1.416 + public: // Speed dials
1.417 + /**
1.418 + * Sets a speed dial to a contact field.
1.419 + *
1.420 + * @param aItem Contact item to add speed dial to.
1.421 + * @param aFieldIndex Field index to add Speed dial to.
1.422 + * @param aSpeedDialPosition Speed dial position number to set to
1.423 + * the field.
1.424 + * @see CContactDatabase::SetFieldAsSpeedDialL
1.425 + */
1.426 + IMPORT_C void SetFieldAsSpeedDialL
1.427 + (CPbkContactItem& aItem, TInt aFieldIndex, TInt aSpeedDialPosition);
1.428 +
1.429 + /**
1.430 + * Returns a speed dial contact.
1.431 + *
1.432 + * @param aSpeedDialPosition Speed dial position number.
1.433 + * @param aPhoneNumber Phone number
1.434 + * @see CContactDatabase::GetSpeedDialFieldL.
1.435 + */
1.436 + IMPORT_C TContactItemId GetSpeedDialFieldL
1.437 + (TInt aSpeedDialPosition, TDes& aPhoneNumber) const;
1.438 +
1.439 + /**
1.440 + * Removes a speed dial from a contact.
1.441 + *
1.442 + * @param aContactId Contact item to remove the speed dial from.
1.443 + * @param aSpeedDialPosition Speed dial position number to remove.
1.444 + * @see CContactDatabase::RemoveSpeedDialFieldL.
1.445 + */
1.446 + IMPORT_C void RemoveSpeedDialFieldL
1.447 + (TContactItemId aContactId, TInt aSpeedDialPosition);
1.448 +
1.449 + /**
1.450 + * Returns ETrue if this field has been assigned a speed dial position.
1.451 + *
1.452 + * @param aItem contact Item to check for speed dial.
1.453 + * @param aFieldIndex Index of the field to check. This is an index
1.454 + * into aItem.CardFields().
1.455 + * @return ETrue if Speed dial exitst, EFalse if not.
1.456 + */
1.457 + IMPORT_C TBool IsSpeedDialAssigned
1.458 + (const CPbkContactItem& aItem, TInt aFieldIndex) const;
1.459 +
1.460 + public: // Contact views
1.461 + /**
1.462 + * Returns a contact view object containing all the contacts in the
1.463 + * database.
1.464 + *
1.465 + * @return Contact view containing all the contacts in the database.
1.466 + * @see CContactViewBase
1.467 + */
1.468 + IMPORT_C CContactViewBase& AllContactsView();
1.469 +
1.470 + /**
1.471 + * Returns a contact view object containing all the groups in the
1.472 + * database.
1.473 + *
1.474 + * @return Contact view containing all the groups in the database.
1.475 + * @see CContactViewBase
1.476 + */
1.477 + IMPORT_C CContactViewBase& AllGroupsViewL();
1.478 +
1.479 + /**
1.480 + * Returns a contact view object containing all the contacts in the
1.481 + * database that match a filter.
1.482 + *
1.483 + * @param aFilter Use CContactDatabase::TContactViewFilter.
1.484 + * @see CContactViewBase
1.485 + */
1.486 + IMPORT_C CContactViewBase& FilteredContactsViewL(TInt aFilter);
1.487 +
1.488 + public: // Events
1.489 + /**
1.490 + * Creates and returns a new CPbkContactChangeNotifier for the
1.491 + * default contact database. The returned object attaches aObserver
1.492 + * to this engine instance as long as the object exists.
1.493 + *
1.494 + * @param aObserver Observer to attach to this object.
1.495 + * @return New CPbkContactChangeNotifier object. Caller is responsible
1.496 + * of the object.
1.497 + * @see CPbkContactChangeNotifier
1.498 + * @see MPbkContactDbObserver
1.499 + */
1.500 + IMPORT_C CPbkContactChangeNotifier* CreateContactChangeNotifierL
1.501 + (MPbkContactDbObserver* aObserver);
1.502 +
1.503 + public: // Contact name formatting
1.504 + /**
1.505 + * Gets a title text for a contact or localised text for unnamed
1.506 + * contact if contact contains no title.
1.507 + *
1.508 + * @param aItem Contact item for which to make the title.
1.509 + * @return A buffer containing the title or unnamed text if no title
1.510 + * can be generated. Caller is responsible of deleting the
1.511 + * returned buffer.
1.512 + */
1.513 + IMPORT_C HBufC* GetContactTitleL(const CPbkContactItem& aItem) const;
1.514 +
1.515 + /**
1.516 + * Similar to GetContactTitleL but returns NULL if contact contains no
1.517 + * title. Uses the MPbkFieldDataArray interface to access the field
1.518 + * content.
1.519 + * @param aContactData The contact field data array.
1.520 + * @return Contact title, NULL if field array did not contain any fields
1.521 + * used to for constructing contact titles.
1.522 + * @see CPbkContactEngine::GetContactTitleL
1.523 + */
1.524 + IMPORT_C HBufC* GetContactTitleOrNullL
1.525 + (const MPbkFieldDataArray& aContactData);
1.526 +
1.527 + /**
1.528 + * Returns ETrue if field is one of the fields used in building the
1.529 + * contact title.
1.530 + *
1.531 + * @param aFieldId The id of the field.
1.532 + * @return ETrue if aFieldId is type of a field used to build contact
1.533 + * titles.
1.534 + * @see GetContactTitleL
1.535 + * @see GetContactTitleOrNullL
1.536 + */
1.537 + IMPORT_C TBool IsTitleField(TPbkFieldId aFieldId) const;
1.538 +
1.539 + /**
1.540 + * @internal
1.541 + * Returns the contact name formatter.
1.542 + *
1.543 + * @see MPbkContactNameFormat
1.544 + * @deprecated
1.545 + */
1.546 + IMPORT_C MPbkContactNameFormat& ContactNameFormat() const;
1.547 +
1.548 + /**
1.549 + * Returns the localised title text to use for unnamed contacts.
1.550 + * @return Localised title text to use for unnamed contacts.
1.551 + */
1.552 + IMPORT_C const TDesC& UnnamedTitle() const;
1.553 +
1.554 + public: // Searching
1.555 + /**
1.556 + * Call-through for new Phone number matching function in 6.2 version
1.557 + * of class CContactDatabase. If you don't need any other functionality
1.558 + * from CPbkContactEngine than this consider using the CContactDatabase
1.559 + * API directly. See Symbian Contacts Model documentation for
1.560 + * CContactDatabase::MatchPhoneNumberL use.
1.561 + *
1.562 + * @see CContactDatabase::MatchPhoneNumberL(const TDesC&,const TInt)
1.563 + */
1.564 + IMPORT_C CContactIdArray* MatchPhoneNumberL
1.565 + (const TDesC& aNumber, const TInt aMatchLengthFromRight);
1.566 +
1.567 + /**
1.568 + * Searches all contacts in the database for aText.
1.569 + *
1.570 + * @param aText Text to search.
1.571 + * @param aFieldTypes Phonebook fields types to <i>at least</i>
1.572 + * include in the search. If NULL searches all
1.573 + * fields.<br>
1.574 + * <b>PLEASE NOTE:</b> The find matches in most
1.575 + * cases also other fields than those specified
1.576 + * in aFieldTypes. Always loop through the
1.577 + * returned contacts to check match in the
1.578 + * required fields.
1.579 + * @return Array of matching contact IDs.
1.580 + * @see CContactDatabase::FindLC.
1.581 + */
1.582 + IMPORT_C CContactIdArray* FindLC
1.583 + (const TDesC& aText, const CPbkFieldIdArray* aFieldTypes=NULL);
1.584 +
1.585 + /**
1.586 + * Searches all contacts in the database for aText asynchronously.
1.587 + *
1.588 + * @param aText Text to search.
1.589 + * @param aFieldTypes Phonebook fields types to <i>at least</i>
1.590 + * include in the search. If NULL searches all
1.591 + * fields.<br>
1.592 + * <b>PLEASE NOTE:</b> The find matches in most
1.593 + * cases also other fields than those specified
1.594 + * in aFieldTypes. Always loop through the
1.595 + * returned contacts to check match in the
1.596 + * required fields.
1.597 + * @param aObserver Observer for this operation.
1.598 + * @return CPbkIdleFinder object which is used to access the find
1.599 + * results when complete. Deleting this object will cancel
1.600 + * this asyncronous find operation.
1.601 + * @see CContactDatabase::FindAsyncL.
1.602 + * @see CPbkIdleFinder
1.603 + */
1.604 + IMPORT_C CPbkIdleFinder* FindAsyncL(
1.605 + const TDesC& aText,
1.606 + const CPbkFieldIdArray* aFieldTypes=NULL,
1.607 + MIdleFindObserver *aObserver=NULL);
1.608 +
1.609 + public: // Phonebook internal API
1.610 + /**
1.611 + * @internal
1.612 + * Sets the compression UI for this engine.
1.613 + * To be called by Phonebook only!
1.614 + *
1.615 + * @see MPbkCompressUi
1.616 + * @see CheckCompress
1.617 + * @see CancelCompress
1.618 + * @deprecated
1.619 + */
1.620 + IMPORT_C void SetCompressUi(MPbkCompressUi* aCompressiUi);
1.621 +
1.622 + /**
1.623 + * @internal
1.624 + * Checks if the contact database needs a compression.
1.625 + * To be called by Phonebook only!
1.626 + *
1.627 + * @see SetCompressUi
1.628 + * @see CompressL
1.629 + * @see CancelCompress
1.630 + * @deprecated
1.631 + */
1.632 + IMPORT_C TBool CheckCompress();
1.633 +
1.634 + /**
1.635 + * @internal
1.636 + * Compresses the database if necessary. To be called by Phonebook only.
1.637 + *
1.638 + * @see SetCompressUi
1.639 + * @see CancelCompress
1.640 + * @deprecated
1.641 + */
1.642 + IMPORT_C void CompressL();
1.643 +
1.644 + /**
1.645 + * @internal
1.646 + * Call to cancel any ongoing database compression started with
1.647 + * CheckCompressL(). Calls PbkCompressCanceled() for any registered
1.648 + * compression UI. To be called by Phonebook only.
1.649 + *
1.650 + * @see SetCompressUi
1.651 + * @see CheckCompress
1.652 + * @deprecated
1.653 + */
1.654 + IMPORT_C void CancelCompress();
1.655 +
1.656 + /**
1.657 + * @internal
1.658 + * Checks current file system space and amount of wasted space in
1.659 + * Phonebook's database. Compresses the database synchronously if
1.660 + * Phonebook's database can be made smaller by compression. If file
1.661 + * system space is still under critical level after compression,
1.662 + * leaves with KErrDiskFull.
1.663 + *
1.664 + * @exception KErrDiskFull if file system is out of space.
1.665 + * @deprecated
1.666 + */
1.667 + IMPORT_C void CheckFileSystemSpaceAndCompressL();
1.668 +
1.669 + /**
1.670 + * @internal
1.671 + * Phonebook name ordering information.
1.672 + * @deprecated
1.673 + */
1.674 + enum TPbkNameOrder
1.675 + {
1.676 + EPbkNameOrderLastNameFirstName = 0, /// Last name then first name order
1.677 + EPbkNameOrderFirstNameLastName, /// First name then last name order
1.678 + EPbkNameOrderNotDefined /// undefined name order
1.679 + };
1.680 +
1.681 + /**
1.682 + * @internal
1.683 + * Sets name display order.
1.684 + * @param aNameOrder The ordering to use
1.685 + * @deprecated
1.686 + */
1.687 + IMPORT_C void SetNameDisplayOrderL(TPbkNameOrder aNameOrder);
1.688 +
1.689 + /**
1.690 + * @internal
1.691 + * Gets name display order.
1.692 + * @return The name ordering in use
1.693 + * @deprecated
1.694 + */
1.695 + IMPORT_C TPbkNameOrder NameDisplayOrderL();
1.696 +
1.697 + /**
1.698 + * @internal
1.699 + * Returns the phonebook constants object.
1.700 + * @return Phonebook constants manager
1.701 + * @deprecated
1.702 + */
1.703 + IMPORT_C CPbkConstants* Constants();
1.704 +
1.705 + /**
1.706 + * @internal
1.707 + * Returns the sort order manager of the engine.
1.708 + */
1.709 + const CPbkSortOrderManager& SortOrderManager() const;
1.710 +
1.711 +
1.712 + /**
1.713 + * @internal
1.714 + * Sets whether a separator character is shown between
1.715 + * last and first names.
1.716 + * @param aSeparator This parameter should contain the character to be
1.717 + * used as separator. If value is 0 then separator will not be
1.718 + * used between names.
1.719 + */
1.720 + IMPORT_C void SetNameSeparatorL(TChar aSeparator);
1.721 +
1.722 + /**
1.723 + * @internal
1.724 + * Return info on whether separator character is used between last
1.725 + * and first names.
1.726 + * @return The separator character. Empty (value 0) if there is no
1.727 + * separator.
1.728 + */
1.729 + IMPORT_C TChar NameSeparator() const;
1.730 +
1.731 +
1.732 +
1.733 + private: // from MContactDbObserver
1.734 + void HandleDatabaseEventL(TContactDbObserverEvent aEvent);
1.735 +
1.736 + private: // Interface for CPbkContactChangeNotifier
1.737 + friend class CPbkContactChangeNotifier;
1.738 + void AddObserverL(MPbkContactDbObserver* aObserver);
1.739 + void RemoveObserver(MPbkContactDbObserver* aObserver);
1.740 + void SendEventToAllObservers(const TContactDbObserverEvent& aEvent);
1.741 +
1.742 + private: // Implementation
1.743 + CPbkContactEngine();
1.744 + void ConstructL(const TDesC* aFileName, TBool aReplace, RFs* aFs);
1.745 + void ConnectFsL(RFs* aRfs);
1.746 + void ReadResourcesL(TBool& aSettingsVisibility);
1.747 + void CreateDbConnectionL(const TDesC* aFileName,
1.748 + TBool aReplace,
1.749 + TInt& aDbOpenError,
1.750 + TBool aSettingsVisible);
1.751 + void SendImmidiateEventToAllObservers(
1.752 + TContactDbObserverEventType aEventType,
1.753 + TContactItemId aContactId, TBool aSendEvent);
1.754 + void doDeleteContactL(TContactItemId aContactId);
1.755 + class CContactDbConnection;
1.756 + friend class CContactDbConnection;
1.757 + friend class CPbkSharedDataObserver;
1.758 +
1.759 + private: // Data
1.760 + /// Ref: file server connection
1.761 + RFs iFs;
1.762 + /// Own: file server connection
1.763 + RFs iOwnFs;
1.764 + /// Own: Contact database connection object.
1.765 + CContactDbConnection* iDbConnection;
1.766 + /// Own: Observer array
1.767 + CArrayPtr<MPbkContactDbObserver>* iObservers;
1.768 + /// Own: fields info array.
1.769 + CPbkFieldsInfo* iPbkFieldsInfo;
1.770 + /// Own: Phonebook constants
1.771 + CPbkConstants* iPbkConstants;
1.772 + /// Own: shared data client
1.773 + RSharedDataClient* iSharedDataClient;
1.774 + /// Own: maximum free space required to delete a contact from the DB
1.775 + TInt iFreeSpaceRequiredToDelete;
1.776 + /// Own: Engine extension interface
1.777 + CPbkEngineExtension* iExtension;
1.778 + /// Is separator used between first- and last-names of contacts
1.779 + TBool iUseSeparator;
1.780 + /// The separator to be used between first- and last-names of contacts
1.781 + TChar iSeparator;
1.782 + /// CPbkSINDHandler instance identifier key.
1.783 + TUid iDtorIDKey;
1.784 + /// Own: SIND Handler
1.785 + CPbkSINDHandlerInterface* iSINDHandler;
1.786 +
1.787 +
1.788 +
1.789 + };
1.790 +
1.791 +#endif // __CPBKCONTACTENGINE_H__
1.792 +
1.793 +// End of File