<?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 concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en" id="GUID-E8EF06D7-FB4E-598D-9D9D-4395AB6F51C8"><title>Creating a Charconv Plug-in DLL</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This section describes how to create a Charconv plug-in DLL. </p> <section><title>Introduction</title> <p>The flowchart below shows the steps to create a Charconv plug-in DLL. </p> <fig id="GUID-B145D4B6-8385-5DC9-8958-2350C86EBE2B"><image href="GUID-9F14FB98-D7CD-55C9-8D27-715642B8FFC3_d0e404850_href.png" placement="inline"/></fig> </section> <section><title>Procedure</title> <p>An example is used to explain the procedure for creating a Charconv plug-in DLL. This plug-in converts between the cp850 character set and Unicode. </p> <ol id="GUID-AC4B8539-C41C-5631-A8F7-8C9646951897"><li id="GUID-C75F84C2-C83A-567C-8AC6-788848EEE85E"><p>Create a cnvtool source file using a text editor and save it as, for example <filepath>d:\charconvfiles\data\cp850.txt</filepath>. This file contains pairs of hexadecimal numbers. The first number in each pair is the encoding of a character in cp850and the second is the Unicode encoding of the same character. </p> <codeblock id="GUID-9541977F-8BBA-5838-ACD1-DAB896C00D8C" xml:space="preserve">...
0x00    0x0000    #NULL
0x01    0x0001    #START OF HEADING
0x02    0x0002    #START OF TEXT
0x03    0x0003    #END OF TEXT
0x04    0x0004    #END OF TRANSMISSION
0x05    0x0005    #ENQUIRY
0x06    0x0006    #ACKNOWLEDGE
...</codeblock> <p>For more information about the syntax of a cnvtool source file, refer to <xref href="GUID-6796BA71-47A7-5465-89F2-BD0AEF2E4EE7.dita">Cnvtool Source File</xref>. </p> </li> <li id="GUID-62F3284F-1686-5869-A849-373A8092209F"><p>Create a cnvtool control file using a text editor and save it as, for example <filepath>d:\charconvfiles\data\cp850.ctl</filepath>. This file specifies the conversion algorithms to convert both ways between ranges of characters, and other information. </p> <codeblock id="GUID-EC3C3757-655C-5E7E-873A-0D2620FFE09E" xml:space="preserve">Endianness                                                            FixedBigEndian
ReplacementForUnconvertibleUnicodeCharacters                        0x1a # ASCII "substitute" character - must be a single character, and must be little-endian if the "Endianness" above is "Unspecified", otherwise in the same endianness as specified

StartForeignVariableByteData
#    FirstInitialByteValueInRange    LastInitialByteValueInRange        NumberOfSubsequentBytes
    0x00                            0xff                            0
EndForeignVariableByteData

StartForeignToUnicodeData
#    IncludePriority    SearchPriority    FirstInputCharacterCodeInRange    LastInputCharacterCodeInRange    Algorithm                        Parameters
    2                2                0x00                            0x7f                            Direct                            {}        # ASCII
    1                1                0x80                            0xff                            KeyedTable16OfIndexedTables16    {}        # CP850
EndForeignToUnicodeData

StartUnicodeToForeignData
#    IncludePriority    SearchPriority    FirstInputCharacterCodeInRange    LastInputCharacterCodeInRange    Algorithm            SizeOfOutputCharacterCodeInBytes    Parameters
    2                2                0x0000                            0x007f                            Direct                1                                    {}        # ASCII
    1                1                0x00A0                            0x25A0                            KeyedTable1616        1                                    {}        # CP850
EndUnicodeToForeignData
</codeblock> <p>For more information about the syntax of a cnvtool control file, refer to <xref href="GUID-2624060D-A5E7-590A-9FA0-471AE42A9BE9.dita">Cnvtool Control File</xref>. </p> </li> <li id="GUID-A15AE20D-57A2-5D66-80C6-6CC0CFE5A409"><p>Start a command prompt to run <filepath>cnvtool</filepath> on the source and control files as follows: </p> <p><userinput>cd d:\Symbian\epoc32\tools</userinput> </p> <p><userinput>cnvtool.bat -generateSourceCode d:\charconvfiles\data\cp850.txt d:\charconvfiles\data\cp850.ctl d:\charconvfiles\data\g_cp850.cpp</userinput> </p> <p>This process generates a C++ source code file called <filepath>g_cp850.cpp</filepath>. It is referred to as the <filepath>cnvtool</filepath> -generated cpp file. It contains the <codeph>SCnvConversionData</codeph> data structure. </p> <codeblock id="GUID-0E9F220F-F77C-54D7-A4F1-76672A16625B" xml:space="preserve">
#include &lt;e32std.h&gt;
#include &lt;CONVDATA.H&gt;
#include &lt;CONVGENERATEDCPP.H&gt;

#define ARRAY_LENGTH(aArray) (sizeof(aArray)/sizeof((aArray)[0]))


_LIT8(KLit8ReplacementForUnconvertibleUnicodeCharacters, "\x1a");

GLDEF_C const TDesC8&amp; ReplacementForUnconvertibleUnicodeCharacters_internal()
    {
    return KLit8ReplacementForUnconvertibleUnicodeCharacters;
    }

LOCAL_D const TUint16 keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1[]=
    {
    0x00c7,
    0x00fc,
...
 }


LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable16OfIndexedTables16::SKeyedEntry keyedTables16OfIndexedTables16_keyedEntries_foreignToUnicode_1[]=
    {
        {
        0x80,
        0xff,
        keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1
        }
    };

LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable1616::SEntry keyedTable1616_unicodeToForeign_1[]=
    {
        {
        0x00a0,
        0xff
        },
...
 }
LOCAL_D const SCnvConversionData::SVariableByteData::SRange foreignVariableByteDataRanges[]=
    {
        {
        0x00,
        0xff,
        0,
        0
        }
    };

....

GLDEF_D const SCnvConversionData conversionData=
    {
    SCnvConversionData::EFixedBigEndian,
        {
        ARRAY_LENGTH(foreignVariableByteDataRanges),
        foreignVariableByteDataRanges
        },
        {
        ARRAY_LENGTH(foreignToUnicodeDataRanges),
        foreignToUnicodeDataRanges
        },
        {
        ARRAY_LENGTH(unicodeToForeignDataRanges),
        unicodeToForeignDataRanges
        },
    NULL,
    NULL
    };

</codeblock> <p>For more information about the command syntax of cnvtool, refer to <xref href="GUID-214A7085-185B-5D40-A613-E82E68968AAB.dita">Cnvtool Command Syntax</xref>. </p> </li> <li id="GUID-03FF26E6-8AA2-5E31-A9A9-8A366FDBCD7F"><p>Create a cpp file which implements the <xref href="GUID-F58308AA-7072-370D-BE6A-1E8236060FC4.dita"><apiname>CCharacterSetConverterPluginInterface</apiname></xref> class. </p> <p>All of the functions defined in the interface must be implemented by the plug-in DLL. The implementations of <codeph>ConvertFromUnicode()</codeph> and <codeph>ConvertToUnicode()</codeph> must fulfil the following behavioural requirements: </p> <ul><li id="GUID-E6E2B609-A110-5607-8203-6E5C25C8B952"><p>They must return a negative error code (see <codeph>CCnvCharacterSetConverter::TError</codeph>), or the number of elements remaining in the input descriptor which have not been converted. </p> </li> <li id="GUID-2640AA42-5CA9-54B8-BCF8-40896D1BCA36"><p>They must not return an error when the output descriptor is too short or there is a truncated sequence at the end of the input descriptor. </p> <ul><li id="GUID-3A715936-4164-5493-A826-BB10448BD004"><p>If the output descriptor is full, the input descriptor cannot be fully converted. </p> </li> <li id="GUID-8D962732-8CAE-5D39-A2EA-FEA6D50E920E"><p>If the input descriptor ends with a truncated sequence, such as the first half of a Unicode surrogate pair, the first byte of a multi-byte foreign character set character code, or a truncated escape sequence of a modal foreign character set, it cannot be fully converted. </p> </li> </ul> </li> <li id="GUID-50C3341A-1319-5B57-A6B4-A527B48788E5"><p>If the input descriptor consists purely of a truncated sequence they must return <codeph>CCnvCharacterSetConverter::EErrorIllFormedInput</codeph>. </p> </li> </ul> <p>For non-complex character sets, they can call <codeph>CCnvCharacterSetConverter::DoConvertFromUnicode()</codeph> and <codeph>CCnvCharacterSetConverter::DoConvertToUnicode()</codeph> functions respectively. </p> <p>For complex character sets, for example JIS or Shift-JIS, the <xref href="GUID-2FC99DA0-F1C0-3A5E-B990-5DC3F7EAA31C.dita"><apiname>CnvUtilities</apiname></xref> class provides some utility functions. </p> <p>To access the two (const) global objects implemented in the cnvtool-generated cpp file, you must include the <filepath>convgeneratedcpp.h</filepath> header file. The <xref href="GUID-1A6BF3E3-31BF-3BC9-A010-26FF72F39F0B.dita"><apiname>SCnvConversionData</apiname></xref> object generated can then be used to implement the <codeph>ConvertFromUnicode()</codeph> and <codeph>ConvertToUnicode()</codeph> functions. </p> <p> <b>Example implementation</b>  </p> <codeblock id="GUID-E899A8AE-73D4-591D-B5A1-6777986D9361" xml:space="preserve">#include &lt;e32std.h&gt;
#include &lt;charconv.h&gt;
#include &lt;convgeneratedcpp.h&gt;
#include &lt;ecom/implementationproxy.h&gt;
#include &lt;charactersetconverter.h&gt;

class CCP850ConverterImpl : public CCharacterSetConverterPluginInterface
    {

public:
    virtual const TDesC8&amp; ReplacementForUnconvertibleUnicodeCharacters();

    virtual TInt ConvertFromUnicode(
        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 
        const TDesC8&amp; aReplacementForUnconvertibleUnicodeCharacters, 
        TDes8&amp; aForeign, 
        const TDesC16&amp; aUnicode, 
        CCnvCharacterSetConverter::TArrayOfAscendingIndices&amp; aIndicesOfUnconvertibleCharacters);

    virtual TInt ConvertToUnicode(
        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 
        TDes16&amp; aUnicode, 
        const TDesC8&amp; aForeign, 
        TInt&amp; aState, 
        TInt&amp; aNumberOfUnconvertibleCharacters, 
        TInt&amp; aIndexOfFirstByteOfFirstUnconvertibleCharacter);

    virtual TBool IsInThisCharacterSetL(
        TBool&amp; aSetToTrue, 
        TInt&amp; aConfidenceLevel, 
        const TDesC8&amp; aSample);

    static CCP850ConverterImpl* NewL();
    virtual ~CCP850ConverterImpl();

private:
    CCP850ConverterImpl();

    };


const TDesC8&amp; CCP850ConverterImpl::ReplacementForUnconvertibleUnicodeCharacters()
    {
    return ReplacementForUnconvertibleUnicodeCharacters_internal();
    }

TInt CCP850ConverterImpl::ConvertFromUnicode(
        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 
        const TDesC8&amp; aReplacementForUnconvertibleUnicodeCharacters, 
        TDes8&amp; aForeign, 
        const TDesC16&amp; aUnicode, 
        CCnvCharacterSetConverter::TArrayOfAscendingIndices&amp; aIndicesOfUnconvertibleCharacters)
    {
    return CCnvCharacterSetConverter::DoConvertFromUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aReplacementForUnconvertibleUnicodeCharacters, aForeign, aUnicode, aIndicesOfUnconvertibleCharacters);
    }

TInt CCP850ConverterImpl::ConvertToUnicode(
        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 
        TDes16&amp; aUnicode, 
        const TDesC8&amp; aForeign, 
        TInt&amp; /*aState*/, 
        TInt&amp; aNumberOfUnconvertibleCharacters, 
        TInt&amp; aIndexOfFirstByteOfFirstUnconvertibleCharacter)
    {
    return CCnvCharacterSetConverter::DoConvertToUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aUnicode, aForeign, aNumberOfUnconvertibleCharacters, aIndexOfFirstByteOfFirstUnconvertibleCharacter);
    }

TBool CCP850ConverterImpl::IsInThisCharacterSetL(
        TBool&amp; aSetToTrue, 
        TInt&amp; aConfidenceLevel, 
        const TDesC8&amp; /*aSample*/)
    {
    aSetToTrue=ETrue;
    aConfidenceLevel=0;
    return EFalse;
    }

CCP850ConverterImpl* CCP850ConverterImpl::NewL()
    {
    CCP850ConverterImpl* self = new(ELeave) CCP850ConverterImpl();
    return self;
    }

CCP850ConverterImpl::~CCP850ConverterImpl()
    {
    }

CCP850ConverterImpl::CCP850ConverterImpl()
    {
    }

const TImplementationProxy ImplementationTable[] = 
    {
        IMPLEMENTATION_PROXY_ENTRY(0x102825AD,    CCP850ConverterImpl::NewL)
    };

EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt&amp; aTableCount)
    {
    aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy);

    return ImplementationTable;
    } 
</codeblock> </li> <li id="GUID-D6584918-0542-5164-B339-658D52E041BF"><p>Create an ECom registry resource file using a text editor. </p> <p>102825ac.rss </p> <codeblock id="GUID-0652DC46-A32A-5730-A0B0-211C45A016B5" xml:space="preserve">#include "ecom/registryinfo.rh"

RESOURCE REGISTRY_INFO theInfo
    {
    dll_uid = 0x102825AC; // UID acquired from Symbian
    interfaces = 
        {
        INTERFACE_INFO
            {
            interface_uid = 0x101F7F1D; // fixed UID for Charconv plug-ins
            implementations = 
                {
                IMPLEMENTATION_INFO
                    {
                    implementation_uid = 0x102825AD; // UID acquired from Symbian
                    version_no = 1;
                    display_name = "CP850";
                    default_data = "CP850";
                    opaque_data = "";
                    }
                };
            }
        };
    }
</codeblock> </li> <li id="GUID-58F16B35-BB07-5C51-AE43-92E9D3D76FE8"><p>Create an mmp file which is used to build the plug-in DLL. </p> <codeblock id="GUID-AB46B407-D465-5AA1-BF7D-78FC11816A45" xml:space="preserve">TARGET            cp850.dll
TARGETTYPE        PLUGIN

CAPABILITY        All -Tcb

UID                0x10009D8D 0x102825AC
VENDORID        0x70000001

SYSTEMINCLUDE    /epoc32/include

SOURCEPATH        ../src/plugins
SOURCE            cp850.cpp

SOURCEPATH        /epoc32/build/generatedcpp/charconv
SOURCE            g_cp850.cpp

SOURCEPATH        ../resource
START RESOURCE    cp850.rss
TARGETPATH        /resource/charconv
LANG            sc
END

START RESOURCE    102825ac.rss
TARGET            cp850.rsc
END

LIBRARY            euser.lib
LIBRARY            charconv.lib
LIBRARY            ecom.lib
</codeblock> </li> </ol> <p>Build the plug-in DLL and install it into the <filepath>\system\charconv\</filepath> directory. The DLL is then available to be loaded when <codeph>CCnvCharacterSetConverter::PrepareToConvertToOrFromL()</codeph> is invoked. </p> </section> </conbody></concept>