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:  Class for holding PIM item data

    15  *

    16 */

    17 

    18 

    19 #ifndef CPIMITEMDATA_H

    20 #define CPIMITEMDATA_H

    21 

    22 // INTERNAL INCLUDES

    23 #include "mpimitemdata.h"

    24 

    25 // EXTERNAL INCLUDES

    26 #include <e32std.h>

    27 

    28 // FORWARD DECLARATIONS

    29 class CPIMField;

    30 class TPIMFieldData;

    31 

    32 /**

    33  *  This class representates one PIM item data. This is the actual

    34  *  storage class of the data values of one PIM fields. MPIMItemData

    35  *  is an interface which provides access to this class

    36  *

    37  *  @since S60 v3.1

    38  */

    39 NONSHARABLE_CLASS(CPIMItemData) : public CBase,

    40         public MPIMItemData

    41 {

    42 public:

    43 

    44     /**

    45      * Two-phased constructor.

    46      *

    47      * @return New instance of this class.

    48      */

    49     static CPIMItemData* NewL();

    50 

    51     /**

    52      * Two-phased constructor.

    53      *

    54      * @return New instance of this class. The instance

    55      *         is pushed to the cleanup stack

    56      */

    57     static CPIMItemData* NewLC();

    58 

    59     /**

    60      * Destructor

    61      */

    62     virtual ~CPIMItemData();

    63 

    64 public: // Methods from MPIMItemData

    65 

    66     /**

    67      * Sets PIM field data with certain index

    68      *

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

    70      * data. The TPIMFieldData class encapsulates all

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

    72      * separate functions for each PIM field type

    73      *

    74      * @param aFieldData Reference to data class which

    75      *        all needed information about the new value

    76      *

    77      * @par Leaving

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

    79      */

    80     void SetValueL(const TPIMFieldData& aFieldData);

    81 

    82     /**

    83      * Adds new PIM field data to certain field

    84      *

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

    86      * data. The TPIMFieldData class encapsulates all

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

    88      * separate functions for each PIM field type

    89      *

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

    91      *

    92      * @param aFieldData Reference to data class which

    93      *        all needed information about the new value

    94      *

    95      * @par Leaving:

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

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

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

    99      *     means that the value array has gone corrupt.

   100      */

   101     void AddValueL(const TPIMFieldData& aFieldData);

   102 

   103     /**

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

   105      * capsulated inside TPIMFieldData class to ease an access

   106      * to different types of values within the PIM item

   107      *

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

   109      * @return A class holding requested information

   110      *

   111      * @par Leaving:

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

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

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

   115      *     means that the value array has gone corrupt.

   116      */

   117     const TPIMFieldData ValueL(const TPIMField aField,

   118                                const TInt aIndex) const;

   119 

   120     /**

   121      * Removes a specific value of a specific field.

   122      *

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

   124      *

   125      * @par Leaving:

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

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

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

   129      *     means that the value array has gone corrupt.

   130      */

   131     void RemoveValueL(const TPIMField aField,

   132                       const TInt aIndex);

   133 

   134     /**

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

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

   137      * field, this function returns zero

   138      *

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

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

   141      *         Zero if there is no values

   142      */

   143     TInt CountValues(const TPIMField aField) const;

   144 

   145     /**

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

   147      * The array is left to the cleanup stack

   148      *

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

   150      *         to the caller

   151      */

   152     CArrayFix< TPIMField>* FieldsLC() const;

   153 

   154     /**

   155      * Adds new label to an existing field

   156      *

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

   158      * @param aIndex Value index of the label

   159      * @param aArrayIndex Array index of the label

   160      * @param aLabel New label

   161      */

   162     void SetLabelL(

   163         const TPIMField aField,

   164         const TInt aIndex,

   165         const TInt aArrayIndex,

   166         const TDesC& aLabel);

   167 

   168     /**

   169      * Retrieves the label from the specific field with specific

   170      * field and array indexes.

   171      *

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

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

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

   175      *        array field

   176      *

   177      * @return Label name

   178      */

   179     const TPtrC LabelL(

   180         const TPIMField aField,

   181         const TInt aIndex,

   182         const TInt aArrayIndex) const;

   183 

   184     /**

   185      * Clears all fields from this item data.

   186      */

   187     void Reset();

   188 

   189     /**

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

   191      *

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

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

   194      *

   195      * @par Leaving:

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

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

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

   199      *     means that the value array has gone corrupt.

   200      */

   201     void SetAttributesL(

   202         const TPIMField aField,

   203         const TInt aIndex,

   204         TPIMAttribute aAttributes);

   205 

   206     /**

   207      * Retrieves attributes from an index within a field

   208      *

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

   210      * @param aIndex Value index of the field

   211      * @return Attributes of this value index

   212      *

   213      * @par Leaving:

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

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

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

   217      *     means that the value array has gone corrupt.

   218      */

   219     TInt AttributesL(

   220         const TPIMField aField,

   221         const TInt aIndex) const;

   222 

   223     /**

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

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

   226      * so this function provides only access to set internal

   227      * attributes

   228      *

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

   230      * @param aIndex Value index of the field

   231      * @param aInternalAttributes New internal attributes. Old ones

   232      *        will be overwriten

   233      *

   234      * @par Leaving:

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

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

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

   238      *     means that the value array has gone corrupt.

   239      */

   240     void SetInternalAttributesL(

   241         const TPIMField aField,

   242         const TInt aIndex,

   243         CArrayFix< TUid>* aInternalAttributes);

   244 

   245     /**

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

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

   248      * so this function provides only access to retrieve internal

   249      * attributes

   250      *

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

   252      * @param aIndex Value index of the field

   253      *

   254      * @return Internal attributes of this value index

   255      *

   256      * @par Leaving:

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

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

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

   260      *     means that the value array has gone corrupt.

   261      */

   262     const CArrayFix< TUid>& InternalAttributesL(

   263         const TPIMField aField,

   264         const TInt aIndex) const;

   265 

   266     /**

   267      * FindCategory

   268      * Finds a category from the category list

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

   270      * returned

   271      *

   272      * @param aCategoryName Category name to find

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

   274      *         if the category was not found

   275      */

   276     TInt FindCategory(const TDesC& aCategoryName) const;

   277 

   278     /**

   279      * AddNewCategoryL

   280      * Adds new category to the category list

   281      *

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

   283      */

   284     void AddNewCategoryL(const TDesC& aCategoryName);

   285 

   286     /**

   287      * RemoveCategory

   288      * Removes a category from the category list

   289      * Returns ETrue if the category was found and removed

   290      * and EFalse if there was no such category

   291      *

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

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

   294      */

   295     TBool RemoveCategory(const TDesC& aCategoryName);

   296 

   297     /**

   298      * Categories

   299      * Returns a reference to the categories associeated

   300      * with this item data

   301      *

   302      * @return A reference to the list of categories

   303      */

   304     const CDesCArray& Categories() const;

   305 

   306 public: // New functions

   307 

   308     /**

   309      * Check if this item data contains requested field

   310      * @param aField Field which is to be checked

   311      * @return ETrue if the field is present, EFalse if not

   312      */

   313     TBool HasField(const TPIMField aField) const;

   314 

   315 private:

   316 

   317     /**

   318      * C++ default constructor

   319      */

   320     inline CPIMItemData();

   321 

   322     /**

   323      * Seconds phase constructor

   324      */

   325     inline void ConstructL();

   326 

   327 private: // New functions

   328 

   329     /**

   330      * Finds index of the requested field if it is in the

   331      * field array

   332      *

   333      * @param aField requested field

   334      *

   335      * @return Index of the field. If not found, KErrNotFound

   336      *         is returned

   337      */

   338     TInt FieldIndex(const TPIMField aField) const;

   339 

   340 private: // Data

   341 

   342     /** PIM field array */

   343     RPointerArray< CPIMField> iFields;

   344 

   345     /** Categories associated with this item data. Owned */

   346     CDesCArray* iCategories;

   347 

   348 };

   349 

   350 #endif // CPIMITEMDATA_H

   351 // End of file