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 the field of the store contact

    15 *

    16 */

    17 

    18 #ifndef MVPBKSTORECONTACTFIELD_H

    19 #define MVPBKSTORECONTACTFIELD_H

    20 

    21 // INCLUDES

    22 #include <e32std.h>

    23 #include <mvpbkbasecontactfield.h>

    24 

    25 // CONSTANTS

    26 /// A constant that indicates that the store doesn't set limits

    27 /// to the length of the label

    28 const TInt KVPbkUnlimitedLabelLength = -1;

    29 

    30 // FORWARD DECLARATIONS

    31 class MVPbkContactLink;

    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 MVPbkStoreContactField : public MVPbkBaseContactField,

    49                                public MVPbkObjectHierarchy

    50     {

    51     public:  // Destructor

    52         /**

    53          * Destructor

    54          */

    55         virtual ~MVPbkStoreContactField() { }

    56 

    57     public: // From MVPbkBaseContactField

    58         virtual const MVPbkContactFieldData& FieldData() const = 0;

    59 

    60     public:  // New functions

    61         /**

    62          * Returns ETrue if the field supports label.

    63          *

    64          * Overwrites the global setting in MVPbkContactStoreProperties.

    65          * This must be confirmed before using SetFieldLabelL or

    66          * MaxLabelLength.

    67          *

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

    69          */

    70         virtual TBool SupportsLabel() const = 0;

    71 

    72         /**

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

    74          * label.

    75          *

    76          * @return The label of the field or KNullDesC

    77          */

    78         virtual TPtrC FieldLabel() const = 0;

    79 

    80         /**

    81          * Sets this field's label.

    82          *

    83          * SupportsLabel must be true for using this.

    84          *

    85          * @param aText The label for the field.

    86          */

    87         virtual void SetFieldLabelL( const TDesC& aText ) = 0;

    88 

    89         /**

    90          * Gets the maximum length of the label.

    91          *

    92          * SupportsLabel must be true for using this.

    93          *

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

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

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

    97          *         not supported.

    98          */

    99         virtual TInt MaxLabelLength() const = 0;

   100 

   101         /**

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

   103          *

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

   105          * to check the type before casting the type.

   106          *

   107          * @return The data storage of the field.

   108          * @see MVPbkContactFieldTextData::Cast

   109          * @see MVPbkContactFieldDateTimeData::Cast

   110          * @see MVPbkContactFieldBinaryData::Cast

   111          */

   112         virtual MVPbkContactFieldData& FieldData() = 0;

   113 

   114         /**

   115          * Clones the field.

   116          *

   117          * Pushes the created copy to the cleanup stack.

   118          *

   119          * @return A copy of the field.

   120          * @see MVPbkStoreContactFieldCollection::FieldAt

   121          */

   122         virtual MVPbkStoreContactField* CloneLC() const = 0;

   123 

   124         /**

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

   126          *

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

   128          * MVPbkStoreContactFieldCollection interface.

   129          *

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

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

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

   133          *       can invalidate the link in some store implementations.

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

   135          *       created and immediately given to another component.

   136          *

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

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

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

   140          *         identifier yet.

   141          *         NULL is not put into the CleanupStack.

   142          */

   143         virtual MVPbkContactLink* CreateLinkLC() const = 0;

   144 

   145         /**

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

   147          *

   148          * @param aExtensionUid no extensions defined currently.

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

   150          */

   151         virtual TAny* StoreContactFieldExtension( TUid /*aExtensionUid*/ )

   152             { return NULL; }

   153     };

   154 

   155 

   156 #endif  // MVPBKSTORECONTACTFIELD_H

   157 

   158 // End of file