epoc32/include/app/MVPbkStoreContact.h
branchSymbian3
changeset 4 837f303aceeb
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/epoc32/include/app/MVPbkStoreContact.h	Wed Mar 31 12:33:34 2010 +0100
     1.3 @@ -0,0 +1,256 @@
     1.4 +/*
     1.5 +* Copyright (c) 2004-2007 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:  An interface for store contacts.
    1.18 +*
    1.19 +*/
    1.20 +
    1.21 +
    1.22 +#ifndef MVPBKSTORECONTACT_H
    1.23 +#define MVPBKSTORECONTACT_H
    1.24 +
    1.25 +
    1.26 +// INCLUDES
    1.27 +#include <e32base.h>
    1.28 +#include <mvpbkbasecontact.h>
    1.29 +#include <mvpbkviewcontact.h>
    1.30 +
    1.31 +// Includes needed for covariant return types
    1.32 +#include <mvpbkstorecontactfieldcollection.h>
    1.33 +
    1.34 +// FORWARD DECLARATIONS
    1.35 +class MVPbkContactStore;
    1.36 +class MVPbkContactObserver;
    1.37 +class MVPbkStoreContactField;
    1.38 +class MVPbkFieldType;
    1.39 +class MVPbkContactLinkArray;
    1.40 +class MVPbkContactGroup;
    1.41 +class MVPbkStoreContactProperties;
    1.42 +
    1.43 +// CONSTANTS
    1.44 +const TInt KVPbkStoreContactUnlimitedNumber = -1;
    1.45 +
    1.46 +//Use this UID to access contact store extension 2.
    1.47 +// Used as a parameter to ContactStoreExtension() method.
    1.48 +const TUid KMVPbkStoreContactExtension2Uid = { 2 };
    1.49 +// CLASS DECLARATIONS
    1.50 +
    1.51 +/**
    1.52 + * An interface for store contacts.
    1.53 + *
    1.54 + * A store contact is a contact that includes all the fields of
    1.55 + * the contact. For this reason it usually contains more data compared
    1.56 + * to the corresponding view contact. It can contain all types of fields that
    1.57 + * are supported by the its parent store.
    1.58 + *
    1.59 + * The store contact can be edited if it's not read-only. The client must
    1.60 + * first lock the existing contact then edit it and finally commit the changes.
    1.61 + *
    1.62 + * @see MVPbkContactStore
    1.63 + * @see MVPbkViewContact
    1.64 + */
    1.65 +class MVPbkStoreContact : public MVPbkBaseContact,
    1.66 +                          public MVPbkObjectHierarchy
    1.67 +    {
    1.68 +    public:  // Destructor
    1.69 +        virtual ~MVPbkStoreContact() { }
    1.70 +
    1.71 +    public: // From MVPbkBaseContact (covariant return types)
    1.72 +        const MVPbkStoreContactFieldCollection& Fields() const =0;
    1.73 +
    1.74 +    public:  // New functions
    1.75 +        /**
    1.76 +         * Pushes an item on the cleanup stack.
    1.77 +         *
    1.78 +         * Clients must use either this function or CleanupDeletePushL 
    1.79 +         * from e32base.h.
    1.80 +         *
    1.81 +         * CleanupStack::PushL(TAny*) must not be used because the virtual
    1.82 +         * destructor of M-class won't be called.
    1.83 +         * This function should be used to make sure that the virtual destructor
    1.84 +         * of this object is called when popped and destroyed from the cleanup
    1.85 +         * stack.
    1.86 +         */
    1.87 +        inline void PushL();
    1.88 +
    1.89 +        /**
    1.90 +         * Returns this contact's parent store.
    1.91 +         *
    1.92 +         * @return The parent store of the contact.
    1.93 +         */
    1.94 +        virtual MVPbkContactStore& ParentStore() const =0;
    1.95 +
    1.96 +        /**
    1.97 +         * Returns this contact's fields (read-write).
    1.98 +         *
    1.99 +         * @return A collection of contact fields.
   1.100 +         */
   1.101 +        virtual MVPbkStoreContactFieldCollection& Fields() =0;
   1.102 +
   1.103 +        /**
   1.104 +         * Creates a new field for this contact.
   1.105 +         *
   1.106 +         * The new field must be added to the contact using AddFieldL.
   1.107 +         *
   1.108 +         * @param aFieldType  A type of the field to create. Must be found in
   1.109 +         *                    ParentStore().SupportedFieldTypes().
   1.110 +         * @return A new field object. The returned object is left on the
   1.111 +         *         cleanup stack.
   1.112 +         * @exception KErrNotSupported if the field type is not supported.
   1.113 +         * @exception KErrAccessDenied if the contact can not be modified.
   1.114 +         */
   1.115 +        virtual MVPbkStoreContactField* CreateFieldLC(
   1.116 +                const MVPbkFieldType& aFieldType) const =0;
   1.117 +
   1.118 +        /**
   1.119 +         * Adds a new field to the contact.
   1.120 +         * 
   1.121 +         * The field must be previously created with CreateFieldLC and
   1.122 +         * it must NOT be used after adding.
   1.123 +         *
   1.124 +         * If the client needs the field after adding it must be retrieved
   1.125 +         * using Fields().
   1.126 +         *
   1.127 +         * @param aField A new field that was created using CreateFieldLC.
   1.128 +         *               This object takes ownership of the field.
   1.129 +         * @precond aField must not be NULL or 
   1.130 +         *          VPbkError::Panic(VPbkError::ENullContactField) is raised.
   1.131 +         * @precond aField must be returned from this->CreateFieldLC or
   1.132 +         *          VPbkError::Panic(VPbkError::EInvalidContactField) panic is raised.
   1.133 +         * @postcond this->Fields().FieldCount() == 
   1.134 +         *           old(this->Fields().FieldCount()) + 1
   1.135 +         * @return The index of the new field in the field collection.
   1.136 +         * @exception KErrAccessDenied if the contact can not be modified.
   1.137 +         */
   1.138 +        virtual TInt AddFieldL(MVPbkStoreContactField* aField) =0;
   1.139 +
   1.140 +        /**
   1.141 +         * Removes a field from the contact.
   1.142 +         *
   1.143 +         * @param aIndex A zero-based index of the field to remove.
   1.144 +         * @precond aIndex >= 0 && aIndex < FieldCount().
   1.145 +         *          Panics with VPbkError::EInvalidFieldIndex.
   1.146 +         * @precond The contact is not read-only otherwise panics with 
   1.147 +         *          VPbkError::EInvalidAccessToReadOnlyContact.
   1.148 +         * @postcond this->Fields().FieldCount() == 
   1.149 +         *           old(this->Fields().FieldCount()) - 1
   1.150 +         */
   1.151 +        virtual void RemoveField(TInt aIndex) =0;
   1.152 +
   1.153 +        /**
   1.154 +         * Removes all the fields from the contact.
   1.155 +         *
   1.156 +         * @precond The contact is not read-only otherwise panics with 
   1.157 +         *          VPbkError::EInvalidAccessToReadOnlyContact.
   1.158 +         * @postcond this->Fields().FieldCount() == 0
   1.159 +         */
   1.160 +        virtual void RemoveAllFields() =0;
   1.161 +
   1.162 +        /**
   1.163 +         * Locks this contact for modification asynchronously.
   1.164 +         *
   1.165 +         * Once the observer is notified this contact is locked and cab
   1.166 +         * be modified.
   1.167 +         *
   1.168 +         * @param aObserver The observer to call back when the operation
   1.169 +         *                  completes. The observer will not be called if this
   1.170 +         *                  function leaves.
   1.171 +         * @exception KErrInUse If another asynchronous operation is 
   1.172 +         *            already in progress.
   1.173 +         * @exception KErrAccessDenied if the contact can not be modified.
   1.174 +         */
   1.175 +        virtual void LockL(MVPbkContactObserver& aObserver) const =0;
   1.176 +
   1.177 +        /**
   1.178 +         * Saves the contact to its associated store asynchronously.
   1.179 +         *
   1.180 +         * LockL must have been called before commit if this is
   1.181 +         * an existing contact. Otherwise ContactOperationFailed is called
   1.182 +         * with KErrAccessDenied.
   1.183 +         *
   1.184 +         * @param aObserver The observer to call back when this operation
   1.185 +         *                  completes. The observer will not be called if this
   1.186 +         *                  function leaves.
   1.187 +         * @exception KErrInUse If another asynchronous operation is already
   1.188 +         *            in progress.
   1.189 +         * @exception KErrAccessDenied if the contact can not be modified.
   1.190 +         */
   1.191 +        virtual void CommitL(MVPbkContactObserver& aObserver) const =0;
   1.192 +
   1.193 +        /**
   1.194 +         * Returns the identifiers of the groups that the contact 
   1.195 +         * belongs to.
   1.196 +         *
   1.197 +         * @return The groups that this contact belongs to.
   1.198 +         */
   1.199 +        virtual MVPbkContactLinkArray* GroupsJoinedLC() const =0;
   1.200 +
   1.201 +        /**
   1.202 +         * Returns the group interface of the store contact if this contact
   1.203 +         * is a group.
   1.204 +         * If this contact is not a group, NULL is returned.
   1.205 +         *
   1.206 +         * @return The group interface or NULL.
   1.207 +         */
   1.208 +        virtual MVPbkContactGroup* Group() =0;
   1.209 +        
   1.210 +        /**
   1.211 +         * Returns the maximum amount of fields of given type that can be
   1.212 +         * inserted to the contact.
   1.213 +         *
   1.214 +         * E.g. A USIM ADN contact can have 1 or more phone numbers but there
   1.215 +         * is a limit that the store in USIM defines.
   1.216 +         * On the other hand the contact in the Contacts Model data base
   1.217 +         * doesn't have limits.
   1.218 +         *
   1.219 +         * @param aType The field type of the field
   1.220 +         * @return The maximum amount fields of given type in the contact
   1.221 +         *         or KVPbkStoreContactUnlimitedNumber it there is no limit
   1.222 +         *         set by the store contact
   1.223 +         */
   1.224 +        virtual TInt MaxNumberOfFieldL(const MVPbkFieldType& aType) const =0;
   1.225 +
   1.226 +        
   1.227 +        /**
   1.228 +         * Returns an extension point for this interface or NULL.
   1.229 +         *
   1.230 +         * @param aExtensionUid no extensions defined currently.
   1.231 +         * @return An extension point for this interface or NULL.
   1.232 +         */
   1.233 +        virtual TAny* StoreContactExtension(TUid /*aExtensionUid*/) 
   1.234 +                { return NULL; }
   1.235 +
   1.236 +    public:  // from MVPbkBaseContact
   1.237 +        /// Do not override
   1.238 +        virtual TBool IsSame(const MVPbkBaseContact& aOtherContact) const
   1.239 +            {
   1.240 +            return aOtherContact.IsSame(*this);
   1.241 +            }
   1.242 +
   1.243 +        // Do not override
   1.244 +        virtual TBool IsSame(const MVPbkViewContact& aOtherContact) const
   1.245 +            {
   1.246 +            return aOtherContact.IsSame(*this, &ContactStore());
   1.247 +            }
   1.248 +    };
   1.249 +
   1.250 +
   1.251 +// INLINE FUNCTIONS
   1.252 +inline void MVPbkStoreContact::PushL()
   1.253 +    {
   1.254 +    CleanupDeletePushL(this);
   1.255 +    }
   1.256 +
   1.257 +#endif  // MVPBKSTORECONTACT_H
   1.258 +
   1.259 +//End of file