Collapse all Symbian^3 Application Developer Library

Creating a Charconv Plug-in DLL

This section describes how to create a Charconv plug-in DLL.

Introduction

The flowchart below shows the steps to create a Charconv plug-in DLL.

Procedure

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.

Create a cnvtool source file using a text editor and save it as, for example d:\charconvfiles\data\cp850.txt . 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.
```
         
          
         
         ...
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
...
        
```
For more information about the syntax of a cnvtool source file, refer to Cnvtool Source File .

Create a cnvtool control file using a text editor and save it as, for example d:\charconvfiles\data\cp850.ctl . This file specifies the conversion algorithms to convert both ways between ranges of characters, and other information.

         
          
         
         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

For more information about the syntax of a cnvtool control file, refer to Cnvtool Control File .

Start a command prompt to run cnvtool on the source and control files as follows:

cd d:\Symbian\epoc32\tools

cnvtool.bat -generateSourceCode d:\charconvfiles\data\cp850.txt d:\charconvfiles\data\cp850.ctl d:\charconvfiles\data\g_cp850.cpp

This process generates a C++ source code file called g_cp850.cpp . It is referred to as the cnvtool -generated cpp file. It contains the SCnvConversionData data structure.

         
          
         
         #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
    };

For more information about the command syntax of cnvtool, refer to Cnvtool Command Syntax .

Create a cpp file which implements the CCharacterSetConverterPluginInterface class.

All of the functions defined in the interface must be implemented by the plug-in DLL. The implementations of ConvertFromUnicode() and ConvertToUnicode() must fulfil the following behavioural requirements:

They must return a negative error code (see CCnvCharacterSetConverter::TError ), or the number of elements remaining in the input descriptor which have not been converted.
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.
- If the output descriptor is full, the input descriptor cannot be fully converted.
- 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.
If the input descriptor consists purely of a truncated sequence they must return CCnvCharacterSetConverter::EErrorIllFormedInput .

For non-complex character sets, they can call CCnvCharacterSetConverter::DoConvertFromUnicode() and CCnvCharacterSetConverter::DoConvertToUnicode() functions respectively.

For complex character sets, for example JIS or Shift-JIS, the CnvUtilities class provides some utility functions.

To access the two (const) global objects implemented in the cnvtool-generated cpp file, you must include the convgeneratedcpp.h header file. The SCnvConversionData object generated can then be used to implement the ConvertFromUnicode() and ConvertToUnicode() functions.

Example implementation

         
          
         
         #include <e32std.h>
#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;
    }

Create an ECom registry resource file using a text editor.

102825ac.rss

         
          
         
         #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 = "";
                    }
                };
            }
        };
    }

Create an mmp file which is used to build the plug-in DLL.

         
          
         
         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

Build the plug-in DLL and install it into the \system\charconv\ directory. The DLL is then available to be loaded when CCnvCharacterSetConverter::PrepareToConvertToOrFromL() is invoked.

Parent topic: Character Encoding and Conversion Framework Tutorials