1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-49C93C36-D86B-4EEE-A8AB-4279312DF4BC" xml:lang="en"><title>Write

    13 an interface implementation for a converter</title><prolog><metadata><keywords/></metadata></prolog><taskbody>

    14 <context>       <p>Conversion from one data type to another is performed by

    15 a class derived from the abstract <codeph>CConverterBase2</codeph> class.

    16 Conversions can be performed between files specified by filenames, or between

    17 objects which support the stream interfaces. For example, stream stores, memory

    18 streams and the clipboard.</p><p>Implement the following key <codeph>CConverterBase2</codeph> functions:</p><ul>

    19 <li><p><codeph>ConvertAL()</codeph>, which prepares the converter to convert

    20 data in a file. By default, this leaves with <codeph>KErrNotSupported</codeph>.</p></li>

    21 <li><p><codeph>ConvertObjectAL()</codeph>, which prepares the converter to

    22 convert data in a stream. By default, this leaves with <codeph>KErrNotSupported</codeph>.</p></li>

    23 <li><p><codeph>DoConvertL()</codeph>, which performs a step in the conversion

    24 and indicates whether the conversion is complete, or whether the client needs

    25 to call <codeph>DoConvertL()</codeph> again. By default this leaves with <codeph>KErrNotSupported</codeph>.</p></li>

    26 <li><p><codeph>CancelConvert()</codeph>, which can be called at any stage

    27 in the conversion process to cancel the conversion.</p></li>

    28 </ul><p><b>NOTE</b>: The approach of an initial preparatory step followed

    29 by a sequence of further incremental steps allows the client thread to stay

    30 responsive while a potentially lengthy conversion process is taking place.</p><p><codeph>CConverterBase2</codeph> also

    31 defines two functions which do the complete conversion in one function call: <codeph>ConvertL()</codeph> and <codeph>ConvertObjectL()</codeph>. <codeph>CConverterBase2</codeph> supplies default implementations of these functions

    32 which perform their tasks by calling <codeph>ConvertAL()</codeph> or <codeph>ConvertObjectAL()</codeph> once,

    33 and <codeph>DoConvertL()</codeph> in a loop until complete. </p><p>A converter

    34 must also implement:</p><ul>

    35 <li><p><codeph>Uid()</codeph> to return a UID that uniquely identifies the

    36 converter. This should be the same value as the <codeph>conv_uid</codeph> value

    37 defined in the converter's <codeph>CONARC_RESOURCE_FILE</codeph> resource.</p></li>

    38 <li><p><codeph>Capabilities()</codeph> to return a flag indicating if the

    39 converter can convert files, streams, or both.</p></li>

    40 </ul><p>The following code snippet is an example declaration of a converter

    41 class:</p><codeblock xml:space="preserve">class CExampleConverter : public CConverterBase2

    42     {

    43     public: 

    44         static CConverterBase2* NewL();        CExampleConverter();

    45         ~CExampleConverter();    

    46         // from CConverterBase2

    47         void ConvertObjectAL( RReadStream& aReadStream, 

    48                               RWriteStream& aWriteStream, 

    49                               MConverterUiObserver* aObserver = NULL );

    50         TBool DoConvertL();

    51         TUid Uid();

    52         TInt Capabilities();

    53         void CancelConvert();

    54     private:

    55         RReadStream* iReadStream;

    56         RWriteStream* iWriteStream;

    57     };

    58 </codeblock><p><b>Note</b>: The <codeph>MConverterUiObserver</codeph> observer

    59 pointer can be NULL, so check for this before calling its functions.</p></context>

    60 </taskbody></task>