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

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

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

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

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

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

must also implement:</p><ul>

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

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

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

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

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

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

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

    {

    public: 

        static CConverterBase2* NewL();        CExampleConverter();

        ~CExampleConverter();    

        // from CConverterBase2

        void ConvertObjectAL( RReadStream& aReadStream, 

                              RWriteStream& aWriteStream, 

                              MConverterUiObserver* aObserver = NULL );

        TBool DoConvertL();

        TUid Uid();

        TInt Capabilities();

        void CancelConvert();

    private:

        RReadStream* iReadStream;

        RWriteStream* iWriteStream;

    };

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

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