The Tor Browser / file comparison
comparison: intl/icu/source/common/unicode/ucnv_cb.h
intl/icu/source/common/unicode/ucnv_cb.h
- branch
- TOR_BUG_3246
- changeset 4
- fc2d59ddac77
equal
deleted
inserted
replaced
| -1:000000000000 | 0:000f752760b0 |
|---|---|
| 1 /* | |
| 2 ********************************************************************** | |
| 3 * Copyright (C) 2000-2004, International Business Machines | |
| 4 * Corporation and others. All Rights Reserved. | |
| 5 ********************************************************************** | |
| 6 * ucnv_cb.h: | |
| 7 * External APIs for the ICU's codeset conversion library | |
| 8 * Helena Shih | |
| 9 * | |
| 10 * Modification History: | |
| 11 * | |
| 12 * Date Name Description | |
| 13 */ | |
| 14 | |
| 15 /** | |
| 16 * \file | |
| 17 * \brief C UConverter functions to aid the writers of callbacks | |
| 18 * | |
| 19 * <h2> Callback API for UConverter </h2> | |
| 20 * | |
| 21 * These functions are provided here for the convenience of the callback | |
| 22 * writer. If you are just looking for callback functions to use, please | |
| 23 * see ucnv_err.h. DO NOT call these functions directly when you are | |
| 24 * working with converters, unless your code has been called as a callback | |
| 25 * via ucnv_setFromUCallback or ucnv_setToUCallback !! | |
| 26 * | |
| 27 * A note about error codes and overflow. Unlike other ICU functions, | |
| 28 * these functions do not expect the error status to be U_ZERO_ERROR. | |
| 29 * Callbacks must be much more careful about their error codes. | |
| 30 * The error codes used here are in/out parameters, which should be passed | |
| 31 * back in the callback's error parameter. | |
| 32 * | |
| 33 * For example, if you call ucnv_cbfromUWriteBytes to write data out | |
| 34 * to the output codepage, it may return U_BUFFER_OVERFLOW_ERROR if | |
| 35 * the data did not fit in the target. But this isn't a failing error, | |
| 36 * in fact, ucnv_cbfromUWriteBytes may be called AGAIN with the error | |
| 37 * status still U_BUFFER_OVERFLOW_ERROR to attempt to write further bytes, | |
| 38 * which will also go into the internal overflow buffers. | |
| 39 * | |
| 40 * Concerning offsets, the 'offset' parameters here are relative to the start | |
| 41 * of SOURCE. For example, Suppose the string "ABCD" was being converted | |
| 42 * from Unicode into a codepage which doesn't have a mapping for 'B'. | |
| 43 * 'A' will be written out correctly, but | |
| 44 * The FromU Callback will be called on an unassigned character for 'B'. | |
| 45 * At this point, this is the state of the world: | |
| 46 * Target: A [..] [points after A] | |
| 47 * Source: A B [C] D [points to C - B has been consumed] | |
| 48 * 0 1 2 3 | |
| 49 * codePoint = "B" [the unassigned codepoint] | |
| 50 * | |
| 51 * Now, suppose a callback wants to write the substitution character '?' to | |
| 52 * the target. It calls ucnv_cbFromUWriteBytes() to write the ?. | |
| 53 * It should pass ZERO as the offset, because the offset as far as the | |
| 54 * callback is concerned is relative to the SOURCE pointer [which points | |
| 55 * before 'C'.] If the callback goes into the args and consumes 'C' also, | |
| 56 * it would call FromUWriteBytes with an offset of 1 (and advance the source | |
| 57 * pointer). | |
| 58 * | |
| 59 */ | |
| 60 | |
| 61 #ifndef UCNV_CB_H | |
| 62 #define UCNV_CB_H | |
| 63 | |
| 64 #include "unicode/utypes.h" | |
| 65 | |
| 66 #if !UCONFIG_NO_CONVERSION | |
| 67 | |
| 68 #include "unicode/ucnv.h" | |
| 69 #include "unicode/ucnv_err.h" | |
| 70 | |
| 71 /** | |
| 72 * ONLY used by FromU callback functions. | |
| 73 * Writes out the specified byte output bytes to the target byte buffer or to converter internal buffers. | |
| 74 * | |
| 75 * @param args callback fromUnicode arguments | |
| 76 * @param source source bytes to write | |
| 77 * @param length length of bytes to write | |
| 78 * @param offsetIndex the relative offset index from callback. | |
| 79 * @param err error status. If <TT>U_BUFFER_OVERFLOW</TT> is returned, then U_BUFFER_OVERFLOW <STRONG>must</STRONG> | |
| 80 * be returned to the user, because it means that not all data could be written into the target buffer, and some is | |
| 81 * in the converter error buffer. | |
| 82 * @see ucnv_cbFromUWriteSub | |
| 83 * @stable ICU 2.0 | |
| 84 */ | |
| 85 U_STABLE void U_EXPORT2 | |
| 86 ucnv_cbFromUWriteBytes (UConverterFromUnicodeArgs *args, | |
| 87 const char* source, | |
| 88 int32_t length, | |
| 89 int32_t offsetIndex, | |
| 90 UErrorCode * err); | |
| 91 | |
| 92 /** | |
| 93 * ONLY used by FromU callback functions. | |
| 94 * This function will write out the correct substitution character sequence | |
| 95 * to the target. | |
| 96 * | |
| 97 * @param args callback fromUnicode arguments | |
| 98 * @param offsetIndex the relative offset index from the current source pointer to be used | |
| 99 * @param err error status. If <TT>U_BUFFER_OVERFLOW</TT> is returned, then U_BUFFER_OVERFLOW <STRONG>must</STRONG> | |
| 100 * be returned to the user, because it means that not all data could be written into the target buffer, and some is | |
| 101 * in the converter error buffer. | |
| 102 * @see ucnv_cbFromUWriteBytes | |
| 103 * @stable ICU 2.0 | |
| 104 */ | |
| 105 U_STABLE void U_EXPORT2 | |
| 106 ucnv_cbFromUWriteSub (UConverterFromUnicodeArgs *args, | |
| 107 int32_t offsetIndex, | |
| 108 UErrorCode * err); | |
| 109 | |
| 110 /** | |
| 111 * ONLY used by fromU callback functions. | |
| 112 * This function will write out the error character(s) to the target UChar buffer. | |
| 113 * | |
| 114 * @param args callback fromUnicode arguments | |
| 115 * @param source pointer to pointer to first UChar to write [on exit: 1 after last UChar processed] | |
| 116 * @param sourceLimit pointer after last UChar to write | |
| 117 * @param offsetIndex the relative offset index from callback which will be set | |
| 118 * @param err error status <TT>U_BUFFER_OVERFLOW</TT> | |
| 119 * @see ucnv_cbToUWriteSub | |
| 120 * @stable ICU 2.0 | |
| 121 */ | |
| 122 U_STABLE void U_EXPORT2 ucnv_cbFromUWriteUChars(UConverterFromUnicodeArgs *args, | |
| 123 const UChar** source, | |
| 124 const UChar* sourceLimit, | |
| 125 int32_t offsetIndex, | |
| 126 UErrorCode * err); | |
| 127 | |
| 128 /** | |
| 129 * ONLY used by ToU callback functions. | |
| 130 * This function will write out the specified characters to the target | |
| 131 * UChar buffer. | |
| 132 * | |
| 133 * @param args callback toUnicode arguments | |
| 134 * @param source source string to write | |
| 135 * @param length the length of source string | |
| 136 * @param offsetIndex the relative offset index which will be written. | |
| 137 * @param err error status <TT>U_BUFFER_OVERFLOW</TT> | |
| 138 * @see ucnv_cbToUWriteSub | |
| 139 * @stable ICU 2.0 | |
| 140 */ | |
| 141 U_STABLE void U_EXPORT2 ucnv_cbToUWriteUChars (UConverterToUnicodeArgs *args, | |
| 142 const UChar* source, | |
| 143 int32_t length, | |
| 144 int32_t offsetIndex, | |
| 145 UErrorCode * err); | |
| 146 | |
| 147 /** | |
| 148 * ONLY used by ToU callback functions. | |
| 149 * This function will write out the Unicode substitution character (U+FFFD). | |
| 150 * | |
| 151 * @param args callback fromUnicode arguments | |
| 152 * @param offsetIndex the relative offset index from callback. | |
| 153 * @param err error status <TT>U_BUFFER_OVERFLOW</TT> | |
| 154 * @see ucnv_cbToUWriteUChars | |
| 155 * @stable ICU 2.0 | |
| 156 */ | |
| 157 U_STABLE void U_EXPORT2 ucnv_cbToUWriteSub (UConverterToUnicodeArgs *args, | |
| 158 int32_t offsetIndex, | |
| 159 UErrorCode * err); | |
| 160 #endif | |
| 161 | |
| 162 #endif |
