1<!DOCTYPE HTML PUBLIC "-//W3C//Dtd HTML 4.01 Transitional//EN">
2<html>
3<head>
4<meta http-equiv="Content-Type" content="text/html; charset=windows-1252" />
5<meta http-equiv="Content-Style-Type" content="text/css" />
6<link rel="stylesheet" type="text/css" href="../../CSS/revolution.css" />
7<title>ENCConvertString[Src]To[Dst]</title>
8</head>
9<body>
10
11<h1>ENCConvertString[Src]To[Dst]</h1>
12
13<h2>Syntax</h2>
14<dl><dd><pre class="construction">#include &lt;revolution/enc.h&gt;
15
16ENCResult ENCConvertStringAsciiToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
17ENCResult ENCConvertStringUnicodeToAscii(u8* dst, s32* dstlen, const u16* src, s32* srclen);
18
19ENCResult ENCConvertStringUtf32ToUtf16(u16* dst, s32* dstlen, const u32* src, s32* srclen);
20ENCResult ENCConvertStringUtf16ToUtf32(u32* dst, s32* dstlen, const u16* src, s32* srclen);
21ENCResult ENCConvertStringUtf16ToUtf8(u8* dst, s32* dstlen, const u16* src, s32* srclen);
22ENCResult ENCConvertStringUtf8ToUtf16(u16* dst, s32* dstlen, const u8* src, s32* srclen);
23
24ENCResult ENCConvertStringSjisToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
25ENCResult ENCConvertStringUnicodeToSjis(u8* dst, s32* dstlen, const u16* src, s32* srclen);
26ENCResult ENCConvertStringJisToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
27ENCResult ENCConvertStringUnicodeToJis(u8* dst, s32* dstlen, const u16* src, s32* srclen);
28
29ENCResult ENCConvertStringGb2312ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
30ENCResult ENCConvertStringUnicodeToGb2312(u8* dst, s32* dstlen, const u16* src, s32* srclen);
31
32ENCResult ENCConvertStringUhcToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
33ENCResult ENCConvertStringUnicodeToUhc(u8* dst, s32* dstlen, const u16* src, s32* srclen);
34
35ENCResult ENCConvertStringLatin1ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
36ENCResult ENCConvertStringUnicodeToLatin1(u8* dst, s32* dstlen, const u16* src, s32* srclen);
37ENCResult ENCConvertStringLatin2ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
38ENCResult ENCConvertStringUnicodeToLatin2(u8* dst, s32* dstlen, const u16* src, s32* srclen);
39ENCResult ENCConvertStringLatin3ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
40ENCResult ENCConvertStringUnicodeToLatin3(u8* dst, s32* dstlen, const u16* src, s32* srclen);
41ENCResult ENCConvertStringGreekToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
42ENCResult ENCConvertStringUnicodeToGreek(u8* dst, s32* dstlen, const u16* src, s32* srclen);
43ENCResult ENCConvertStringLatin6ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
44ENCResult ENCConvertStringUnicodeToLatin6(u8* dst, s32* dstlen, const u16* src, s32* srclen);
45ENCResult ENCConvertStringLatin9ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
46ENCResult ENCConvertStringUnicodeToLatin9(u8* dst, s32* dstlen, const u16* src, s32* srclen);
47
48ENCResult ENCConvertStringWin1252ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
49ENCResult ENCConvertStringUnicodeToWin1252(u8* dst, s32* dstlen, const u16* src, s32* srclen);
50</pre></dd></dl>
51
52<h2>Arguments</h2>
53<TABLE class="arguments" border="1" >
54    <tr>
55<th>dst</th>
56<td>Destination buffer of the converted string. Termination character will not be attached. If <SPAN class="argument">dst</SPAN> is <CODE>NULL</CODE>, the string will not be written.</td>
57    </tr>
58    <tr>
59<th>dstlen</th>
60<td>The size of the converted string destination buffer. This is the size (buffer size/type size) of the type-conversion string in <SPAN class="argument">*dst</SPAN>.<br> After conversion, the size written to the buffer will be stored.<br>When <SPAN class="argument">dst</SPAN> is <CODE>NULL</CODE>, the destination buffer size will be ignored, and the buffer size necessary for writing the converted string will be stored.</td>
61    </tr>
62    <tr>
63<th>src</th>
64<td>The source string buffer.</td>
65    </tr>
66    <tr>
67<th>srclen</th>
68<td>The source string buffer size. This is the size (buffer size/type size) of the type-conversion string in <SPAN class="argument">*src</SPAN>. A string larger than specified by <SPAN class="argument">srclen</SPAN> will not be read.<br>If <SPAN class="argument">srclen</SPAN> is <CODE>NULL</CODE> or a negative value, <SPAN class="argument">src</SPAN> will be loaded until the termination character is found.<br>If <SPAN class="argument">srclen</SPAN> is not <CODE>NULL</CODE>, the size of the loaded string buffer will be stored here.</td>
69    </tr>
70</table>
71
72<h2>Return Values</h2>
73<p>
74<code>ENC_OK</code>: Normal exit.<br><code>ENC_ERR_NO_BUF_LEFT</code>: Write destination buffer size insufficient.<br><code>ENC_ERR_NO_MAP_RULE</code>: Unconvertable characters detected.<br><code>ENC_ERR_INVALID_PARAM</code>: Invalid argument.<br><code>ENC_ERR_INVALID_FORMAT</code>: Detected characters outside of the prescribed set for the input character code.<br>
75</p>
76
77<h2>Description</h2>
78<p>
79Converts the encoding of a given string from [Src] to [Dst] and then obtains the size of the buffer where the converted string was written.<br>A termination character does not get attached.
80</p>
81<p>If the destination buffer is not specified, the buffer size necessary for the write operation will be obtained.<br>If a character that cannot be converted is detected, <code>ENC_ERR_NO_MAP_RULE</code> is returned and the conversion process ends.<br>
82<p><font color="ff0000">The size (buffer size/type size) of the type-conversion strings <SPAN class="argument">*dst</SPAN> and <SPAN class="argument">*src</SPAN> is stored in <SPAN class="argument">dstlen</SPAN> and <SPAN class="argument">srclen</SPAN>, respectively.</font>For example, UTF-8 is of type <CODE>u8</CODE> and therefore uses single-byte units. Unicode is of type <CODE>u16</CODE> and therefore uses double-byte units.</p>
83<p>Function names take the following format:</p>
84<p><CODE>ENCConvertString[Src]To[Dst]</CODE></p>
85<p> </p>
86<p>
87The relationship between the abbreviations ([Src] and [Dst]) used in function names and the supported character encodings is as follows.<br>Refer to the <a href="../intro.html">ENC API Introduction</a> for details on conversion rules for each of the character encodings.
88</p>
89<table border="1" cellpadding="3" cellspacing="0">
90  <tbody>
91    <tr>
92<td bgcolor="#C0C0C0">Abbreviation used in the function name</td>
93<td bgcolor="#C0C0C0">Supported character encoding</td>
94    </tr>
95    <tr>
96      <td>Ascii</td>
97      <td>US-ASCII</td>
98    </tr>
99    <tr>
100      <td>Unicode</td>
101      <td>UTF-16BE</td>
102    </tr>
103    <tr>
104      <td>Utf32</td>
105      <td>UTF-32BE</td>
106    </tr>
107    <tr>
108      <td>Utf16</td>
109      <td>UTF-16BE, UTF-16LE (input only)</td>
110    </tr>
111    <tr>
112      <td>Utf8</td>
113      <td>UTF-8</td>
114    </tr>
115    <tr>
116      <td>Sjis</td>
117      <td>Shift_JIS</td>
118    </tr>
119    <tr>
120      <td>Jis</td>
121      <td>ISO-2022-JP</td>
122    </tr>
123    <tr>
124      <td>Gb2312</td>
125      <td>GB2312</td>
126    </tr>
127    <tr>
128      <td>Uhc</td>
129      <td>UHC</td>
130    </tr>
131    <tr>
132      <td>Latin1</td>
133      <td>ISO-8859-1</td>
134    </tr>
135    <tr>
136      <td>Latin2</td>
137      <td>ISO-8859-2</td>
138    </tr>
139    <tr>
140      <td>Latin3</td>
141      <td>ISO-8859-3</td>
142    </tr>
143    <tr>
144      <td>Greek</td>
145      <td>ISO-8859-7</td>
146    </tr>
147    <tr>
148      <td>Latin6</td>
149      <td>ISO-8859-10</td>
150    </tr>
151    <tr>
152      <td>Latin9</td>
153      <td>ISO-8859-15</td>
154    </tr>
155    <tr>
156      <td>Win1252</td>
157      <td>windows-1252</td>
158    </tr>
159  </tbody>
160</table>
161<p><b><code>ENC_ERR_NOT_LOADED</code> was eliminated in RevolutionSDK 3.2.</b><br>If you specify conversion to a character code whose conversion table has been stripped, this function will return <code>ENC_ERR_NO_MAP_RULE</code>.</p>
162<h2>See Also</h2>
163<p>
164<a href="../intro.html">ENC API Introduction</a>
165</p>
166
167<h2>Revision History</h2>
168<p>
1692008/07/08 Revised the description of the buffer size. Added a description of the supported character encodings.<br>2008/03/31 Eliminated <code>ENC_ERR_NOT_LOADED</code>.<br>2008/02/21 Added character codes for Korean and Chinese.<br>2007/11/21 Corrected an error in argument types.<br>2007/05/24 Added previously omitted functions.<br>2007/03/02 Corrected errors.<br>2007/02/05 Added <CODE>ENC_ERR_NOT_LOADED</CODE>.<br>2006/12/25 Added supported character encodings.<br>2006/10/19 Added supported character encodings.<br>2006/08/08 Initial version.<br>
170</p>
171
172<hr><p>CONFIDENTIAL</p></body>
173</html>