1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/ucnv_cb.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,162 @@
1.4 +/*
1.5 +**********************************************************************
1.6 +* Copyright (C) 2000-2004, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +**********************************************************************
1.9 + * ucnv_cb.h:
1.10 + * External APIs for the ICU's codeset conversion library
1.11 + * Helena Shih
1.12 + *
1.13 + * Modification History:
1.14 + *
1.15 + * Date Name Description
1.16 + */
1.17 +
1.18 +/**
1.19 + * \file
1.20 + * \brief C UConverter functions to aid the writers of callbacks
1.21 + *
1.22 + * <h2> Callback API for UConverter </h2>
1.23 + *
1.24 + * These functions are provided here for the convenience of the callback
1.25 + * writer. If you are just looking for callback functions to use, please
1.26 + * see ucnv_err.h. DO NOT call these functions directly when you are
1.27 + * working with converters, unless your code has been called as a callback
1.28 + * via ucnv_setFromUCallback or ucnv_setToUCallback !!
1.29 + *
1.30 + * A note about error codes and overflow. Unlike other ICU functions,
1.31 + * these functions do not expect the error status to be U_ZERO_ERROR.
1.32 + * Callbacks must be much more careful about their error codes.
1.33 + * The error codes used here are in/out parameters, which should be passed
1.34 + * back in the callback's error parameter.
1.35 + *
1.36 + * For example, if you call ucnv_cbfromUWriteBytes to write data out
1.37 + * to the output codepage, it may return U_BUFFER_OVERFLOW_ERROR if
1.38 + * the data did not fit in the target. But this isn't a failing error,
1.39 + * in fact, ucnv_cbfromUWriteBytes may be called AGAIN with the error
1.40 + * status still U_BUFFER_OVERFLOW_ERROR to attempt to write further bytes,
1.41 + * which will also go into the internal overflow buffers.
1.42 + *
1.43 + * Concerning offsets, the 'offset' parameters here are relative to the start
1.44 + * of SOURCE. For example, Suppose the string "ABCD" was being converted
1.45 + * from Unicode into a codepage which doesn't have a mapping for 'B'.
1.46 + * 'A' will be written out correctly, but
1.47 + * The FromU Callback will be called on an unassigned character for 'B'.
1.48 + * At this point, this is the state of the world:
1.49 + * Target: A [..] [points after A]
1.50 + * Source: A B [C] D [points to C - B has been consumed]
1.51 + * 0 1 2 3
1.52 + * codePoint = "B" [the unassigned codepoint]
1.53 + *
1.54 + * Now, suppose a callback wants to write the substitution character '?' to
1.55 + * the target. It calls ucnv_cbFromUWriteBytes() to write the ?.
1.56 + * It should pass ZERO as the offset, because the offset as far as the
1.57 + * callback is concerned is relative to the SOURCE pointer [which points
1.58 + * before 'C'.] If the callback goes into the args and consumes 'C' also,
1.59 + * it would call FromUWriteBytes with an offset of 1 (and advance the source
1.60 + * pointer).
1.61 + *
1.62 + */
1.63 +
1.64 +#ifndef UCNV_CB_H
1.65 +#define UCNV_CB_H
1.66 +
1.67 +#include "unicode/utypes.h"
1.68 +
1.69 +#if !UCONFIG_NO_CONVERSION
1.70 +
1.71 +#include "unicode/ucnv.h"
1.72 +#include "unicode/ucnv_err.h"
1.73 +
1.74 +/**
1.75 + * ONLY used by FromU callback functions.
1.76 + * Writes out the specified byte output bytes to the target byte buffer or to converter internal buffers.
1.77 + *
1.78 + * @param args callback fromUnicode arguments
1.79 + * @param source source bytes to write
1.80 + * @param length length of bytes to write
1.81 + * @param offsetIndex the relative offset index from callback.
1.82 + * @param err error status. If <TT>U_BUFFER_OVERFLOW</TT> is returned, then U_BUFFER_OVERFLOW <STRONG>must</STRONG>
1.83 + * be returned to the user, because it means that not all data could be written into the target buffer, and some is
1.84 + * in the converter error buffer.
1.85 + * @see ucnv_cbFromUWriteSub
1.86 + * @stable ICU 2.0
1.87 + */
1.88 +U_STABLE void U_EXPORT2
1.89 +ucnv_cbFromUWriteBytes (UConverterFromUnicodeArgs *args,
1.90 + const char* source,
1.91 + int32_t length,
1.92 + int32_t offsetIndex,
1.93 + UErrorCode * err);
1.94 +
1.95 +/**
1.96 + * ONLY used by FromU callback functions.
1.97 + * This function will write out the correct substitution character sequence
1.98 + * to the target.
1.99 + *
1.100 + * @param args callback fromUnicode arguments
1.101 + * @param offsetIndex the relative offset index from the current source pointer to be used
1.102 + * @param err error status. If <TT>U_BUFFER_OVERFLOW</TT> is returned, then U_BUFFER_OVERFLOW <STRONG>must</STRONG>
1.103 + * be returned to the user, because it means that not all data could be written into the target buffer, and some is
1.104 + * in the converter error buffer.
1.105 + * @see ucnv_cbFromUWriteBytes
1.106 + * @stable ICU 2.0
1.107 + */
1.108 +U_STABLE void U_EXPORT2
1.109 +ucnv_cbFromUWriteSub (UConverterFromUnicodeArgs *args,
1.110 + int32_t offsetIndex,
1.111 + UErrorCode * err);
1.112 +
1.113 +/**
1.114 + * ONLY used by fromU callback functions.
1.115 + * This function will write out the error character(s) to the target UChar buffer.
1.116 + *
1.117 + * @param args callback fromUnicode arguments
1.118 + * @param source pointer to pointer to first UChar to write [on exit: 1 after last UChar processed]
1.119 + * @param sourceLimit pointer after last UChar to write
1.120 + * @param offsetIndex the relative offset index from callback which will be set
1.121 + * @param err error status <TT>U_BUFFER_OVERFLOW</TT>
1.122 + * @see ucnv_cbToUWriteSub
1.123 + * @stable ICU 2.0
1.124 + */
1.125 +U_STABLE void U_EXPORT2 ucnv_cbFromUWriteUChars(UConverterFromUnicodeArgs *args,
1.126 + const UChar** source,
1.127 + const UChar* sourceLimit,
1.128 + int32_t offsetIndex,
1.129 + UErrorCode * err);
1.130 +
1.131 +/**
1.132 + * ONLY used by ToU callback functions.
1.133 + * This function will write out the specified characters to the target
1.134 + * UChar buffer.
1.135 + *
1.136 + * @param args callback toUnicode arguments
1.137 + * @param source source string to write
1.138 + * @param length the length of source string
1.139 + * @param offsetIndex the relative offset index which will be written.
1.140 + * @param err error status <TT>U_BUFFER_OVERFLOW</TT>
1.141 + * @see ucnv_cbToUWriteSub
1.142 + * @stable ICU 2.0
1.143 + */
1.144 +U_STABLE void U_EXPORT2 ucnv_cbToUWriteUChars (UConverterToUnicodeArgs *args,
1.145 + const UChar* source,
1.146 + int32_t length,
1.147 + int32_t offsetIndex,
1.148 + UErrorCode * err);
1.149 +
1.150 +/**
1.151 + * ONLY used by ToU callback functions.
1.152 + * This function will write out the Unicode substitution character (U+FFFD).
1.153 + *
1.154 + * @param args callback fromUnicode arguments
1.155 + * @param offsetIndex the relative offset index from callback.
1.156 + * @param err error status <TT>U_BUFFER_OVERFLOW</TT>
1.157 + * @see ucnv_cbToUWriteUChars
1.158 + * @stable ICU 2.0
1.159 + */
1.160 +U_STABLE void U_EXPORT2 ucnv_cbToUWriteSub (UConverterToUnicodeArgs *args,
1.161 + int32_t offsetIndex,
1.162 + UErrorCode * err);
1.163 +#endif
1.164 +
1.165 +#endif
