<?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_d0e378239_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 <e32std.h>

#include <CONVDATA.H>

#include <CONVGENERATEDCPP.H>

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

_LIT8(KLit8ReplacementForUnconvertibleUnicodeCharacters, "\x1a");

GLDEF_C const TDesC8& 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 <charconv.h>

#include <convgeneratedcpp.h>

#include <ecom/implementationproxy.h>

#include <charactersetconverter.h>

class CCP850ConverterImpl : public CCharacterSetConverterPluginInterface

    {

public:

    virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters();

    virtual TInt ConvertFromUnicode(

        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

        const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, 

        TDes8& aForeign, 

        const TDesC16& aUnicode, 

        CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters);

    virtual TInt ConvertToUnicode(

        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

        TDes16& aUnicode, 

        const TDesC8& aForeign, 

        TInt& aState, 

        TInt& aNumberOfUnconvertibleCharacters, 

        TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter);

    virtual TBool IsInThisCharacterSetL(

        TBool& aSetToTrue, 

        TInt& aConfidenceLevel, 

        const TDesC8& aSample);

    static CCP850ConverterImpl* NewL();

    virtual ~CCP850ConverterImpl();

private:

    CCP850ConverterImpl();

    };

const TDesC8& CCP850ConverterImpl::ReplacementForUnconvertibleUnicodeCharacters()

    {

    return ReplacementForUnconvertibleUnicodeCharacters_internal();

    }

TInt CCP850ConverterImpl::ConvertFromUnicode(

        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

        const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, 

        TDes8& aForeign, 

        const TDesC16& aUnicode, 

        CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters)

    {

    return CCnvCharacterSetConverter::DoConvertFromUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aReplacementForUnconvertibleUnicodeCharacters, aForeign, aUnicode, aIndicesOfUnconvertibleCharacters);

    }

TInt CCP850ConverterImpl::ConvertToUnicode(

        CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

        TDes16& aUnicode, 

        const TDesC8& aForeign, 

        TInt& /*aState*/, 

        TInt& aNumberOfUnconvertibleCharacters, 

        TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter)

    {

    return CCnvCharacterSetConverter::DoConvertToUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aUnicode, aForeign, aNumberOfUnconvertibleCharacters, aIndexOfFirstByteOfFirstUnconvertibleCharacter);

    }

TBool CCP850ConverterImpl::IsInThisCharacterSetL(

        TBool& aSetToTrue, 

        TInt& aConfidenceLevel, 

        const TDesC8& /*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& 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>