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:  Access interface to PIM item common data representation.

    15  *

    16 */

    17 

    18 

    19 #ifndef MPIMITEM_H

    20 #define MPIMITEM_H

    21 

    22 //  INCLUDES

    23 #include "pimcommon.h"

    24 #include "bamdesca.h" // For MDesCArray

    25 #include "badesca.h" // For CDesCArray

    26 /**

    27  *  Interface for manipulating item data in the Framework.

    28  *  The interface does

    29  *  as few checks as possible to provide "raw" access to the data in a

    30  *  list-independent manner.

    31  *

    32  *  Only CBase-derived classes may implement this interface. Deriving other

    33  *  M-classes from this class is \b prohibited. Deriving specialized M-classes

    34  *  from this class might result in a "diamond-shaped" inheritance tree,

    35  *  because it is intended that the common parts of the item implementation

    36  *  implement this interface. Specialized implementations will be derived

    37  *  from that common implementation and those must implement the specialized

    38  *  interfaces (M-classes), too. Diamond-shaped inheritance is highly

    39  *  discouraged in Symbian OS. The case is resolved so that the M-classes

    40  *  that would be derived from this class provide a \e getter method, say

    41  *  \c "GetItemData()", that returns a pointer to this interface. The two

    42  *  interfaces access the same object, thus providing an "inheritance-like"

    43  *  accessibility to that object.

    44  *

    45  *  When accessing data through this interface, the following things are

    46  *  checked:

    47  *  @li Field validity in accordance to the PIM type (Contact, Event, ToDo).

    48  *      No fields belonging to different PIM type are allowed to be manipulated

    49  *      through this interface.

    50  *  @li Field value validity in accordance to the field value type (binary,

    51  *      boolean, integer, ...). Value types do not mix.

    52  *  @li Existence of a requested value for given field and index in the value

    53  *      array when getting a value.

    54  *  @li Is a field supported by a specific list (adapter) implementation, if

    55  *      the item belongs to a list.

    56  *  @li Is an attribute valid for a specific field.

    57  *  @li Is an attribute supported by a specific list (adapter) implementation,

    58  *      if the item belongs to a list.

    59  *  @li Value array maximum sizes, if the item belongs to a list.

    60  *

    61  * NOTE: If you use PIM item via this interface, be sure that when modifiying

    62  *       non-initialized fields with huge amount if item may cause significant

    63  *       overhead if the data is not available.

    64  */

    65 NONSHARABLE_CLASS(MPIMItem)

    66 {

    67 public: // Destructor

    68 

    69     /**

    70      * Destructor.

    71      */

    72     virtual ~MPIMItem()

    73     {}

    74 

    75 public: // New functions

    76 

    77     /**

    78      * Provides all fields that have values in the item.

    79      *

    80      * @return An array of fields. The \b ownership of the array is

    81      *         transferred to the caller. The order of fields is

    82      *         undefined.

    83      *

    84      * @par Leaving:

    85      * The method leaves on error.

    86      */

    87     virtual CArrayFix< TPIMField>* GetFieldsL() const = 0;

    88 

    89     /* --- Binary --- */

    90 

    91     /**

    92      * Gets specific binary value.

    93      * The value is Base64-encoded.

    94      *

    95      * @param aField Field constant.

    96      * @param aIndex Value index.

    97      * @return Byte array value.

    98      *         \b Ownership of the return value is transferred to caller.

    99      *

   100      * @par Leaving:

   101      * The method leaves on error. Error codes should be interpreted as

   102      * follows:

   103      * @li \c KErrArgument - \a aField is not valid for the implementing

   104      *     PIM item type.

   105      * @li \c KErrNotFound - There is no value for given \a aIndex.

   106      * @li \c KErrNotSupported - The item is associated with a list and

   107      *     The list does not support \a aField.

   108      */

   109     virtual CPIMByteArray* GetBinaryL(TPIMField aField, TInt aIndex) const = 0;

   110 

   111     /**

   112      * Same as GetBinaryL, but provides the value non-Base64-encoded.

   113      * Ownership of the return value remains.

   114      */

   115     virtual const CPIMByteArray

   116     & GetBinaryRawL(TPIMField aField, TInt aIndex) const = 0;

   117 

   118     /**

   119      * Adds a binary value for a binary field. The value is added as the

   120      * last value in that field's value array.

   121      * The value must be Base64-encoded.

   122      *

   123      * @param aField The field to which the value is added.

   124      * @param aAttributes The attributes to be set for the value.

   125      * @param aValue The binary value to be added to the field.

   126      *        \b Ownership of the value is transferred to the called

   127      *        object.

   128      *

   129      * @par Leaving:

   130      * The method leaves on error. Error codes should be interpreted as

   131      * follows:

   132      * @li \c KErrArgument - \a aField is not valid for the implementing

   133      *     PIM item type or \a aValue is NULL.

   134      * @li \c KErrTooBig - \a aValue is not valid for the field.

   135      * @li \c KErrNotSupported - The item is associated with a list and

   136      *     The list does not support \a aField.

   137      * @li \c KErrOverflow - The field already contains the maximum

   138      *     number of values it can hold.

   139      * @li \c KErrLocked - \a aField is read-only.

   140      * @li Other - The value could not be added.

   141      */

   142     virtual void AddBinaryL(TPIMField aField, TPIMAttribute aAttributes,

   143                             CPIMByteArray* aValue) = 0;

   144 

   145     /**

   146      * Same as AddBinaryL, but takes the value non-Base64-encoded.

   147      */

   148     virtual void AddBinaryRawL(TPIMField aField, TPIMAttribute aAttributes,

   149                                CPIMByteArray* aValue) = 0;

   150 

   151     /**

   152      * Sets an existing binary value, discarding the old value.

   153      * The value must be Base64-encoded.

   154      *

   155      * @param aField The field for which the value is set.

   156      * @param aIndex The index of the value in the value array.

   157      * @param aAttributes The attributes to be set for the value.

   158      * @param aValue The value to be set in the place of the old value.

   159      *        \b Ownership of the new value is transferred to the called

   160      *        object. The old value is deleted.

   161      *

   162      * @par Leaving:

   163      * The method leaves on error. Error codes should be interpreted as

   164      * follows:

   165      * @li \c KErrArgument - \a aField is not valid for the implementing

   166      *     PIM item type or \a aValue is NULL.

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

   168      * @li \c KErrTooBig - \a aValue is not valid for the field.

   169      * @li \c KErrNotSupported - The item is associated with a list and

   170      *     The list does not support \a aField.

   171      * @li \c KErrLocked - \a aField is read-only.

   172      * @li Other - The value could not be set.

   173      */

   174     virtual void SetBinaryL(TPIMField aField, TInt aIndex,

   175                             TPIMAttribute aAttributes, CPIMByteArray* aValue) = 0;

   176 

   177     /**

   178      * Same as SetBinaryL, but takes the value non-Base64-encoded.

   179      */

   180     virtual void SetBinaryRawL(TPIMField aField, TInt aIndex,

   181                                TPIMAttribute aAttributes, CPIMByteArray* aValue) = 0;

   182 

   183     /* --- Date --- */

   184 

   185     /**

   186      * Gets specific date value.

   187      *

   188      * @param aField Field constant.

   189      * @param aIndex Value index.

   190      * @return Date value.

   191      *

   192      * @par Leaving:

   193      * The method leaves on error. Error codes should be interpreted as

   194      * follows:

   195      * @li \c KErrArgument - \a aField is not valid for the implementing

   196      *     PIM item type.

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

   198      * @li \c KErrNotSupported - The item is associated with a list and

   199      *     The list does not support \a aField.

   200      */

   201     virtual const TPIMDate GetDateL(TPIMField aField, TInt aIndex) const = 0;

   202 

   203     /**

   204      * Adds a date value for a date field. The value is added as the

   205      * last value in that field's value array.

   206      *

   207      * @param aField The field to which the value is added.

   208      * @param aAttributes The attributes to be set for the value.

   209      * @param aValue The date value to be added to the field.

   210      *

   211      * @par Leaving:

   212      * The method leaves on error. Error codes should be interpreted as

   213      * follows:

   214      * @li \c KErrArgument - \a aField is not valid for the implementing

   215      *     PIM item type.

   216      * @li \c KErrTooBig - \a aValue is not valid for the field.

   217      * @li \c KErrNotSupported - The item is associated with a list and

   218      *     The list does not support \a aField.

   219      * @li \c KErrOverflow - The field already contains the maximum

   220      *     number of values it can hold.

   221      * @li \c KErrLocked - \a aField is read-only.

   222      * @li Other - The value could not be added.

   223      */

   224     virtual void AddDateL(TPIMField aField, TPIMAttribute aAttributes,

   225                           TPIMDate aValue) = 0;

   226 

   227     /**

   228      * Sets an existing date value, discarding the old value.

   229      *

   230      * @param aField The field for which the value is set.

   231      * @param aIndex The index of the value in the value array.

   232      * @param aAttributes The attributes to be set for the value.

   233      * @param aValue The value to be set in the place of the old value.

   234      *

   235      * @par Leaving:

   236      * The method leaves on error. Error codes should be interpreted as

   237      * follows:

   238      * @li \c KErrArgument - \a aField is not valid for the implementing

   239      *     PIM item type.

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

   241      * @li \c KErrTooBig - \a aValue is not valid for the field.

   242      * @li \c KErrNotSupported - The item is associated with a list and

   243      *     The list does not support \a aField.

   244      * @li \c KErrLocked - \a aField is read-only.

   245      * @li Other - The value could not be set.

   246      */

   247     virtual void SetDateL(TPIMField aField, TInt aIndex,

   248                           TPIMAttribute aAttributes, TPIMDate aValue) = 0;

   249 

   250     /* --- Int --- */

   251 

   252     /**

   253      * Gets specific int value.

   254      *

   255      * @param aField Field constant.

   256      * @param aIndex Value index.

   257      * @return Integer value.

   258      *

   259      * @par Leaving:

   260      * The method leaves on error. Error codes should be interpreted as

   261      * follows:

   262      * @li \c KErrArgument - \a aField is not valid for the implementing

   263      *     PIM item type.

   264      * @li \c KErrNotFound - There is no value for given \a aIndex.

   265      * @li \c KErrNotSupported - The item is associated with a list and

   266      *     The list does not support \a aField.

   267      */

   268     virtual int getInt(TPIMField aField, int aIndex) const = 0;

   269 

   270 

   271     /* --- String --- */

   272 

   273     /**

   274      * Gets specific string value.

   275      *

   276      * @param aField Field constant.

   277      * @param aIndex Value index.

   278      * @return String value.

   279      *

   280      * @par Leaving:

   281      * The method leaves on error. Error codes should be interpreted as

   282      * follows:

   283      * @li \c KErrArgument - \a aField is not valid for the implementing

   284      *     PIM item type.

   285      * @li \c KErrNotFound - There is no value for given \a aIndex.

   286      * @li \c KErrNotSupported - The item is associated with a list and

   287      *     The list does not support \a aField.

   288      */

   289     virtual const TDesC& GetStringL(TPIMField aField, TInt aIndex) const = 0;

   290 

   291     /**

   292      * Adds a string value for a string field. The value is added as the

   293      * last value in that field's value array.

   294      *

   295      * @param aField The field to which the value is added.

   296      * @param aAttributes The attributes to be set for the value.

   297      * @param aValue The string value to be added to the field.

   298      *        \b Ownership of the value is transferred to the called

   299      *        object.

   300      *

   301      * @par Leaving:

   302      * The method leaves on error. Error codes should be interpreted as

   303      * follows:

   304      * @li \c KErrArgument - \a aField is not valid for the implementing

   305      *     PIM item type or \a aValue is NULL.

   306      * @li \c KErrTooBig - \a aValue is not valid for the field.

   307      * @li \c KErrNotSupported - The item is associated with a list and

   308      *     The list does not support \a aField.

   309      * @li \c KErrOverflow - The field already contains the maximum

   310      *     number of values it can hold.

   311      * @li \c KErrLocked - \a aField is read-only.

   312      * @li Other - The value could not be added.

   313      */

   314     virtual void AddStringL(TPIMField aField, TPIMAttribute aAttributes,

   315                             HBufC* aValue) = 0;

   316 

   317     /**

   318      * Sets an existing string value, discarding the old value.

   319      *

   320      * @param aField The field for which the value is set.

   321      * @param aIndex The index of the value in the value array.

   322      * @param aAttributes The attributes to be set for the value.

   323      * @param aValue The value to be set in the place of the old value.

   324      *        \b Ownership of the value is transferred to the called

   325      *        object. The old value is deleted.

   326      *

   327      * @par Leaving:

   328      * The method leaves on error. Error codes should be interpreted as

   329      * follows:

   330      * @li \c KErrArgument - \a aField is not valid for the implementing

   331      *     PIM item type or \a aValue is NULL.

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

   333      * @li \c KErrTooBig - \a aValue is not valid for the field.

   334      * @li \c KErrNotSupported - The item is associated with a list and

   335      *     The list does not support \a aField.

   336      * @li \c KErrLocked - \a aField is read-only.

   337      * @li Other - The value could not be set.

   338      */

   339     virtual void SetStringL(TPIMField aField, TInt aIndex,

   340                             TPIMAttribute aAttributes, HBufC* aValue) = 0;

   341 

   342     /* --- Boolean --- */

   343 

   344     /**

   345      * Gets specific boolean value.

   346      *

   347      * @param aField Field constant.

   348      * @param aIndex Value index.

   349      * @return Boolean value.

   350      *

   351      * @par Leaving:

   352      * The method leaves on error. Error codes should be interpreted as

   353      * follows:

   354      * @li \c KErrArgument - \a aField is not valid for the implementing

   355      *     PIM item type.

   356      * @li \c KErrNotFound - There is no value for given \a aIndex.

   357      * @li \c KErrNotSupported - The item is associated with a list and

   358      *     The list does not support \a aField.

   359      */

   360     virtual TBool GetBooleanL(TPIMField aField, TInt aIndex) const = 0;

   361 

   362     /**

   363      * Adds a boolean value for a boolean field. The value is added as the

   364      * last value in that field's value array.

   365      *

   366      * @param aField The field to which the value is added.

   367      * @param aAttributes The attributes to be set for the value.

   368      * @param aValue The boolean value to be added to the field.

   369      *

   370      * @par Leaving:

   371      * The method leaves on error. Error codes should be interpreted as

   372      * follows:

   373      * @li \c KErrArgument - \a aField is not valid for the implementing

   374      *     PIM item type.

   375      * @li \c KErrTooBig - \a aValue is not valid for the field.

   376      * @li \c KErrNotSupported - The item is associated with a list and

   377      *     The list does not support \a aField.

   378      * @li \c KErrOverflow - The field already contains the maximum

   379      *     number of values it can hold.

   380      * @li \c KErrLocked - \a aField is read-only.

   381      * @li Other - The value could not be added.

   382      */

   383     virtual void AddBooleanL(TPIMField aField, TPIMAttribute aAttributes,

   384                              TBool aValue) = 0;

   385 

   386     /**

   387      * Sets an existing boolean value, discarding the old value.

   388      *

   389      * @param aField The field for which the value is set.

   390      * @param aIndex The index of the value in the value array.

   391      * @param aAttributes The attributes to be set for the value.

   392      * @param aValue The value to be set in the place of the old value.

   393      *

   394      * @par Leaving:

   395      * The method leaves on error. Error codes should be interpreted as

   396      * follows:

   397      * @li \c KErrArgument - \a aField is not valid for the implementing

   398      *     PIM item type.

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

   400      * @li \c KErrTooBig - \a aValue is not valid for the field.

   401      * @li \c KErrNotSupported - The item is associated with a list and

   402      *     The list does not support \a aField.

   403      * @li \c KErrLocked - \a aField is read-only.

   404      * @li Other - The value could not be set.

   405      */

   406     virtual void SetBooleanL(TPIMField aField, TInt aIndex,

   407                              TPIMAttribute aAttributes, TBool aValue) = 0;

   408 

   409     /* --- StringArray --- */

   410 

   411     /**

   412      * Gets specific string array value.

   413      * Empty string array elements are denoted with an empty string.

   414      *

   415      * @param aField Field constant.

   416      * @param aIndex Value index.

   417      * @return StringArray value.

   418      *

   419      * @par Leaving:

   420      * The method leaves on error. Error codes should be interpreted as

   421      * follows:

   422      * @li \c KErrArgument - \a aField is not valid for the implementing

   423      *     PIM item type.

   424      * @li \c KErrNotFound - There is no value for given \a aIndex.

   425      * @li \c KErrNotSupported - The item is associated with a list and

   426      *     The list does not support \a aField.

   427      */

   428     virtual const CDesCArray

   429     & GetStringArrayL(TPIMField aField, TInt aIndex) const = 0;

   430 

   431     /**

   432      * Adds a string array value for a string array field.

   433      * The value is added as the last value in that field's value array.

   434      * All elements of the string array must be present in their specified

   435      * indexes. Empty elements are denoted with an empty string.

   436      *

   437      * @param aField The field to which the value is added.

   438      * @param aAttributes The attributes to be set for the value.

   439      * @param aValue The string array value to be added to the field.

   440      *        \b Ownership of the value is transferred to the called

   441      *        object.

   442      *

   443      * @par Leaving:

   444      * The method leaves on error. Error codes should be interpreted as

   445      * follows:

   446      * @li \c KErrArgument - \a aField is not valid for the implementing

   447      *     PIM item type or \a aValue is NULL.

   448      * @li \c KErrTooBig - \a aValue is not valid for the field.

   449      * @li \c KErrNotSupported - The item is associated with a list and

   450      *     The list does not support \a aField.

   451      * @li \c KErrOverflow - The field already contains the maximum

   452      *     number of values it can hold.

   453      * @li \c KErrLocked - \a aField is read-only.

   454      * @li Other - The value could not be added.

   455      */

   456     virtual void AddStringArrayL(TPIMField aField, TPIMAttribute aAttributes,

   457                                  CDesCArray* aValue) = 0;

   458 

   459     /**

   460      * Sets an existing string array value, discarding the old value.

   461      * All elements of the string array must be present in their specified

   462      * indexes. Empty elements are denoted with an empty string.

   463      *

   464      * @param aField The field for which the value is set.

   465      * @param aIndex The index of the value in the value array.

   466      * @param aAttributes The attributes to be set for the value.

   467      * @param aValue The value to be set in the place of the old value.

   468      *        \b Ownership of the value is transferred to the called

   469      *        object. The old value is deleted.

   470      *

   471      * @par Leaving:

   472      * The method leaves on error. Error codes should be interpreted as

   473      * follows:

   474      * @li \c KErrArgument - \a aField is not valid for the implementing

   475      *     PIM item type or \a aValue is NULL.

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

   477      * @li \c KErrTooBig - \a aValue is not valid for the field.

   478      * @li \c KErrNotSupported - The item is associated with a list and

   479      *     The list does not support \a aField.

   480      * @li \c KErrLocked - \a aField is read-only.

   481      * @li Other - The value could not be set.

   482      */

   483     virtual void SetStringArrayL(TPIMField aField, TInt aIndex,

   484                                  TPIMAttribute aAttributes, CDesCArray* aValue) = 0;

   485 

   486     /**

   487      * Counts the number of values in a specific field.

   488      *

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

   490      *

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

   492      *

   493      * @par Leaving:

   494      * The method leaves on error. Error codes should be interpreted as

   495      * follows:

   496      * @li \c KErrArgument - \a aField is not valid for the implementing

   497      *     PIM item type.

   498      * @li \c KErrNotSupported - The item is associated with a list and

   499      *     The list does not support \a aField.

   500      */

   501     virtual TInt CountValuesL(TPIMField aField) const = 0;

   502 

   503 

   504     /**

   505      * Provides attributes of a specific value of a specific field.

   506      *

   507      * @param aField The field that has the value.

   508      * @param aIndex The index of the value in the value array.

   509      *

   510      * @return The attributes set for the value, orred bitwise.

   511      *

   512      * @par Leaving:

   513      * The method leaves on error. Error codes should be interpreted as

   514      * follows:

   515      * @li \c KErrArgument - \a aField is not valid for the implementing

   516      *     PIM item type.

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

   518      * @li \c KErrNotSupported - The item is associated with a list and

   519      *     The list does not support \a aField.

   520      */

   521     virtual TPIMAttribute

   522     getAttributes(TPIMField aField, TInt aIndex) const = 0;

   523 

   524     /**

   525      * Adds the item to a category.

   526      * If the item already belongs to the category, nothing is done.

   527      *

   528      * @param aCategory The category. Category name is copied if necessary.

   529      *

   530      * @par Leaving:

   531      * The method leaves on error. Error codes should be interpreted as

   532      * follows:

   533      * @li \c KErrArgument - \a aCategory is not valid for the item.

   534      * @li Other - The item could not be added to the category for some

   535      *     internal reason.

   536      */

   537     virtual void AddToCategoryL(const TDesC& aCategory) = 0;

   538 

   539     /**

   540      * Removes the item from a category.

   541      * If the item does not belong to the category, nothing is done.

   542      *

   543      * @param aCategory. The category.

   544      *

   545      */

   546     virtual void RemoveFromCategory(const TDesC& aCategory) = 0;

   547 

   548     /**

   549      * Provides the categories to which the item belongs to.

   550      *

   551      * @return Array of categories.

   552      *

   553      * @par Leaving:

   554      * The method leaves on error.

   555      */

   556     virtual const CDesCArray& GetCategoriesL() const = 0;

   557 

   558     /**

   559      * Provides the Item ID of the item.

   560      *

   561      * @return Item ID. If the Item ID is not set, \ref KPIMNullItemID is

   562      *         returned.

   563      */

   564     virtual TPIMItemID GetId() const = 0;

   565 

   566     /**

   567      * Sets the Item ID of the item.

   568      *

   569      * @param aItemID The new Item ID.

   570      *

   571      * @par Leaving:

   572      * @li Any - An internal error.

   573      */

   574     virtual void SetIdL(TPIMItemID aItemID) = 0;

   575 

   576     /**

   577      * Sets the last modified date/time of the item.

   578      */

   579     virtual void SetLastModifiedL(TPIMDate aLastModified) = 0;

   580 

   581     /**

   582      * Gets the last modified date/time of the item.

   583      */

   584     virtual TPIMDate LastModified() const = 0;

   585 

   586 protected: // Non-public operations

   587 

   588     // Allow derivation with protected default constructor.

   589     MPIMItem()

   590     {}

   591 

   592 }

   593 ;

   594 

   595 #endif // MPIMITEM_H

   596 // End of File