--- a/Symbian3/SDK/Source/GUID-E8EF06D7-FB4E-598D-9D9D-4395AB6F51C8.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-E8EF06D7-FB4E-598D-9D9D-4395AB6F51C8.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,265 +1,265 @@
-<?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_d0e405012_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 <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;
- }
-</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
+<?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 <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 <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;
+ }
+</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>
\ No newline at end of file