--- /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 <e32base.h> // 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<TPbkContactItemField>
+ {
+ public:
+ enum
+ {
+ /// Default array reallocation granularity
+ KDefaultGranularity = 8
+ };
+
+ /**
+ * Constructor.
+ */
+ inline CPbkFieldArray()
+ : CArrayFixFlat<TPbkContactItemField>(KDefaultGranularity)
+ {
+ }
+
+ /**
+ * Constructor.
+ * @param aGranularity Reallocation granularity of this array.
+ */
+ inline CPbkFieldArray(TInt aGranurality)
+ : CArrayFixFlat<TPbkContactItemField>(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<br>
+ * field exists AND <br>
+ * field is nonempty AND <br>
+ * 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