1 /*

     2 * Copyright (c) 2005-2007 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:  The vcard engine for importing/exporting vcards and compact

    15 *                business cards.

    16 *

    17 */

    18 

    19 

    20 #ifndef CVPBKVCARDENG_H

    21 #define CVPBKVCARDENG_H

    22 

    23 

    24 // INCLUDES

    25 #include <e32base.h>

    26 #include <f32file.h>

    27 #include <s32file.h>

    28 

    29 // FORWARD DECLARATIONS

    30 class MVPbkFieldTypeList;

    31 class CVPbkContactManager;

    32 class MVPbkStoreContact;

    33 class MVPbkFieldType;

    34 class MVPbkContactOperationBase;

    35 class MVPbkSingleContactOperationObserver;

    36 class MVPbkContactCopyObserver;

    37 class MVPbkContactLink;

    38 class MVPbkContactStore;

    39 class CVPbkVCardData;

    40 

    41 // CLASS DECLARATIONS

    42 

    43 /**

    44  * The vcard engine for importing/exporting vcards and compact business cards.

    45  * 

    46  * @lib VPbkVCardEng.lib

    47  */

    48 class CVPbkVCardEng : public CBase

    49     {

    50     public:  // Constructors and destructor

    51         /**

    52          * Creates VCard engine instance.

    53          * @param aContactManager The Contact manager.

    54          * @return A new instance of the CVPbkVCardEng.

    55          */

    56         IMPORT_C static CVPbkVCardEng* NewL(

    57                 CVPbkContactManager& aContactManager);

    58 

    59         /**

    60          * Destructor.

    61          */

    62         ~CVPbkVCardEng();

    63 

    64     public: // New methods

    65 

    66         /**

    67          * Reads vCard records from a stream and saves contacts to the store

    68          * asynchronously. 

    69          * 

    70          * A client receives links to the created contacts in a call back.

    71          *

    72          * @param aTargetStore The Virtual Phonebook store in which the 

    73          *                     information is copied to. The store must be 

    74          *                     writable.

    75          * @param aSourceStream A stream where the vCard data is read from

    76          * @param aObserver The observer who is notified when the import

    77          *                  completes. Failed cases:

    78          *                  -KErrNotFound if the card contained fields that

    79          *                  cannot be saved to the target store i.e. 

    80          *                  the operation didn't find any fields to copy.

    81          * @return A new operation handle owned by the client.

    82          * @exception KErrNotFound if the engine didn't find a copy policy

    83          *                         for the target store.

    84          * @asynchronous

    85          */

    86         IMPORT_C MVPbkContactOperationBase* ImportVCardL(

    87                 MVPbkContactStore& aTargetStore, 

    88                 RReadStream &aSourceStream,

    89                 MVPbkContactCopyObserver& aObserver);

    90                 

    91         /**

    92          * Reads vCard records from a stream and saves contacts to the store

    93          * asynchronously. 

    94          * 

    95          * A client receives links to the created contacts in a call back.

    96          * NOTE: This API is introduced for performance improvements in sync.

    97          *       When imported for Sync the duplicate policy checks are ignored.

    98          *

    99          * @param aTargetStore The Virtual Phonebook store in which the 

   100          *                     information is copied to. The store must be 

   101          *                     writable.

   102          * @param aSourceStream A stream where the vCard data is read from

   103          * @param aObserver The observer who is notified when the import

   104          *                  completes. Failed cases:

   105          *                  -KErrNotFound if the card contained fields that

   106          *                  cannot be saved to the target store i.e. 

   107          *                  the operation didn't find any fields to copy.

   108          * @return A new operation handle owned by the client.

   109          * @exception KErrNotFound if the engine didn't find a copy policy

   110          *                         for the target store.

   111          * @asynchronous

   112          */        

   113         IMPORT_C MVPbkContactOperationBase* ImportVCardForSyncL(

   114                 MVPbkContactStore& aTargetStore, 

   115                 RReadStream &aSourceStream,

   116                 MVPbkContactCopyObserver& aObserver);                

   117                 

   118         /**

   119          * Reads vCard records from a stream and creates contacts

   120          * asynchronously. 

   121          *

   122          * A client handles commiting the contact(s). Otherwise contacts

   123          * are not saved to the store.

   124 		 *

   125 		 * @param aImportedContact An array for imported contacts from

   126 		 *                         the client. Contains results after

   127 		 *                         asynchronous import operation has completed.

   128 		 * @param aTargetStore The Virtual Phonebook Store in which the 

   129 		 *                     information is copied to. The store must be 

   130 		 *                     writable.

   131          * @param aSourceStream A stream where the vCard data is read from.

   132          * @param aObserver An observer for asynchronous import.

   133          *                  The aContact in the call back is always NULL.

   134          * @return A new operation handle owned by the client.

   135          * @asynchronous

   136          */

   137         IMPORT_C MVPbkContactOperationBase* ImportVCardL(

   138                 RPointerArray<MVPbkStoreContact>& aImportedContacts,

   139                 MVPbkContactStore& aTargetStore, 

   140                 RReadStream &aSourceStream,

   141                 MVPbkSingleContactOperationObserver& aObserver );

   142             

   143               

   144         /**

   145          * Reads Compact Business Card records from a stream and saves

   146          * contacts to the store asynchronously. 

   147          *

   148          * A client receives links to the created contacts in a call back.

   149 		 *

   150 		 * @param aTargetStore The Virtual Phonebook Store in which the 

   151 		 *                     information is copied to. The store must be 

   152 		 *                     writable.

   153          * @param aSourceStream A stream where the card data is read from.

   154          * @param aObserver An observer for asynchronous import.

   155          *                  If successful there is one or more contact

   156          *                  links in the array. Failed cases:

   157          *                  -KErrNotSupported if the card is not compact 

   158          *                  business card

   159          *                  -KErrCorrupted if the data is corrupted

   160          *                  -KErrNotFound if there were no supported fields

   161          *                  in the card.

   162          * @return A new operation handle owned by the client.

   163          * @exception KErrNotFound if the engine didn't find a copy policy

   164          *                         for the target store.

   165          * @asynchronous

   166          */

   167         IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(

   168             MVPbkContactStore& aTargetStore,

   169 			RReadStream &aSourceStream,

   170             MVPbkContactCopyObserver& aObserver );

   171         

   172         /**

   173          * Reads Compact Business Card records from a stream and creates

   174          * contacts asynchronously. 

   175          *

   176          * A client handles commiting the contact(s). Otherwise contacts

   177          * are not saved to the store.

   178 		 *

   179 		 * @param aImportedContact An array for imported contacts from

   180 		 *                         the client. Contains results after

   181 		 *                         asynchronous import operation has completed. 

   182 		 * @param aTargetStore The Virtual Phonebook Store in which the 

   183 		 *                     contacts are created from. The store must be 

   184 		 *                     writable.

   185          * @param aSourceStream A stream where the card data is read from.

   186          * @param aObserver An observer for asynchronous import.

   187          *                  aContact is always NULL in call back.

   188          *                  If successful there is one or more contact

   189          *                  links in the array. Failed cases:

   190          *                  -KErrNotSupported if the card is not compact 

   191          *                  business card

   192          *                  -KErrCorrupted if the data is corrupted

   193          *                  -KErrNotFound if there were no supported fields

   194          *                  in the card.

   195          * @return A new operation handle owned by the client.

   196          * @exception KErrNotFound if the engine didn't find a copy policy

   197          *                         for the target store.

   198          * @asynchronous

   199          */

   200         IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(

   201             RPointerArray<MVPbkStoreContact>& aImportedContacts,

   202             MVPbkContactStore& aTargetStore,

   203 			RReadStream &aSourceStream,

   204             MVPbkSingleContactOperationObserver& aObserver );

   205 

   206         /**

   207          * Exports contact information asynchronously to a vCard record.

   208 		 *

   209 		 * The client gives the contact whose information is exported.

   210 		 *

   211 		 * @param aDestStream A stream where the vCard data is written to.

   212 		 *        The data written to the stream is not Committed by this method.

   213 		 * @param aSourceItem A contact whose information is exported.

   214          * @param aObserver An observer that is notified when the export completes.

   215          *          A store contact returned when operation has completed is

   216          *          always NULL.

   217          * @param aBeamed If ETrue, then select fields are masked while exporting VCard

   218          * @return A new operation handle owned by the client.

   219          * @asynchronous

   220          */

   221         IMPORT_C MVPbkContactOperationBase* ExportVCardL( 

   222             RWriteStream& aDestStream, 

   223             const MVPbkStoreContact& aSourceItem,

   224             MVPbkSingleContactOperationObserver& aObserver);

   225 

   226         /**

   227          * Exports contact information asynchronously to a vCard record.

   228          * 

   229          * The client gives the identifier of the contact that is first loaded

   230          * and then exported.

   231          *

   232          * @param aDestStream A stream where the vCard data is written to.

   233          *        The data written to the stream is not Commited by this method.

   234          * @param aContactLink An identifier of the contact that is exported.

   235          * @param aObserver An observer that is notified when the export completes.

   236          *          A store contact returned when operation has completed is

   237          *          always NULL.

   238          * @param aBeamed If ETrue, then select fields are masked while exporting VCard

   239          * @return A new operation handle owned by the client.

   240          * @asynchronous

   241          */

   242         IMPORT_C MVPbkContactOperationBase* ExportVCardL(

   243             RWriteStream& aDestStream, 

   244             const MVPbkContactLink& aContactLink,

   245             MVPbkSingleContactOperationObserver& aObserver);

   246             

   247         /**

   248         * Exports contact information asynchronously to a vCard record.

   249          * Note: Includes the fields, X-FAVORITE and X-SELF, during export

   250          *

   251          * The client gives the contact whose information is exported.

   252          *

   253          * @param aDestStream A stream where the vCard data is written to.

   254          *        The data written to the stream is not Committed by this method.

   255          * @param aSourceItem A contact whose information is exported.

   256         * @param aObserver An observer that is notified when the export completes.

   257         *          A store contact returned when operation has completed is

   258         *          always NULL.

   259         * @return A new operation handle owned by the client.

   260         * @asynchronous

   261         */

   262         IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL( 

   263             RWriteStream& aDestStream, 

   264             const MVPbkStoreContact& aSourceItem,

   265             MVPbkSingleContactOperationObserver& aObserver);

   266 

   267         /**

   268          * Exports contact information asynchronously to a vCard record.

   269          * Note: Includes the fields, X-FAVORITE and X-SELF, during export

   270          * 

   271          * The client gives the identifier of the contact that is first loaded

   272          * and then exported.

   273          *

   274          * @param aDestStream A stream where the vCard data is written to.

   275          *        The data written to the stream is not Commited by this method.

   276          * @param aContactLink An identifier of the contact that is exported.

   277          * @param aObserver An observer that is notified when the export completes.

   278          *          A store contact returned when operation has completed is

   279          *          always NULL.

   280          * @return A new operation handle owned by the client.

   281          * @asynchronous

   282          */

   283         IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL(

   284             RWriteStream& aDestStream, 

   285             const MVPbkContactLink& aContactLink,

   286             MVPbkSingleContactOperationObserver& aObserver);

   287             

   288                     

   289         /** 

   290          * Returns true for those field types that are supported by the vCard

   291          * format and this engine.

   292          *

   293          * @param aFieldType A field type that is looked for.

   294          * @return ETrue if given field is supported, EFalse otherwise

   295          */

   296         IMPORT_C TBool SupportsFieldType(const MVPbkFieldType& aFieldType);

   297 

   298 

   299         /**

   300          * Returns field types that are supported by vCard engine.

   301          *

   302          * @return Field types that are supported by vCard engine.

   303          */

   304         IMPORT_C const MVPbkFieldTypeList& SupportedFieldTypes();

   305         

   306         /**

   307          * Reads vCard records from a stream and replaces contacts

   308          * asynchronously. 

   309          *

   310          * A client handles commiting the contact(s). Otherwise contacts

   311          * are not saved to the store.

   312 		 *

   313 		 * @param aReplaceContact Current contact which needs to replaced with

   314 		 *                         the contact recevied from server as VcardBuffer. Contains results after

   315 		 *                         asynchronous import operation has completed.

   316 		 * @param aTargetStore The Virtual Phonebook Store in which the 

   317 		 *                     information is copied to. The store must be 

   318 		 *                     writable.

   319          * @param aSourceStream A stream where the vCard data is read from.

   320          * @param aObserver An observer for asynchronous import.

   321          *                  The aContact in the call back is always NULL.

   322          * @return A new operation handle owned by the client.

   323          * @asynchronous

   324          */   

   325         IMPORT_C MVPbkContactOperationBase* CVPbkVCardEng::ImportVCardMergeL(

   326             const MVPbkContactLink& aReplaceContact,

   327             MVPbkContactStore& aTargetStore, 

   328             RReadStream& aSourceStream,

   329             MVPbkSingleContactOperationObserver& aObserver );

   330 

   331     private: // Implementation

   332         CVPbkVCardEng(CVPbkContactManager& aContactManager);

   333         void ConstructL();

   334 

   335     private: // Data

   336         /// Ref: Contact manager reference

   337         CVPbkContactManager&                        iContactManager;

   338         /// Own: Data for vCard handling

   339         CVPbkVCardData*                             iData;

   340     };

   341 

   342 

   343 #endif  // CVPBKVCARDENG_H

   344 

   345 // End of file