<?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&amp; aReadStream, 
                              RWriteStream&amp; 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>
</taskbody></task>