epoc32/include/app/CPbkContactEngine.h
branchSymbian3
changeset 4 837f303aceeb
     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