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:  Converts properties vCard <-> PIM API

    15  *

    16 */

    17 

    18 

    19 #ifndef CPIMCARDPROPERTYCONVERTER_H

    20 #define CPIMCARDPROPERTYCONVERTER_H

    21 

    22 //  INCLUDES

    23 #include <e32base.h> // CBase

    24 #include <badesca.h> // CDesCArray

    25 #include "pimcontact.h" // TPIMContactField

    26 #include "pimcommon.h" // TPIMAttribute

    27 // CLASS DECLARATION

    28 class CPIMItem;

    29 class CPIMContactItem;

    30 class CParserVCard;

    31 class CParserParam;

    32 class CPIMParserProperty;

    33 class CParserProperty;

    34 class CPIMContactValidator;

    35 class CPIMVCardParserParamArray;

    36 class CParserPropertyValue;

    37 

    38 /**

    39  *  Converts Properties from versit objects to fields in PIM Contact items.

    40  */

    41 NONSHARABLE_CLASS(CPIMCardPropertyConverter): public CBase

    42 {

    43 public: // Constructors and destructor

    44 

    45     /**

    46      * Two-phased constructor.

    47      */

    48     static CPIMCardPropertyConverter* NewL(

    49         const CPIMContactValidator& aValidator);

    50 

    51     /**

    52      * Destructor

    53      */

    54     virtual ~CPIMCardPropertyConverter();

    55 

    56 public: // New functions

    57 

    58     /**

    59      * Inserts a Field from a PIM Contact Item to CParserVCard as

    60      * a property.

    61      *

    62      * @param aItem item to read the field from

    63      * @param aParser parser to insert the property to.

    64      * @param aField field to convert

    65      *

    66      */

    67     void ConvertFieldL(

    68         const CPIMItem& aItem,

    69         CParserVCard& aParser,

    70         TPIMContactField aField);

    71 

    72     /**

    73      * Inserts a property from a vCard to a PIM Contact Item as a field.

    74      * If the property contains another vCard, that vCard is returned.

    75      * Otherwise NULL is returned.

    76      *

    77      * @param aProperty property to convert

    78      * @param aItem item to write the field to

    79      * @param aItemArray Array where agent field items are stored

    80      *

    81      * @return contained vCard, or NULL.

    82      */

    83     CParserVCard* ConvertPropertyL(

    84         const CParserProperty& aProperty,

    85         CPIMContactItem& aItem);

    86 

    87 private:

    88     /**

    89      * C++ default constructor.

    90      */

    91     CPIMCardPropertyConverter(const CPIMContactValidator& aValidator);

    92 

    93     /**

    94      * Converts an agent property. The contained vCard is returned.

    95      *

    96      * @param aProperty property to convert

    97      *

    98      * @return contained vCard.

    99      */

   100     CParserVCard* ConvertAgentPropertyL(

   101         const CPIMParserProperty& aProperty);

   102 

   103     /**

   104      * Adds parameters "HOME" and "WORK" to an array of property

   105      * parameters if needed. Ownership of the new parameter objects

   106      * is transferred to the caller.

   107      *

   108      * @param aAttributes Checked, if contains EPIMContactAttrHome or

   109      *        EPIMContactAttrWork, the parameter is added.

   110      *

   111      * @param aParamArray Property parameter array to add the parameters

   112      *        to.

   113      */

   114     void AddParamHomeAndWorkL(TPIMAttribute aAttributes,

   115                               CPIMVCardParserParamArray& aParamArray);

   116 

   117     /**

   118      * Converts an address field from a PIM Contact Item to CParserVCard.

   119      * The field is stored in the parser as a property.

   120      *

   121      * @param aItem item to read the field from

   122      * @param aParser parser to insert the property to.

   123      * @param aField field to convert

   124      * @param aIndex index to the field to convert

   125      *

   126      * @par Leaving:

   127      * This method leaves on an error with system wide error codes.

   128      */

   129     void ConvertAddressFieldL(

   130         const CPIMItem& aItem,

   131         CParserVCard& aParser,

   132         TPIMContactField aField,

   133         TInt aIndex);

   134 

   135     /**

   136      * Converts a name field from a PIM Contact Item to CParserVCard.

   137      * The field is stored in the parser as a property.

   138      *

   139      * @param aItem item to read the field from

   140      * @param aParser parser to insert the property to.

   141      * @param aField field to convert

   142      * @param aIndex index to the field to convert

   143      *

   144      * @par Leaving:

   145      * This method leaves on an error with system wide error codes.

   146      */

   147     void ConvertNameFieldL(

   148         const CPIMItem& aItem,

   149         CParserVCard& aParser,

   150         TPIMContactField aField,

   151         TInt aIndex);

   152 

   153     /**

   154      * Converts name and address arrays from a vCard to a PIM Contact Item.

   155      *

   156      * @param aProperty property to convert

   157      * @param aItem item to write the field to

   158      *

   159      */

   160     void ConvertCDesCArrayPropertyL(

   161         const CPIMParserProperty& aProperty,

   162         CPIMContactItem& aItem);

   163 

   164     /**

   165      * Converts a date field from a PIM Contact Item to a CParserVCard.

   166      * The field is stored in the parser as a property.

   167      *

   168      * @param aItem item to read the field from

   169      * @param aParser parser to insert the property to.

   170      * @param aField field to convert

   171      * @param aIndex index to the field to convert

   172      *

   173      * @par Leaving:

   174      * This method leaves on an error with system wide error codes.

   175      */

   176     void ConvertDateFieldL(

   177         const CPIMItem& aItem,

   178         CParserVCard& aParser,

   179         TPIMContactField aField,

   180         TInt aIndex);

   181 

   182     /**

   183      * Converts a birthday field from a vCard to a PIM Contact Item.

   184      *

   185      * @param aProperty property to convert

   186      * @param aItem item to write the field to

   187      *

   188      */

   189     void ConvertDatePropertyL(

   190         const CPIMParserProperty& aProperty,

   191         CPIMContactItem& aItem);

   192 

   193     /**

   194      * Adds new parser parameter to the parameter array

   195      *

   196      * @param aArrayOfParams Parameter array

   197      * @param aParamName The name of the parameter which will be added

   198      */

   199     void AddParserParameterL(

   200         CPIMVCardParserParamArray& aArrayOfParams,

   201         const TPtrC8 aParamName);

   202 

   203     /**

   204      * Converts a string field from a PIM Contact Item to a CParserVCard.

   205      * The field is stored in the parser as a property.

   206      *

   207      * @param aItem item to read the field from

   208      * @param aParser parser to insert the property to.

   209      * @param aField field to convert

   210      * @param aIndex index to the field to convert

   211      *

   212      * @par Leaving:

   213      * This method leaves on an error with system wide error codes.

   214      */

   215     void ConvertStringFieldL(

   216         const CPIMItem& aItem,

   217         CParserVCard& aParser,

   218         TPIMContactField aField,

   219         TInt aIndex);

   220 

   221     /**

   222      * Converts a string field from a vCard to a PIM Contact Item.

   223      *

   224      * @param aProperty property to convert

   225      * @param aItem item to write the field to

   226      *

   227      */

   228     void ConvertStringPropertyL(

   229         const CPIMParserProperty& aProperty,

   230         CPIMContactItem& aItem);

   231 

   232     /**

   233      * Converts a photo field from a PIM Contact Item to a CParserVCard.

   234      * The field is stored in the parser as a property.

   235      *

   236      * @param aItem item to read the field from

   237      * @param aParser parser to insert the property to.

   238      * @param aField field to convert

   239      * @param aIndex index to the field to convert

   240      *

   241      * @par Leaving:

   242      * This method leaves on an error with system wide error codes.

   243      */

   244     void ConvertPhotoFieldL(

   245         const CPIMItem& aItem,

   246         CParserVCard& aParser,

   247         TPIMContactField aField,

   248         TInt aIndex);

   249 

   250     /**

   251      * Inserts a PHOTO property from a vCard to a PIM Contact Item as a

   252      * binary field

   253      *

   254      * @param aProperty property to convert

   255      * @param aItem item to write the field to

   256      *

   257      */

   258     void ConvertPhotoPropertyL(

   259         const CPIMParserProperty& aProperty,

   260         CPIMContactItem& aItem);

   261 

   262     /**

   263      * Converts a class field from a PIM Contact Item to a CParserVCard.

   264      * The field is stored in the parser as a property.

   265      *

   266      * @param aItem item to read the field from

   267      * @param aParser parser to insert the property to.

   268      * @param aField field to convert

   269      * @param aIndex index to the field to convert

   270      *

   271      * @par Leaving:

   272      * This method leaves on an error with system wide error codes.

   273      */

   274     void ConvertClassFieldL(

   275         const CPIMItem& aItem,

   276         CParserVCard& aParser,

   277         TPIMContactField aField,

   278         TInt aIndex);

   279 

   280     /**

   281      * Inserts a CLASS property from a vCard to a PIM Contact Item as a

   282      * integer field

   283      *

   284      * @param aProperty property to convert

   285      * @param aItem item to write the field to

   286      *

   287      */

   288     void ConvertClassPropertyL(

   289         const CPIMParserProperty& aProperty,

   290         CPIMContactItem& aItem);

   291 

   292     /**

   293      * Converts organisational fields from a PIM Contact Item to a

   294      * CParserVCard. The field is stored in the parser as a property.

   295      *

   296      * @param aItem item to read the field from

   297      * @param aParser parser to insert the property to.

   298      * @param aField field to convert

   299      * @param aIndex index to the field to convert

   300      *

   301      * @par Leaving:

   302      * This method leaves on an error with system wide error codes.

   303      */

   304     void ConvertOrganisationalFieldsL(

   305         const CPIMItem& aItem,

   306         CParserVCard& aParser,

   307         TPIMContactField aField,

   308         TInt aIndex);

   309 

   310     /**

   311      * Converts vCard name readings to a PIM item name array elements

   312      *

   313      * @param aProperty vCard property value

   314      * @param aItem Contact List item

   315      * @param aNameArrayElementIndex Index of this element

   316      */

   317     void ConvertNameReadingFieldL(

   318         const CPIMParserProperty& aProperty,

   319         CPIMContactItem& aItem);

   320 

   321     /**

   322      * Adds a new property to the vCard parser

   323      * Note that property value and array of params are popped

   324      * from the cleanup stack inside this function

   325      *

   326      * @param aPropertyValue Property value for the vCard property

   327      *        This needs not to be pushed to the cleanup stack before

   328      *        this function call since it is done straight from the start

   329      *        of this function

   330      * @param aPropertyName Name of the property

   331      * @param aArrayOfParams Parameter array. This can be NULL and must be

   332      *        pushed to the cleanup stack before this function call

   333      * @param aParser VCard parser into which the new property is pushed

   334      */

   335     void AddPropertyToParserL(

   336         CParserPropertyValue* aPropertyValue,

   337         const TDesC8& aPropertyName,

   338         CPIMVCardParserParamArray* aArrayOfParams,

   339         CParserVCard& aParser);

   340 

   341 private: // data

   342 

   343     // Validates contacts

   344     const CPIMContactValidator& iContactValidator;

   345 

   346 };

   347 

   348 #endif // CPIMCARDPROPERTYCONVERTER_H

   349 

   350 // End of file