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