<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>ICU 3.6: ucnv_cb.h File Reference</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.4.7 -->
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="classes.html"><span>Data Structures</span></a></li>
<li id="current"><a href="files.html"><span>Files</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li>
<form action="search.php" method="get">
<table cellspacing="0" cellpadding="0" border="0">
<tr>
<td><label> <u>S</u>earch for </label></td>
<td><input type="text" name="query" value="" size="20" accesskey="s"/></td>
</tr>
</table>
</form>
</li>
</ul></div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
<li><a href="globals.html"><span>Globals</span></a></li>
</ul></div>
<h1>ucnv_cb.h File Reference</h1>C UConverter functions to aid the writers of callbacks. <a href="#_details">More...</a>
<p>
<code>#include "<a class="el" href="utypes_8h-source.html">unicode/utypes.h</a>"</code><br>
<code>#include "<a class="el" href="ucnv_8h-source.html">unicode/ucnv.h</a>"</code><br>
<code>#include "<a class="el" href="ucnv__err_8h-source.html">unicode/ucnv_err.h</a>"</code><br>
<p>
<a href="ucnv__cb_8h-source.html">Go to the source code of this file.</a><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="ucnv__cb_8h.html#a02f41f05b757285f7acdb8a275efa93">ucnv_cbFromUWriteBytes</a> (<a class="el" href="structUConverterFromUnicodeArgs.html">UConverterFromUnicodeArgs</a> *<a class="el" href="structUConverterToUnicodeArgs.html">args</a>, const char *source, <a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> <a class="el" href="ucnv_8h.html#885b7a4b123891f24dedd11fb6b2e641">length</a>, <a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> offsetIndex, <a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> *err)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">ONLY used by FromU callback functions. <a href="#a02f41f05b757285f7acdb8a275efa93"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="ucnv__cb_8h.html#796ecba1e90e4531d7f11d6e8bed1a86">ucnv_cbFromUWriteSub</a> (<a class="el" href="structUConverterFromUnicodeArgs.html">UConverterFromUnicodeArgs</a> *<a class="el" href="structUConverterToUnicodeArgs.html">args</a>, <a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> offsetIndex, <a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> *err)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">ONLY used by FromU callback functions. <a href="#796ecba1e90e4531d7f11d6e8bed1a86"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="ucnv__cb_8h.html#57a8e1d06682a4b9ec7ac1cf74f203c8">ucnv_cbFromUWriteUChars</a> (<a class="el" href="structUConverterFromUnicodeArgs.html">UConverterFromUnicodeArgs</a> *<a class="el" href="structUConverterToUnicodeArgs.html">args</a>, const UChar **source, const UChar *sourceLimit, <a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> offsetIndex, <a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> *err)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">ONLY used by fromU callback functions. <a href="#57a8e1d06682a4b9ec7ac1cf74f203c8"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="ucnv__cb_8h.html#2f6498f138a961668709054b97a54c84">ucnv_cbToUWriteUChars</a> (<a class="el" href="structUConverterToUnicodeArgs.html">UConverterToUnicodeArgs</a> *<a class="el" href="structUConverterToUnicodeArgs.html">args</a>, const UChar *source, <a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> <a class="el" href="ucnv_8h.html#885b7a4b123891f24dedd11fb6b2e641">length</a>, <a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> offsetIndex, <a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> *err)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">ONLY used by ToU callback functions. <a href="#2f6498f138a961668709054b97a54c84"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="ucnv__cb_8h.html#58facd4f9bfd65c27963c86fe58aa320">ucnv_cbToUWriteSub</a> (<a class="el" href="structUConverterToUnicodeArgs.html">UConverterToUnicodeArgs</a> *<a class="el" href="structUConverterToUnicodeArgs.html">args</a>, <a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> offsetIndex, <a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> *err)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">ONLY used by ToU callback functions. <a href="#58facd4f9bfd65c27963c86fe58aa320"></a><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
C UConverter functions to aid the writers of callbacks.
<p>
<h2>Callback API for UConverter </h2>
<p>
These functions are provided here for the convenience of the callback writer. If you are just looking for callback functions to use, please see <a class="el" href="ucnv__err_8h.html">ucnv_err.h</a>. DO NOT call these functions directly when you are working with converters, unless your code has been called as a callback via ucnv_setFromUCallback or ucnv_setToUCallback !!<p>
A note about error codes and overflow. Unlike other ICU functions, these functions do not expect the error status to be U_ZERO_ERROR. Callbacks must be much more careful about their error codes. The error codes used here are in/out parameters, which should be passed back in the callback's error parameter.<p>
For example, if you call ucnv_cbfromUWriteBytes to write data out to the output codepage, it may return U_BUFFER_OVERFLOW_ERROR if the data did not fit in the target. But this isn't a failing error, in fact, ucnv_cbfromUWriteBytes may be called AGAIN with the error status still U_BUFFER_OVERFLOW_ERROR to attempt to write further bytes, which will also go into the internal overflow buffers.<p>
Concerning offsets, the 'offset' parameters here are relative to the start of SOURCE. For example, Suppose the string "ABCD" was being converted from Unicode into a codepage which doesn't have a mapping for 'B'. 'A' will be written out correctly, but The FromU Callback will be called on an unassigned character for 'B'. At this point, this is the state of the world: Target: A [..] [points after A] Source: A B [C] D [points to C - B has been consumed] 0 1 2 3 codePoint = "B" [the unassigned codepoint]<p>
Now, suppose a callback wants to write the substitution character '?' to the target. It calls <a class="el" href="ucnv__cb_8h.html#a02f41f05b757285f7acdb8a275efa93">ucnv_cbFromUWriteBytes()</a> to write the ?. It should pass ZERO as the offset, because the offset as far as the callback is concerned is relative to the SOURCE pointer [which points before 'C'.] If the callback goes into the args and consumes 'C' also, it would call FromUWriteBytes with an offset of 1 (and advance the source pointer).
<p>
Definition in file <a class="el" href="ucnv__cb_8h-source.html">ucnv_cb.h</a>.<hr><h2>Function Documentation</h2>
<a class="anchor" name="a02f41f05b757285f7acdb8a275efa93"></a><!-- doxytag: member="ucnv_cb.h::ucnv_cbFromUWriteBytes" ref="a02f41f05b757285f7acdb8a275efa93" args="(UConverterFromUnicodeArgs *args, const char *source, int32_t length, int32_t offsetIndex, UErrorCode *err)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ucnv_cbFromUWriteBytes </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUConverterFromUnicodeArgs.html">UConverterFromUnicodeArgs</a> * </td>
<td class="paramname"> <em>args</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>source</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> </td>
<td class="paramname"> <em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> </td>
<td class="paramname"> <em>offsetIndex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> * </td>
<td class="paramname"> <em>err</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
ONLY used by FromU callback functions.
<p>
Writes out the specified byte output bytes to the target byte buffer or to converter internal buffers.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>args</em> </td><td>callback fromUnicode arguments </td></tr>
<tr><td valign="top"></td><td valign="top"><em>source</em> </td><td>source bytes to write </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>length of bytes to write </td></tr>
<tr><td valign="top"></td><td valign="top"><em>offsetIndex</em> </td><td>the relative offset index from callback. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>err</em> </td><td>error status. If <code>U_BUFFER_OVERFLOW</code> is returned, then U_BUFFER_OVERFLOW <b>must</b> be returned to the user, because it means that not all data could be written into the target buffer, and some is in the converter error buffer. </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="ucnv__cb_8h.html#796ecba1e90e4531d7f11d6e8bed1a86">ucnv_cbFromUWriteSub</a> </dd></dl>
<dl compact><dt><b><a class="el" href="stable.html#_stable000917">Stable:</a></b></dt><dd>ICU 2.0 </dd></dl>
</div>
</div><p>
<a class="anchor" name="796ecba1e90e4531d7f11d6e8bed1a86"></a><!-- doxytag: member="ucnv_cb.h::ucnv_cbFromUWriteSub" ref="796ecba1e90e4531d7f11d6e8bed1a86" args="(UConverterFromUnicodeArgs *args, int32_t offsetIndex, UErrorCode *err)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ucnv_cbFromUWriteSub </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUConverterFromUnicodeArgs.html">UConverterFromUnicodeArgs</a> * </td>
<td class="paramname"> <em>args</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> </td>
<td class="paramname"> <em>offsetIndex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> * </td>
<td class="paramname"> <em>err</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
ONLY used by FromU callback functions.
<p>
This function will write out the correct substitution character sequence to the target.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>args</em> </td><td>callback fromUnicode arguments </td></tr>
<tr><td valign="top"></td><td valign="top"><em>offsetIndex</em> </td><td>the relative offset index from the current source pointer to be used </td></tr>
<tr><td valign="top"></td><td valign="top"><em>err</em> </td><td>error status. If <code>U_BUFFER_OVERFLOW</code> is returned, then U_BUFFER_OVERFLOW <b>must</b> be returned to the user, because it means that not all data could be written into the target buffer, and some is in the converter error buffer. </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="ucnv__cb_8h.html#a02f41f05b757285f7acdb8a275efa93">ucnv_cbFromUWriteBytes</a> </dd></dl>
<dl compact><dt><b><a class="el" href="stable.html#_stable000918">Stable:</a></b></dt><dd>ICU 2.0 </dd></dl>
</div>
</div><p>
<a class="anchor" name="57a8e1d06682a4b9ec7ac1cf74f203c8"></a><!-- doxytag: member="ucnv_cb.h::ucnv_cbFromUWriteUChars" ref="57a8e1d06682a4b9ec7ac1cf74f203c8" args="(UConverterFromUnicodeArgs *args, const UChar **source, const UChar *sourceLimit, int32_t offsetIndex, UErrorCode *err)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ucnv_cbFromUWriteUChars </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUConverterFromUnicodeArgs.html">UConverterFromUnicodeArgs</a> * </td>
<td class="paramname"> <em>args</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const UChar ** </td>
<td class="paramname"> <em>source</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const UChar * </td>
<td class="paramname"> <em>sourceLimit</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> </td>
<td class="paramname"> <em>offsetIndex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> * </td>
<td class="paramname"> <em>err</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
ONLY used by fromU callback functions.
<p>
This function will write out the error character(s) to the target UChar buffer.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>args</em> </td><td>callback fromUnicode arguments </td></tr>
<tr><td valign="top"></td><td valign="top"><em>source</em> </td><td>pointer to pointer to first UChar to write [on exit: 1 after last UChar processed] </td></tr>
<tr><td valign="top"></td><td valign="top"><em>sourceLimit</em> </td><td>pointer after last UChar to write </td></tr>
<tr><td valign="top"></td><td valign="top"><em>offsetIndex</em> </td><td>the relative offset index from callback which will be set </td></tr>
<tr><td valign="top"></td><td valign="top"><em>err</em> </td><td>error status <code>U_BUFFER_OVERFLOW</code> </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="ucnv__cb_8h.html#58facd4f9bfd65c27963c86fe58aa320">ucnv_cbToUWriteSub</a> </dd></dl>
<dl compact><dt><b><a class="el" href="stable.html#_stable000919">Stable:</a></b></dt><dd>ICU 2.0 </dd></dl>
</div>
</div><p>
<a class="anchor" name="58facd4f9bfd65c27963c86fe58aa320"></a><!-- doxytag: member="ucnv_cb.h::ucnv_cbToUWriteSub" ref="58facd4f9bfd65c27963c86fe58aa320" args="(UConverterToUnicodeArgs *args, int32_t offsetIndex, UErrorCode *err)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ucnv_cbToUWriteSub </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUConverterToUnicodeArgs.html">UConverterToUnicodeArgs</a> * </td>
<td class="paramname"> <em>args</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> </td>
<td class="paramname"> <em>offsetIndex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> * </td>
<td class="paramname"> <em>err</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
ONLY used by ToU callback functions.
<p>
This function will write out the Unicode substitution character (U+FFFD).<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>args</em> </td><td>callback fromUnicode arguments </td></tr>
<tr><td valign="top"></td><td valign="top"><em>offsetIndex</em> </td><td>the relative offset index from callback. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>err</em> </td><td>error status <code>U_BUFFER_OVERFLOW</code> </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="ucnv__cb_8h.html#2f6498f138a961668709054b97a54c84">ucnv_cbToUWriteUChars</a> </dd></dl>
<dl compact><dt><b><a class="el" href="stable.html#_stable000921">Stable:</a></b></dt><dd>ICU 2.0 </dd></dl>
</div>
</div><p>
<a class="anchor" name="2f6498f138a961668709054b97a54c84"></a><!-- doxytag: member="ucnv_cb.h::ucnv_cbToUWriteUChars" ref="2f6498f138a961668709054b97a54c84" args="(UConverterToUnicodeArgs *args, const UChar *source, int32_t length, int32_t offsetIndex, UErrorCode *err)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ucnv_cbToUWriteUChars </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUConverterToUnicodeArgs.html">UConverterToUnicodeArgs</a> * </td>
<td class="paramname"> <em>args</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const UChar * </td>
<td class="paramname"> <em>source</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> </td>
<td class="paramname"> <em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="pwin32_8h.html#f03f47ee300d26bee7dd521b1169f394">int32_t</a> </td>
<td class="paramname"> <em>offsetIndex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#863c11989634c998849cc946d04dfabe">UErrorCode</a> * </td>
<td class="paramname"> <em>err</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
ONLY used by ToU callback functions.
<p>
This function will write out the specified characters to the target UChar buffer.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>args</em> </td><td>callback toUnicode arguments </td></tr>
<tr><td valign="top"></td><td valign="top"><em>source</em> </td><td>source string to write </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>the length of source string </td></tr>
<tr><td valign="top"></td><td valign="top"><em>offsetIndex</em> </td><td>the relative offset index which will be written. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>err</em> </td><td>error status <code>U_BUFFER_OVERFLOW</code> </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="ucnv__cb_8h.html#58facd4f9bfd65c27963c86fe58aa320">ucnv_cbToUWriteSub</a> </dd></dl>
<dl compact><dt><b><a class="el" href="stable.html#_stable000920">Stable:</a></b></dt><dd>ICU 2.0 </dd></dl>
</div>
</div><p>
<hr size="1"><address style="align: right;"><small>Generated on Tue Dec 13 17:29:52 2011 for ICU 3.6 by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.7 </small></address>
</body>
</html>
