1 /*

     2 * Copyright (c) 2004-2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  An interface for store contacts.

    15 *

    16 */

    17 

    18 

    19 #ifndef MVPBKSTORECONTACT_H

    20 #define MVPBKSTORECONTACT_H

    21 

    22 

    23 // INCLUDES

    24 #include <e32base.h>

    25 #include <MVPbkBaseContact.h>

    26 #include <MVPbkViewContact.h>

    27 

    28 // Includes needed for covariant return types

    29 #include <MVPbkStoreContactFieldCollection.h>

    30 

    31 // FORWARD DECLARATIONS

    32 class MVPbkContactStore;

    33 class MVPbkContactObserver;

    34 class MVPbkStoreContactField;

    35 class MVPbkFieldType;

    36 class MVPbkContactLinkArray;

    37 class MVPbkContactGroup;

    38 class MVPbkStoreContactProperties;

    39 

    40 // CONSTANTS

    41 const TInt KVPbkStoreContactUnlimitedNumber = -1;

    42 

    43 //Use this UID to access contact store extension 2.

    44 // Used as a parameter to ContactStoreExtension() method.

    45 const TUid KMVPbkStoreContactExtension2Uid = { 2 };

    46 // CLASS DECLARATIONS

    47 

    48 /**

    49  * An interface for store contacts.

    50  *

    51  * A store contact is a contact that includes all the fields of

    52  * the contact. For this reason it usually contains more data compared

    53  * to the corresponding view contact. It can contain all types of fields that

    54  * are supported by the its parent store.

    55  *

    56  * The store contact can be edited if it's not read-only. The client must

    57  * first lock the existing contact then edit it and finally commit the changes.

    58  *

    59  * @see MVPbkContactStore

    60  * @see MVPbkViewContact

    61  */

    62 class MVPbkStoreContact : public MVPbkBaseContact,

    63                           public MVPbkObjectHierarchy

    64     {

    65     public:  // Destructor

    66         virtual ~MVPbkStoreContact() { }

    67 

    68     public: // From MVPbkBaseContact (covariant return types)

    69         const MVPbkStoreContactFieldCollection& Fields() const =0;

    70 

    71     public:  // New functions

    72         /**

    73          * Pushes an item on the cleanup stack.

    74          *

    75          * Clients must use either this function or CleanupDeletePushL 

    76          * from e32base.h.

    77          *

    78          * CleanupStack::PushL(TAny*) must not be used because the virtual

    79          * destructor of M-class won't be called.

    80          * This function should be used to make sure that the virtual destructor

    81          * of this object is called when popped and destroyed from the cleanup

    82          * stack.

    83          */

    84         inline void PushL();

    85 

    86         /**

    87          * Returns this contact's parent store.

    88          *

    89          * @return The parent store of the contact.

    90          */

    91         virtual MVPbkContactStore& ParentStore() const =0;

    92 

    93         /**

    94          * Returns this contact's fields (read-write).

    95          *

    96          * @return A collection of contact fields.

    97          */

    98         virtual MVPbkStoreContactFieldCollection& Fields() =0;

    99 

   100         /**

   101          * Creates a new field for this contact.

   102          *

   103          * The new field must be added to the contact using AddFieldL.

   104          *

   105          * @param aFieldType  A type of the field to create. Must be found in

   106          *                    ParentStore().SupportedFieldTypes().

   107          * @return A new field object. The returned object is left on the

   108          *         cleanup stack.

   109          * @exception KErrNotSupported if the field type is not supported.

   110          * @exception KErrAccessDenied if the contact can not be modified.

   111          */

   112         virtual MVPbkStoreContactField* CreateFieldLC(

   113                 const MVPbkFieldType& aFieldType) const =0;

   114 

   115         /**

   116          * Adds a new field to the contact.

   117          * 

   118          * The field must be previously created with CreateFieldLC and

   119          * it must NOT be used after adding.

   120          *

   121          * If the client needs the field after adding it must be retrieved

   122          * using Fields().

   123          *

   124          * @param aField A new field that was created using CreateFieldLC.

   125          *               This object takes ownership of the field.

   126          * @precond aField must not be NULL or 

   127          *          VPbkError::Panic(VPbkError::ENullContactField) is raised.

   128          * @precond aField must be returned from this->CreateFieldLC or

   129          *          VPbkError::Panic(VPbkError::EInvalidContactField) panic is raised.

   130          * @postcond this->Fields().FieldCount() == 

   131          *           old(this->Fields().FieldCount()) + 1

   132          * @return The index of the new field in the field collection.

   133          * @exception KErrAccessDenied if the contact can not be modified.

   134          */

   135         virtual TInt AddFieldL(MVPbkStoreContactField* aField) =0;

   136 

   137         /**

   138          * Removes a field from the contact.

   139          *

   140          * @param aIndex A zero-based index of the field to remove.

   141          * @precond aIndex >= 0 && aIndex < FieldCount().

   142          *          Panics with VPbkError::EInvalidFieldIndex.

   143          * @precond The contact is not read-only otherwise panics with 

   144          *          VPbkError::EInvalidAccessToReadOnlyContact.

   145          * @postcond this->Fields().FieldCount() == 

   146          *           old(this->Fields().FieldCount()) - 1

   147          */

   148         virtual void RemoveField(TInt aIndex) =0;

   149 

   150         /**

   151          * Removes all the fields from the contact.

   152          *

   153          * @precond The contact is not read-only otherwise panics with 

   154          *          VPbkError::EInvalidAccessToReadOnlyContact.

   155          * @postcond this->Fields().FieldCount() == 0

   156          */

   157         virtual void RemoveAllFields() =0;

   158 

   159         /**

   160          * Locks this contact for modification asynchronously.

   161          *

   162          * Once the observer is notified this contact is locked and cab

   163          * be modified.

   164          *

   165          * @param aObserver The observer to call back when the operation

   166          *                  completes. The observer will not be called if this

   167          *                  function leaves.

   168          * @exception KErrInUse If another asynchronous operation is 

   169          *            already in progress.

   170          * @exception KErrAccessDenied if the contact can not be modified.

   171          */

   172         virtual void LockL(MVPbkContactObserver& aObserver) const =0;

   173 

   174         /**

   175          * Saves the contact to its associated store asynchronously.

   176          *

   177          * LockL must have been called before commit if this is

   178          * an existing contact. Otherwise ContactOperationFailed is called

   179          * with KErrAccessDenied.

   180          *

   181          * @param aObserver The observer to call back when this operation

   182          *                  completes. The observer will not be called if this

   183          *                  function leaves.

   184          * @exception KErrInUse If another asynchronous operation is already

   185          *            in progress.

   186          * @exception KErrAccessDenied if the contact can not be modified.

   187          */

   188         virtual void CommitL(MVPbkContactObserver& aObserver) const =0;

   189 

   190         /**

   191          * Returns the identifiers of the groups that the contact 

   192          * belongs to.

   193          *

   194          * @return The groups that this contact belongs to.

   195          */

   196         virtual MVPbkContactLinkArray* GroupsJoinedLC() const =0;

   197 

   198         /**

   199          * Returns the group interface of the store contact if this contact

   200          * is a group.

   201          * If this contact is not a group, NULL is returned.

   202          *

   203          * @return The group interface or NULL.

   204          */

   205         virtual MVPbkContactGroup* Group() =0;

   206         

   207         /**

   208          * Returns the maximum amount of fields of given type that can be

   209          * inserted to the contact.

   210          *

   211          * E.g. A USIM ADN contact can have 1 or more phone numbers but there

   212          * is a limit that the store in USIM defines.

   213          * On the other hand the contact in the Contacts Model data base

   214          * doesn't have limits.

   215          *

   216          * @param aType The field type of the field

   217          * @return The maximum amount fields of given type in the contact

   218          *         or KVPbkStoreContactUnlimitedNumber it there is no limit

   219          *         set by the store contact

   220          */

   221         virtual TInt MaxNumberOfFieldL(const MVPbkFieldType& aType) const =0;

   222 

   223         

   224         /**

   225          * Returns an extension point for this interface or NULL.

   226          *

   227          * @param aExtensionUid no extensions defined currently.

   228          * @return An extension point for this interface or NULL.

   229          */

   230         virtual TAny* StoreContactExtension(TUid /*aExtensionUid*/) 

   231                 { return NULL; }

   232 

   233     public:  // from MVPbkBaseContact

   234         /// Do not override

   235         virtual TBool IsSame(const MVPbkBaseContact& aOtherContact) const

   236             {

   237             return aOtherContact.IsSame(*this);

   238             }

   239 

   240         // Do not override

   241         virtual TBool IsSame(const MVPbkViewContact& aOtherContact) const

   242             {

   243             return aOtherContact.IsSame(*this, &ContactStore());

   244             }

   245     };

   246 

   247 

   248 // INLINE FUNCTIONS

   249 inline void MVPbkStoreContact::PushL()

   250     {

   251     CleanupDeletePushL(this);

   252     }

   253 

   254 #endif  // MVPBKSTORECONTACT_H

   255 

   256 //End of file