Creating 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 + + + + + +
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.
\ No newline at end of file