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:  

    15 :                

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef SCVPBKSTORECONTACTFIELD_H

    22 #define SCVPBKSTORECONTACTFIELD_H

    23 

    24 

    25 // INCLUDES

    26 #include <e32base.h>

    27 #include <MVPbkStoreContactField.h>

    28 #include <MVPbkFieldType.h>

    29 

    30 // CONSTANTS

    31 

    32 

    33 // CLASS DECLARATIONS

    34 

    35 /**

    36  * An interface for the field of the store contact.

    37  *

    38  * Client can access the contact field using this interface. The field

    39  * can have a label and a data.

    40  *

    41  * A new field can be created using the MVPbkStoreContact interface.

    42  * For looping the contact fields see MVPbkStoreContactFieldCollection.

    43  * The parent of the field in the object hierarchy is the store contact.

    44  *

    45  * @see CVPbkContactFieldTypeIterator

    46  * @see CVPbkFieldTypeSelector

    47  */

    48 class CVPbkStoreContactFieldStub : public CBase,

    49                                public MVPbkStoreContactField,

    50                                public MVPbkFieldType

    51     {

    52     public:  // ctor

    53     	CVPbkStoreContactFieldStub(TInt aIndex);

    54         /**

    55          * Destructor

    56          */

    57         ~CVPbkStoreContactFieldStub();

    58 

    59     public: // From MVPbkBaseContactField

    60         const MVPbkContactFieldData& FieldData() const ;

    61 

    62     public:  // New functions

    63         /**

    64          * Returns ETrue if the field supports label. 

    65          * 

    66          * Overwrites the global setting in MVPbkContactStoreProperties. 

    67          * This must be confirmed before using SetFieldLabelL or 

    68          * MaxLabelLength.

    69          * 

    70          * @return ETrue if the field supports label. Otherwise EFalse.

    71          */

    72         TBool SupportsLabel() const ;

    73         

    74         /**

    75          * Returns the label of the field or KNullDesC if there is no field 

    76          * label.

    77          *

    78          * @return The label of the field or KNullDesC

    79          */

    80         TPtrC FieldLabel() const ;

    81 

    82         /**

    83          * Sets this field's label.

    84          *

    85          * SupportsLabel must be true for using this.

    86          *

    87          * @param aText The label for the field.

    88          */

    89         void SetFieldLabelL( const TDesC& aText ) ;

    90         

    91         /**

    92          * Gets the maximum length of the label. 

    93          *

    94          * SupportsLabel must be true for using this.

    95          * 

    96          * @return The maximum length of the label or KVPbkUnlimitedLabelLength

    97          *         if the store has no limits. Zero should be returned in other

    98          *         cases though this shouldn't be called if labels are 

    99          *         not supported.

   100          */

   101         TInt MaxLabelLength() const ;

   102 

   103         /**

   104          * Returns the data storage (read-write) of the field. 

   105          *

   106          * The data type depends on the field and it's client's responsibility

   107          * to check the type before casting the type.

   108          *

   109          * @return The data storage of the field.

   110          * @see MVPbkContactFieldTextData::Cast

   111          * @see MVPbkContactFieldDateTimeData::Cast

   112          * @see MVPbkContactFieldBinaryData::Cast

   113          */

   114         MVPbkContactFieldData& FieldData() ;

   115 

   116         /**

   117          * Clones the field. 

   118          * 

   119          * Pushes the created copy to the cleanup stack.

   120          *

   121          * @return A copy of the field.

   122          * @see MVPbkStoreContactFieldCollection::FieldAt

   123          */

   124         MVPbkStoreContactField* CloneLC() const ;

   125         

   126         /**

   127          * Creates a link representing the contact and the field.

   128          *

   129          * The field can be later retrieved using the RetrieveField of

   130          * MVPbkStoreContactFieldCollection interface.

   131          *

   132          * NOTE: implementations of stores are possibly using an index

   133          *       of the field as an identifier so clients should prefer not

   134          *       to save field links permanently. E.g modifying the contact

   135          *       can invalidate the link in some store implementations.

   136          *       A field link is practical in use cases where the link is

   137          *       created and immediately given to another component.

   138          *

   139          * @return A link representing the contact and the field or NULL

   140          *         if the contact doesn't exist in the store. E.g a new

   141          *         contact that hasn't been committed has no unique

   142          *         identifier yet.

   143          *         NULL is not put into the CleanupStack.

   144          */

   145         MVPbkContactLink* CreateLinkLC() const ;

   146 

   147 

   148     public:  // Interface

   149         /**

   150          * Returns the parent contact where this field is from.

   151          *

   152          * @return The parent contact where this field is from.

   153          */

   154         MVPbkBaseContact& ParentContact() const ;

   155 

   156         /**

   157          * Returns this field's type or NULL if no mapping exists

   158          * between the native type and phonebook type.

   159          *

   160          * @param aMatchPriority    matching priority to use.

   161          * @return The field type or NULL

   162          * @postcond !FieldType(list) || list.ContainsSame(*FieldType(list))

   163          */

   164         const MVPbkFieldType* MatchFieldType(

   165                 TInt aMatchPriority) const ;

   166         

   167         /**

   168          * Returns the best matching type of the field or NULL 

   169          * if no mapping exists between the native type and 

   170          * phonebook type. This is the same as looping 

   171          * MatchFieldType from priority 0 and getting the first 

   172          * matched type.

   173          *

   174          * @return The field type or NULL

   175          * @postcond !FieldType(list) || list.ContainsSame(*FieldType(list))

   176          */

   177         const MVPbkFieldType* BestMatchingFieldType() const ;

   178 

   179         

   180 

   181         /**

   182          * Returns true if this field is the same as another field in the

   183          * contact instance. 

   184          * Doesn't work for fields from different contact instances.

   185          * Always use this method instead of direct pointer comparison.

   186          *

   187          * @param aOther another field inside the contact

   188          * @return ETrue if contact is same

   189          */

   190         TBool IsSame(const MVPbkBaseContactField& aOther) const ;

   191 

   192         

   193 public:  // New functions

   194         /**

   195          * Returns the parent object of this object. For the root of the 

   196          * hierarchy returns self.

   197          * @return The parent object.

   198          */

   199         MVPbkObjectHierarchy& ParentObject() const ;

   200         

   201 		/**

   202          * Returns the Versit properties mapped to this field type.

   203          *

   204          * @return Versit properties.

   205          */

   206         TArray<TVPbkFieldVersitProperty> VersitProperties() const ;

   207 

   208         /**

   209          * Returns the Versit parameters fields of this type should not have.

   210          *

   211          * @return Excluded parameters.

   212          */

   213         const TVPbkFieldTypeParameters& ExcludedParameters() const ;

   214 

   215         /**

   216          * Type name for field types not supported by the Versit 2.1 standard.

   217          *

   218          * @return A non-Versit type.

   219          */

   220         TVPbkNonVersitFieldType NonVersitType() const ;

   221 

   222         /**

   223          * Returns true if this field type is the same as aOtherType.

   224          *

   225          * @param aOtherType The type to compare.

   226          * @return ETrue if the field types are the same.

   227          */

   228         TBool IsSame(

   229                 const MVPbkFieldType& aOtherType ) const ;

   230 

   231         /**

   232          * Returns true if this field type matches a Versit property.

   233          *

   234          * @param aMatchProperty A versit property to match against.

   235          * @param aMatchPriority A matching priority. Priorities start

   236          *                       from zero which is the highest priority.

   237          *                       Priority is also a direct index to

   238          *                       VersitProperties() array.

   239          * @return ETrue if this field type matches aMatchProperty at

   240          *         aMatchPriority. Returns always false if 

   241          *         aMatchPriority >= VersitProperties().Count().

   242          */

   243         TBool Matches(

   244                 const TVPbkFieldVersitProperty& aMatchProperty,

   245                 TInt aMatchPriority ) const ;

   246 

   247         /**

   248          * Returns the field type resource id from VPbkEng.rsg

   249          * that be used to identify a type.

   250          *

   251          * @return A field type resource id.

   252          */

   253         TInt FieldTypeResId() const ;   

   254         

   255 	private:

   256 		TInt iIndex ;

   257         

   258     };

   259 

   260 #endif  // SCVPBKSTORECONTACTFIELD_H

   261         

   262 // End of file