diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/app/CPbkContactItem.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/app/CPbkContactItem.h Wed Mar 31 12:33:34 2010 +0100 @@ -0,0 +1,627 @@ +/* +* Copyright (c) 2002 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: +* Phonebook Contact item class. +* +*/ + + +#ifndef __CPbkContactItem_H__ +#define __CPbkContactItem_H__ + +// INCLUDES +#include // CBase, CArrayFixFlat +#include "MPbkFieldData.h" // MPbkFieldDataArray +#include "PbkFields.hrh" // TPbkFieldId +#include "TPbkContactItemField.h" + +// FORWARD DECLARATIONS +class CPbkFieldsInfo; +class CPbkFieldInfo; +class CContactItemField; +class CContactItem; +class MPbkContactNameFormat; + + +// CLASS DECLARATION + +/** + * Array of TPbkContactItemField instances. + */ +class CPbkFieldArray : public CArrayFixFlat + { + public: + enum + { + /// Default array reallocation granularity + KDefaultGranularity = 8 + }; + + /** + * Constructor. + */ + inline CPbkFieldArray() + : CArrayFixFlat(KDefaultGranularity) + { + } + + /** + * Constructor. + * @param aGranularity Reallocation granularity of this array. + */ + inline CPbkFieldArray(TInt aGranurality) + : CArrayFixFlat(aGranurality) + { + } + }; + + +/** + * Phonebook Contact item class. Contact items can be read from the contact + * database by using the Phonebook engine, @see CPbkContactEngine. + * This class extends Symbian Contacts model class CContactItem capabilities + * to better suit Phonebook application's needs. + */ +class CPbkContactItem : + public CBase, public MPbkFieldDataArray + { + public: // Constructor and destructor + /** + * Creates an instance of this class. + * + * @param aItem Contact item this object wraps. This object + * takes ownership of aItem. If this function + * leaves, ownership is not taken. + * @param aFieldsInfo Collection of Phonebook field types. + * @param aNameFormat Contact name formatter. + * @return A new instance of this class. + */ + IMPORT_C static CPbkContactItem* NewL( + CContactItem* aItem, + const CPbkFieldsInfo& aFieldsInfo, + MPbkContactNameFormat& aNameFormat); + + /** + * Destructor. + */ + ~CPbkContactItem(); + + public: // CContactItem functions + /** + * Returns this contact item's id. + * @see CContactItem::Id() + */ + IMPORT_C TContactItemId Id() const; + + /** + * Returns type of this contact item. The contact types are documented in + * the Symbian Contacts model CContactItem::Type(). + * @return Contact type. + * @see CContactItem::Type() + */ + IMPORT_C TUid Type() const; + + /** + * Gets the groups this contact belongs to. + * @return Array of group ids. Caller owns the array. + * @see CContactItem::GroupsJoinedLC() + */ + IMPORT_C CContactIdArray* GroupsJoinedLC() const; + + /** + * Converts this object to a CContactItem. Use only if this class's API + * is not enough. + * @return The underlying Symbian Contacts model contact item object. + */ + IMPORT_C CContactItem& ContactItem(); + + /** + * Converts this object to a const CContactItem. Use only if this + * class's API is not enough. + * @return The underlying Symbian Contacts model contact item object. + */ + IMPORT_C const CContactItem& ContactItem() const; + + public: // Field set operations + /** + * Returns the field set of this contact item. + * @return Field array of this contact item. + */ + IMPORT_C CPbkFieldArray& CardFields() const; + + /** + * Creates a new field based on aFieldInfo and adds it to this contact. + * + * @param aFieldInfo Type of field to create. + * @return The created field. + */ + IMPORT_C TPbkContactItemField& AddFieldL(CPbkFieldInfo& aFieldInfo); + + /** + * Returns ETrue if data of type aFieldInfo can be added to this + * contact. + * @param aFieldInfo The field type that we are trying to add. + * @return ETrue if the contact can accept this type of data, EFalse + * otherwise. + */ + IMPORT_C TBool CanAcceptDataOfType(CPbkFieldInfo& aFieldInfo) const; + + /** + * Finds an unused or creates a new field based on aFieldInfo. An + * unused field is a field that is in the contact template, but + * doesnt contain any data, in other words it is empty. So a unused + * field is preferred ad the next field to add user data before + * adding a new field to the contact. + * + * @param aFieldInfo Type of field to search or create. + * @return Pointer to the found or created field. NULL only if
+ * field exists AND
+ * field is nonempty AND
+ * aFieldInfo.Multiplicity()==EPbkFieldMultiplicityOne. + */ + IMPORT_C TPbkContactItemField* AddOrReturnUnusedFieldL + (CPbkFieldInfo& aFieldInfo); + + /** + * Deletes field at aIndex. + * @param aIndex Field index to delete from the contact item. + */ + IMPORT_C void RemoveField(TInt aIndex); + + /** + * Updates this contacts field set to match the field set of + * the owned CContactItem. No need to call unless contact item's + * field set has been manipulated directly. In other words + * remaps the field types of this contact item from the underlying + * Symbian Contacts model contact item. + * @param aFieldsInfo The new fields set for this contact. + */ + IMPORT_C void UpdateFieldSetL(const CPbkFieldsInfo& aFieldsInfo); + + public: // Field searching + /** + * Returns first field matching aFieldId. + * + * @param aFieldId Field id to search. + * @return First field matching aFieldId, NULL if none found. + */ + IMPORT_C TPbkContactItemField* FindField(TPbkFieldId aFieldId) const; + + /** + * Returns first field matching aFieldId starting from aIndex. + * + * @param aFieldId Field id to search. + * @param aIndex Input: field index where to start the search from, + * output: index of the found field or -1 if not found. + * @return Field matching aFieldId, NULL if none found. + */ + IMPORT_C TPbkContactItemField* FindField + (TPbkFieldId aFieldId, TInt& aIndex) const; + + /** + * Returns first field matching aFieldInfo. + * + * @param aFieldInfo Field type to find from the contact. + * @return First field matching aFieldInfo, NULL if none found. + */ + IMPORT_C TPbkContactItemField* FindField(const CPbkFieldInfo& aFieldInfo) const; + + /** + * Returns first field matching aFieldInfo starting from aIndex. + * + * @param aFieldInfo Field type to find from the contact. + * @param aIndex Input: field index where to start the search from, + * output: index of the found field or -1 if not found. + * @return Field matching aFieldInfo, NULL if none found. + */ + IMPORT_C TPbkContactItemField* FindField + (const CPbkFieldInfo& aFieldInfo, TInt& aIndex) const; + + /** + * Returns aField's index from this contact item. + * + * @param aField Field to search for. Field is matched with + * TPbkContactItemField::IsSame -function. + * @return Index of aField in this contact item's field set, + * KErrNotFound if not found. + * @see TPbkContactItemField::IsSame + */ + IMPORT_C TInt FindFieldIndex(const TPbkContactItemField& aField) const; + + /** + * Returns aField's index from ContactItem()'s CardFields() or + * KErrNotFound if not found. + * @param aField The field which index we are querying. + * @return The fields index in this contact item, KErrNotFound is not found. + */ + IMPORT_C TInt FindContactItemFieldIndex(const CContactItemField& aField) const; + + /** + * Searches phone number fields of this contact for a match. + * Uses PbkEngUtils::ContainSameDigits to perform the matching. + * + * @param aNumber Phone number to match to. + * @param aNumberOfDigits Number of digits to compare from the end + * of the phone numbers. Full comparison + * performed if 0. + * @param aIndex Input: field index where to start the search from, + * output: index of the found field or KErrNotFound if not found. + * @return The matching field, NULL if not found. + * @see PbkEngUtils::ContainSameDigits + */ + IMPORT_C TPbkContactItemField* FindNextFieldWithPhoneNumber + (const TDesC& aNumber, + TInt aNumberOfDigits, + TInt &aIndex) const; + + /** + * Searches for a text in this contact's fields. Uses TDesC::FindF() + * search the text from the fields. + * + * @param aIndex Input: field index from where to start the search, + * Output: index of the found field or KErrNotFound + * if not found. + * @return The matching field, NULL if not found. + * @see TDesC::FindF + */ + IMPORT_C TPbkContactItemField* FindNextFieldWithText + (const TDesC& aText, + TInt& aIndex) const; + + /** + * Returns field matching aField from this contact item's field set, NULL if + * not found. + * @param aField The field that we a mathing. + * @return Matching field or NULL if not found. + * @postcond !FindSameField(field) || FindSameField(field)->IsSame(field) + */ + IMPORT_C TPbkContactItemField* FindSameField + (const TPbkContactItemField& aField) const; + + public: // Contact presentation + /** + * Gets a title text for this contact or localized unnamed text. + * + * @return A buffer containing the title or localized unnamed text if no + * title can be generated. Caller is responsible for deleting + * the returned buffer. + */ + IMPORT_C HBufC* GetContactTitleL() const; + + /** + * Gets a title text for this contact. + * + * @return A buffer containing the title text, NULL if title is empty. + * Caller is responsible for deleting the returned buffer. + */ + IMPORT_C HBufC* GetContactTitleOrNullL() const; + + /** + * Returns an Phonebook icon id for a contact. This icon id is the icon + * of the field that is set as the default number to call. + * + * @return Icon index for this contact, EPbkNullIconId for no icon. + */ + IMPORT_C TPbkIconId ContactIconIdL() const; + + public: // Defaults + /** + * Returns the default phone number field of this contact. + * + * @return Default phone number field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultPhoneNumberField() const; + + /** + * Sets this contact's default phone number field to aField. + * + * @param aField Field to set as default, if NULL phone number + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound If aField is not this contact's field. + * @exception KErrNotSupported If aField is not a phone number field. + */ + IMPORT_C void SetDefaultPhoneNumberFieldL + (TPbkContactItemField* aField); + + /** + * Removes phone number default from this contact. + * + * @postcond DefaultPhoneNumberField()==NULL. + */ + IMPORT_C void RemoveDefaultPhoneNumberField(); + + /** + * Returns the default video number field of this contact. + * + * @return Default video number field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultVideoNumberField() const; + + /** + * Sets this contact's default video number field to aField. + * + * @param aField Field to set as default, if NULL video number + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound if aField is not this contact's field. + * @exception KErrNotSupported if aField is not a phone number field. + */ + IMPORT_C void SetDefaultVideoNumberFieldL + (TPbkContactItemField* aField); + + /** + * Removes video number default from this contact. + * + * @postcond DefaultVideoNumberField()==NULL. + */ + IMPORT_C void RemoveDefaultVideoNumberField(); + + /** + * Returns the default SMS field of this contact. + * + * @return Default SMS field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultSmsField() const; + + /** + * Sets this contact's default SMS field to aField. + * + * @param aField Field to set as default, if NULL SMS + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound if aField is not this contact's field. + * @exception KErrNotSupported if aField is not a phone number field. + */ + IMPORT_C void SetDefaultSmsFieldL(TPbkContactItemField* aField); + + /** + * Removes SMS field default from this contact. + * + * @postcond DefaultSmsField()==NULL. + */ + IMPORT_C void RemoveDefaultSmsField(); + + /** + * Returns the default email field of this contact. + * + * @return Default email field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultEmailField() const; + + /** + * Sets this contact's default email address field to aField. + * + * @param aField Field to set as default, if NULL email + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound If aField is not this contact's field. + * @exception KErrNotSupported If aField is not an email field. + */ + IMPORT_C void SetDefaultEmailFieldL(TPbkContactItemField* aField); + + /** + * Removes email field default from this contact. + * + * @postcond DefaultEmailField()==NULL. + */ + IMPORT_C void RemoveDefaultEmailField(); + + /** + * Returns the default Mms field of this contact. + * + * @return Default Mms field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultMmsField() const; + + /** + * Sets this contact's default MMS address field to aField. + * + * @param aField Field to set as default, if NULL MMS + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound If aField is not this contact's field. + * @exception KErrNotSupported If aField is not an email field. + */ + IMPORT_C void SetDefaultMmsFieldL(TPbkContactItemField* aField); + + /** + * Removes MMS field default from this contact. + * + * @postcond DefaultMmsField()==NULL. + */ + IMPORT_C void RemoveDefaultMmsField(); + + /** + * Returns the default Poc field of this contact. + * + * @return Default Poc field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultPocField() const; + + /** + * Sets this contact's default POC address field to aField. + * + * @param aField Field to set as default, if NULL POC + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound If aField is not this contact's field. + * @exception KErrNotSupported If aField is not an email field. + */ + IMPORT_C void SetDefaultPocFieldL(TPbkContactItemField* aField); + + /** + * Removes POC field default from this contact. + * + * @postcond DefaultPocField()==NULL. + */ + IMPORT_C void RemoveDefaultPocField(); + + /** + * Returns the default VOIP field of this contact. + * + * @return Default VOIP field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultVoipField() const; + + /** + * Sets this contact's default VOIP address field to aField. + * + * @param aField Field to set as default, if NULL VOIP + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound If aField is not this contact's field. + * @exception KErrNotSupported If aField is not an email field. + */ + IMPORT_C void SetDefaultVoipFieldL(TPbkContactItemField* aField); + + /** + * Removes VOIP field default from this contact. + * + * @postcond DefaultVoipField()==NULL. + */ + IMPORT_C void RemoveDefaultVoipField(); + + /** + * Returns the default EmailOverSms field of this contact. + * + * @return Default EmailOverSms field of this contact, + * NULL if no default set. + */ + IMPORT_C TPbkContactItemField* DefaultEmailOverSmsField() const; + + /** + * Sets this contact's default Sms With Email address field to aField. + * + * @param aField Field to set as default, if NULL Sms With Email + * default is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound If aField is not this contact's field. + * @exception KErrNotSupported If aField is not an email field. + */ + IMPORT_C void SetDefaultEmailOverSmsFieldL(TPbkContactItemField* aField); + + /** + * Removes EmailOverSms field default from this contact. + * + * @postcond DefaultEmailOverSmsField()==NULL. + */ + IMPORT_C void RemoveDefaultEmailOverSmsField(); + + public: // Voice tags + /** + * Returns the voice tag field of this contact. + * NOTE: If this function is unable to make a connection to + * the voice tag handling system for some reason, this function will + * return null. + * + * @return Voice tag field of this contact, + * NULL if no voice tag set. + * @deprecated + */ + IMPORT_C TPbkContactItemField* VoiceTagField() const; + + /** + * Sets this contact's voice tag field to aField. + * + * @param aField Field to set as default, if NULL voice tag mark + * is removed. Guaranteed not to leave if + * aField is NULL. + * @exception KErrNotFound If aField is not this contact's field. + * @exception KErrNotSupported If aField is not a phone number field. + * @postcond (aField && VoiceTagField()->IsSame(*aField)) || (!aField && !VoiceTagField()) + * @deprecated + */ + IMPORT_C void SetVoiceTagFieldL(TPbkContactItemField* aField); + + /** + * Removes any voice tag mark from this contact. + * + * @postcond VoiceTagField()==NULL. + * @deprecated + */ + IMPORT_C void RemoveVoiceTagField(); + + public: // from MPbkFieldDataArray + TInt PbkFieldCount() const; + MPbkFieldData& PbkFieldAt(TInt aIndex); + const MPbkFieldData& PbkFieldAt(TInt aIndex) const; + + public: // Phonebook internal functions, do not call + /** + * @internal + * Prepares this contact for saving into the contact database. + * @see PrepareAfterLoad + * @deprecated + */ + void PrepareForSaveL(); + + /** + * @internal + * Prepares this contact after loading it from the contact database. + * @see PrepareForSaveL + * @deprecated + */ + void PrepareAfterLoadL(); + + private: // Implementation + CPbkContactItem(MPbkContactNameFormat& aNameFormat); + void ConstructL(CContactItem* aItem, const CPbkFieldsInfo& aFieldsInfo); + void CreateFieldArrayL(CContactItem& aContactItem, const CPbkFieldsInfo& aFieldsInfo); + TInt InsertionPos(const TPbkContactItemField& aField) const; + __DECLARE_TEST; + typedef CPbkContactItem SelfType; + + private: // Data + /// Own: Embedded contact item. + CContactItem* iItem; + /// Own: array of phonebook contact item fields + CPbkFieldArray iFields; + /// Ref: Contact name formatting API + MPbkContactNameFormat& iNameFormat; + + private: // Friend declarations + friend IMPORT_C TBool operator== + (const CPbkContactItem& aLeft, const CPbkContactItem& aRight); + }; + + +// FUNCTION DECLARATIONS + +/** + * Returns ETrue if aLeft and aRight contents are the same. + */ +IMPORT_C TBool operator== + (const CPbkContactItem& aLeft, const CPbkContactItem& aRight); + +/** + * Returns ETrue if aLeft and aRight contents differ. + */ +inline TBool operator!= + (const CPbkContactItem& aLeft, const CPbkContactItem& aRight) + { + return !(aLeft==aRight); + } + + +#endif // __CPbkContactItem_H__ + +// End of File