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 field data

    15  *

    16 */

    17 

    18 

    19 #ifndef CPIMFIELD_H

    20 #define CPIMFIELD_H

    21 

    22 // INTERNAL INCLUDES

    23 #include "tpimfielddata.h"

    24 

    25 // EXTERNAL INCLUDES

    26 #include <e32std.h>

    27 

    28 // FORWARD DECLARATIONS

    29 class CPIMValueBase;

    30 

    31 /**

    32  * Class for holding PIM field data. This class

    33  * stores value indexes to an array.

    34  * @since S60 v3.1

    35  */

    36 NONSHARABLE_CLASS(CPIMField) : public CBase

    37 {

    38 public:

    39 

    40     /**

    41      * Two-phased constructor.

    42      *

    43      * @return New instance of this class.

    44      */

    45     static CPIMField* NewL(const TPIMFieldData& aFieldData);

    46 

    47     /**

    48      * Two-phased constructor.

    49      *

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

    51      *         is pushed to the cleanup stack

    52      */

    53     static CPIMField* NewLC(const TPIMFieldData& aFieldData);

    54 

    55     /**

    56      * Destructor

    57      */

    58     virtual ~CPIMField();

    59 

    60 public: // New methods

    61 

    62     /**

    63      * Sets PIM field data with certain index

    64      *

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

    66      * data. The TPIMFieldData class encapsulates all

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

    68      * separate functions for each PIM field type

    69      *

    70      * @param aFieldData Reference to data class which

    71      *        all needed information about the new value

    72      *

    73      * @par Leaving:

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

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

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

    77      *     means that the value array has gone corrupt or OOM situation

    78      *     has occured

    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 or OOM situation

   100      *     has occured

   101      */

   102     void AddValueL(const TPIMFieldData& aFieldData);

   103 

   104     /**

   105      * Fetches value from specific value index.

   106      *

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

   108      * @return A class holding requested information

   109      *

   110      * @par Leaving:

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

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

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

   114      *     means that the value array has gone corrupt or OOM situation

   115      *     has occured

   116      */

   117     const TPIMFieldData ValueL(const TInt aIndex) const;

   118 

   119     /**

   120      * Removes a specific value of a specific field.

   121      *

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

   123      *

   124      * @par Leaving:

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

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

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

   128      *     means that the value array has gone corrupt or OOM situation

   129      *     has occured

   130      */

   131     void RemoveValueL(const TInt aIndex);

   132 

   133     /**

   134      * Count values currently in this PIM field

   135      *

   136      * @return Number of values in this field

   137      */

   138     TInt CountValues() const;

   139 

   140     /**

   141      * Adds new label to an existing field

   142      *

   143      * @param aIndex Value index of the label

   144      * @param aArrayIndex Array index of the label

   145      * @param aLabel New label

   146      *

   147      * @par Leaving:

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

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

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

   151      *     means that the value array has gone corrupt or OOM situation

   152      *     has occured

   153      */

   154     void SetLabelL(

   155         const TInt aIndex,

   156         const TInt aArrayIndex,

   157         const TDesC& aLabel);

   158 

   159     /**

   160      * Retrieves the label from the specific field with specific

   161      * field and array indexes.

   162      *

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

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

   165      *        array field

   166      *

   167      * @return Label name. NULL if there is no label for this array

   168      *         index or the labels have not been allocated yet

   169      */

   170     const TPtrC Label(

   171         const TInt aIndex,

   172         const TInt aArrayIndex) const;

   173 

   174     /**

   175      * DataType

   176      * Returns the data type of this PIM field

   177      *

   178      * @return Data type of this field

   179      */

   180     TPIMFieldDataType DataType() const;

   181 

   182     /**

   183      * FieldType

   184      * Returns the type of this field

   185      *

   186      * @return The type of this field

   187      */

   188     TPIMField FieldType() const;

   189 

   190     /**

   191      * SetAttributesL

   192      * Sets new attributes for a specific value

   193      *

   194      * @param aIndex Index of the value

   195      * @param aAttributes New attributes

   196      *

   197      * @par Leaving:

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

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

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

   201      *     means that the value array has gone corrupt or OOM situation

   202      *     has occured

   203      */

   204     void SetAttributesL(const TInt aIndex, TPIMAttribute aAttributes);

   205 

   206     /**

   207      * AttributesL

   208      * Returns attributes from the specific value

   209      *

   210      * @param aIndex Index of the value

   211      * @return Attributes of the value

   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 or OOM situation

   218      *     has occured

   219      */

   220     TPIMAttribute AttributesL(const TInt aIndex) const;

   221 

   222     /**

   223      * SetInternalAttributesL

   224      * Sets new internal attributes for a specific value. NOTE:

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

   226      * They only store information which must be preserved when item

   227      * is loaded from the native database and modified before storing

   228      *

   229      * @param aIndex Index of the value

   230      * @param aAttributes New attributes

   231      *

   232      * @par Leaving:

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

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

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

   236      *     means that the value array has gone corrupt or OOM situation

   237      *     has occured

   238      */

   239     void SetInternalAttributesL(

   240         const TInt aIndex,

   241         CArrayFix< TUid>* aInternalAttributes);

   242 

   243     /**

   244      * InternalAttributesL

   245      * Returns internal attributes from the specific value. NOTE:

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

   247      * They only store information which must be preserved when item

   248      * is loaded from the native database and modified before storing

   249      *

   250      * @param aIndex Index of the value

   251      * @return Attributes of the value

   252      *

   253      * @par Leaving:

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

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

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

   257      *     means that the value array has gone corrupt or OOM situation

   258      *     has occured

   259      */

   260     const CArrayFix< TUid>& InternalAttributesL(const TInt aIndex) const;

   261 

   262 private: // New methods

   263 

   264     /**

   265      * Checks that the given index is in the value

   266      * range.

   267      *

   268      * @param aIndex Index which is to be checked

   269      * @return ETrue if the index is in range, EFalse if not

   270      */

   271     TBool IsInRange(const TInt aIndex) const;

   272 

   273 private:

   274 

   275     /**

   276      * C++ default constructor

   277      */

   278     inline CPIMField(const TPIMFieldData& aFieldData);

   279 

   280 private: // Data

   281 

   282     /** Type of this field */

   283     TPIMField iField;

   284 

   285     /** Data type of this field */

   286     TPIMFieldDataType iFieldDataType;

   287 

   288     /** PIM value array */

   289     RPointerArray< CPIMValueBase> iValues;

   290 

   291 };

   292 

   293 #endif // CPIMFIELD_H

   294 // End of file