1 /*

     2 * Copyright (c) 2008 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:  Interface class to access framework item data

    15  *

    16 */

    17 

    18 

    19 #ifndef MPIMITEMDATA_H

    20 #define MPIMITEMDATA_H

    21 

    22 // INTERNAL INCLUDES

    23 #include "tpimfielddata.h"

    24 

    25 // EXTERNAL INCLUDES

    26 #include <e32std.h>

    27 

    28 /**

    29  * This class representates one PIM item data type which

    30  * can be used through this interface. This interface had

    31  * to be represented due to the need for a raw access to

    32  * PIM item data. So, this interface is used by list adapters

    33  * to fill an item without doing extra checks for the data

    34  * (it must be expected that adapters now what data they are adding)

    35  *

    36  * @since S60 v3.1

    37  */

    38 NONSHARABLE_CLASS(MPIMItemData)

    39 {

    40 public:

    41 

    42     /**

    43      * Sets PIM field data with certain index

    44      *

    45      * This function is used to set all types of PIM

    46      * data. The TPIMFieldData class encapsulates all

    47      * possible data about one field so we don't need

    48      * separate functions for each PIM field type

    49      *

    50      * @param aFieldData Reference to data class which

    51      *        all needed information about the new value

    52      *

    53      * @par Leaving

    54      * @li KErrNotFound - The requested field has no value

    55      */

    56     virtual void SetValueL(const TPIMFieldData& aFieldData) = 0;

    57 

    58     /**

    59      * Adds new PIM field data to certain field

    60      *

    61      * This function is used to add all types of PIM

    62      * data. The TPIMFieldData class encapsulates all

    63      * possible data about one field so we don't need

    64      * separate functions for each PIM field type

    65      *

    66      * NOTE: The index value in the argument class is ignored

    67      *

    68      * @param aFieldData Reference to data class which

    69      *        all needed information about the new value

    70      *

    71      * @par Leaving:

    72      * The method leaves on error. Error codes are interpreted as follows:

    73      * @li \c KErrNotFound - There is not value for given \a aIndex.

    74      * @li Other - The value could not be removed cleanly. This probably

    75      *     means that the value array has gone corrupt.

    76      */

    77     virtual void AddValueL(const TPIMFieldData& aFieldData) = 0;

    78 

    79     /**

    80      * Fetches value from specific value index. The value is

    81      * capsulated inside TPIMFieldData class to ease an access

    82      * to different types of values within the PIM item

    83      *

    84      * @param aIndex Index of the value in this specific field

    85      * @return A class holding requested information

    86      *

    87      * @par Leaving:

    88      * The method leaves on error. Error codes are interpreted as follows:

    89      * @li \c KErrNotFound - There is not value for given \a aIndex.

    90      * @li Other - The value could not be removed cleanly. This probably

    91      *     means that the value array has gone corrupt.

    92      */

    93     virtual const TPIMFieldData ValueL(const TPIMField aField,

    94                                        const TInt aIndex) const = 0;

    95 

    96     /**

    97      * Removes a specific value of a specific field.

    98      *

    99      * @param aIndex Index of the value that is to be removed.

   100      *

   101      * @par Leaving:

   102      * The method leaves on error. Error codes are interpreted as follows:

   103      * @li \c KErrNotFound - There is not value for given \a aIndex.

   104      * @li Other - The value could not be removed cleanly. This probably

   105      *     means that the value array has gone corrupt.

   106      */

   107     virtual void RemoveValueL(const TPIMField aField, const TInt aIndex) = 0;

   108 

   109     /**

   110      * Counts the number of values in a specific field. The values

   111      * are counted as indexes within this field. If there is no requested

   112      * field, this function returns zero

   113      *

   114      * @param aField The field values of which are to be counted.

   115      * @return Number of values in field \a aField.

   116      *         Zero if there is no values

   117      */

   118     virtual TInt CountValues(const TPIMField aField) const = 0;

   119 

   120     /**

   121      * Returns an array of fields that currently have more than zero values

   122      * The array is left to the cleanup stack

   123      *

   124      * @return Array of fields. The ownership of the array is transferred

   125      *         to the caller

   126      */

   127     virtual CArrayFix<TPIMField>* FieldsLC() const = 0;

   128 

   129     /**

   130      * Adds new label to an existing field

   131      *

   132      * @param aField Field to which the label is added

   133      * @param aIndex Value index of the label

   134      * @param aArrayIndex Array index of the label

   135      * @param aLabel New label

   136      */

   137     virtual void SetLabelL(const TPIMField aField, const TInt aIndex,

   138                            const TInt aArrayIndex, const TDesC& aLabel) = 0;

   139 

   140     /**

   141      * Retrieves the label from the specific field with specific

   142      * field and array indexes.

   143      *

   144      * @param aField Field from which the label is retrieved

   145      * @param aIndex Index of the field's value

   146      * @param aArrayIndex Index of the array index if this is a string

   147      *        array field

   148      *

   149      * @return Label name

   150      */

   151     virtual const TPtrC LabelL(const TPIMField aField, const TInt aIndex,

   152                                const TInt aArrayIndex) const = 0;

   153 

   154     /**

   155      * Clears all fields from this item data.

   156      */

   157     virtual void Reset() = 0;

   158 

   159     /**

   160      * Sets new attributes for a specific field and value index

   161      *

   162      * @param aField Field for which the attributes are to be added

   163      * @param aIndex Index of the value in this specific field

   164      *

   165      * @par Leaving:

   166      * The method leaves on error. Error codes are interpreted as follows:

   167      * @li \c KErrNotFound - There is not value for given \a aIndex.

   168      * @li Other - The value could not be removed cleanly. This probably

   169      *     means that the value array has gone corrupt.

   170      */

   171     virtual void SetAttributesL(const TPIMField aField, const TInt aIndex,

   172                                 TPIMAttribute aAttributes) = 0;

   173 

   174     /**

   175      * Retrieves attributes from an index within a field

   176      *

   177      * @param aField Field from which the attributes are to fetched

   178      * @param aIndex Value index of the field

   179      * @return Attributes of this value index

   180      *

   181      * @par Leaving:

   182      * The method leaves on error. Error codes are interpreted as follows:

   183      * @li \c KErrNotFound - There is not value for given \a aIndex.

   184      * @li Other - The value could not be removed cleanly. This probably

   185      *     means that the value array has gone corrupt.

   186      */

   187     virtual TInt

   188     AttributesL(const TPIMField aField, const TInt aIndex) const = 0;

   189 

   190     /**

   191      * Sets internal attributes to an index within a field.

   192      * Internal attributes are not accessible from the Java-side

   193      * so this function provides only access to set internal

   194      * attributes

   195      *

   196      * @param aField Field from which the attributes are to fetched

   197      * @param aIndex Value index of the field

   198      * @param aInternalAttributes New internal attributes. Old ones

   199      *        will be overwriten

   200      *

   201      * @par Leaving:

   202      * The method leaves on error. Error codes are interpreted as follows:

   203      * @li \c KErrNotFound - There is not value for given \a aIndex.

   204      * @li Other - The value could not be removed cleanly. This probably

   205      *     means that the value array has gone corrupt.

   206      */

   207     virtual void SetInternalAttributesL(const TPIMField aField,

   208                                         const TInt aIndex, CArrayFix<TUid>* aInternalAttributes) = 0;

   209 

   210     /**

   211      * Retrieves internal attributes from an index within a field.

   212      * Internal attributes are not accessible from the Java-side

   213      * so this function provides only access to retrieve internal

   214      * attributes

   215      *

   216      * @param aField Field from which the attributes are to fetched

   217      * @param aIndex Value index of the field

   218      *

   219      * @return Internal attributes of this value index

   220      *

   221      * @par Leaving:

   222      * The method leaves on error. Error codes are interpreted as follows:

   223      * @li \c KErrNotFound - There is not value for given \a aIndex.

   224      * @li Other - The value could not be removed cleanly. This probably

   225      *     means that the value array has gone corrupt.

   226      */

   227     virtual const CArrayFix<TUid>& InternalAttributesL(const TPIMField aField,

   228             const TInt aIndex) const = 0;

   229 

   230     /**

   231      * FindCategory

   232      * Finds a category from the category list

   233      * If the requested category was not found, KErrNotFound is

   234      * returned

   235      *

   236      * @param aCategoryName Category name to find

   237      * @return If found, the index of the category and KErrNotFound

   238      *         if the category was not found

   239      */

   240     virtual TInt FindCategory(const TDesC& aCategoryName) const = 0;

   241 

   242     /**

   243      * AddNewCategoryL

   244      * Adds new category to the category list

   245      *

   246      * @param aCategoryName Category name which is to be added

   247      */

   248     virtual void AddNewCategoryL(const TDesC& aCategoryName) = 0;

   249 

   250     /**

   251      * RemoveCategory

   252      * Removes a category from the category list

   253      * Returns ETrue if the category was found and removed

   254      * and EFalse if there was no such category

   255      *

   256      * @param aCategoryName Category name which is to be removed

   257      * @return ETrue if the category was removed, EFalse if not

   258      */

   259     virtual TBool RemoveCategory(const TDesC& aCategoryName) = 0;

   260 

   261     /**

   262      * Categories

   263      * Returns a reference to the categories associeated

   264      * with this item data

   265      *

   266      * @return A reference to the list of categories

   267      */

   268     virtual const CDesCArray& Categories() const = 0;

   269 

   270 protected:

   271 

   272     // Prohibit destruction using this interface

   273     virtual ~MPIMItemData()

   274     {}

   275 }

   276 ;

   277 

   278 #endif // MPIMITEMDATA_H

   279 // End of file