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 163