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