/*

 *******************************************************************************

 *

 *   Copyright (C) 2003-2005, International Business Machines

 *   Corporation and others.  All Rights Reserved.

 *

 *******************************************************************************

 *   file name:  udataswp.h

 *   encoding:   US-ASCII

 *   tab size:   8 (not used)

 *   indentation:4

 *

 *   created on: 2003jun05

 *   created by: Markus W. Scherer

 *

 *   Definitions for ICU data transformations for different platforms,

 *   changing between big- and little-endian data and/or between

 *   charset families (ASCII<->EBCDIC).

 */

 #ifndef __UDATASWP_H__

 #define __UDATASWP_H__

 #include <stdarg.h>

 #include "unicode/utypes.h"

 /* forward declaration */

 U_CDECL_BEGIN

 struct UDataSwapper;

 typedef struct UDataSwapper UDataSwapper;

 /**

  * Function type for data transformation.

  * Transforms data, or just returns the length of the data if

  * the input length is -1.

  * Swap functions assume that their data pointers are aligned properly.

  *

  * Quick implementation outline:

  * (best to copy and adapt and existing swapper implementation)

  * check that the data looks like the expected format

  * if(length<0) {

  *   preflight:

  *   never dereference outData

  *   read inData and determine the data size

  *   assume that inData is long enough for this

  * } else {

  *   outData can be NULL if length==0

  *   inData==outData (in-place swapping) possible but not required!

  *   verify that length>=(actual size)

  *   if there is a chance that not every byte up to size is reached

  *     due to padding etc.:

  *   if(inData!=outData) {

  *     memcpy(outData, inData, actual size);

  *   }

  *   swap contents

  * }

  * return actual size

  *

  * Further implementation notes:

  * - read integers from inData before swapping them

  *   because in-place swapping can make them unreadable

  * - compareInvChars compares a local Unicode string with already-swapped

  *   output charset strings

  *

  * @param ds Pointer to UDataSwapper containing global data about the

  *           transformation and function pointers for handling primitive

  *           types.

  * @param inData Pointer to the input data to be transformed or examined.

  * @param length Length of the data, counting bytes. May be -1 for preflighting.

  *               If length>=0, then transform the data.

  *               If length==-1, then only determine the length of the data.

  *               The length cannot be determined from the data itself for all

  *               types of data (e.g., not for simple arrays of integers).

  * @param outData Pointer to the output data buffer.

  *                If length>=0 (transformation), then the output buffer must

  *                have a capacity of at least length.

  *                If length==-1, then outData will not be used and can be NULL.

  * @param pErrorCode ICU UErrorCode parameter, must not be NULL and must

  *                   fulfill U_SUCCESS on input.

  * @return The actual length of the data.

  *

  * @see UDataSwapper

  * @internal ICU 2.8

  */

 typedef int32_t U_CALLCONV

 UDataSwapFn(const UDataSwapper *ds,

             const void *inData, int32_t length, void *outData,

             UErrorCode *pErrorCode);

 /**

  * Convert one uint16_t from input to platform endianness.

  * @internal ICU 2.8

  */

 typedef uint16_t U_CALLCONV

 UDataReadUInt16(uint16_t x);

 /**

  * Convert one uint32_t from input to platform endianness.

  * @internal ICU 2.8

  */

 typedef uint32_t U_CALLCONV

 UDataReadUInt32(uint32_t x);

 /**

  * Convert one uint16_t from platform to input endianness.

  * @internal ICU 2.8

  */

 typedef void U_CALLCONV

 UDataWriteUInt16(uint16_t *p, uint16_t x);

 /**

  * Convert one uint32_t from platform to input endianness.

  * @internal ICU 2.8

  */

 typedef void U_CALLCONV

 UDataWriteUInt32(uint32_t *p, uint32_t x);

 /**

  * Compare invariant-character strings, one in the output data and the

  * other one caller-provided in Unicode.

  * An output data string is compared because strings are usually swapped

  * before the rest of the data, to allow for sorting of string tables

  * according to the output charset.

  * You can use -1 for the length parameters of NUL-terminated strings as usual.

  * Returns Unicode code point order for invariant characters.

  * @internal ICU 2.8

  */

 typedef int32_t U_CALLCONV

 UDataCompareInvChars(const UDataSwapper *ds,

                      const char *outString, int32_t outLength,

                      const UChar *localString, int32_t localLength);

 /**

  * Function for message output when an error occurs during data swapping.

  * A format string and variable number of arguments are passed

  * like for vprintf().

  *

  * @param context A function-specific context pointer.

  * @param fmt The format string.

  * @param args The arguments for format string inserts.

  *

  * @internal ICU 2.8

  */

 typedef void U_CALLCONV

 UDataPrintError(void *context, const char *fmt, va_list args);

 struct UDataSwapper {

     /** Input endianness. @internal ICU 2.8 */

     UBool inIsBigEndian;

     /** Input charset family. @see U_CHARSET_FAMILY @internal ICU 2.8 */

     uint8_t inCharset;

     /** Output endianness. @internal ICU 2.8 */

     UBool outIsBigEndian;

     /** Output charset family. @see U_CHARSET_FAMILY @internal ICU 2.8 */

     uint8_t outCharset;

     /* basic functions for reading data values */

     /** Convert one uint16_t from input to platform endianness. @internal ICU 2.8 */

     UDataReadUInt16 *readUInt16;

     /** Convert one uint32_t from input to platform endianness. @internal ICU 2.8 */

     UDataReadUInt32 *readUInt32;

     /** Compare an invariant-character output string with a local one. @internal ICU 2.8 */

     UDataCompareInvChars *compareInvChars;

     /* basic functions for writing data values */

     /** Convert one uint16_t from platform to input endianness. @internal ICU 2.8 */

     UDataWriteUInt16 *writeUInt16;

     /** Convert one uint32_t from platform to input endianness. @internal ICU 2.8 */

     UDataWriteUInt32 *writeUInt32;

     /* basic functions for data transformations */

     /** Transform an array of 16-bit integers. @internal ICU 2.8 */

     UDataSwapFn *swapArray16;

     /** Transform an array of 32-bit integers. @internal ICU 2.8 */

     UDataSwapFn *swapArray32;

     /** Transform an invariant-character string. @internal ICU 2.8 */

     UDataSwapFn *swapInvChars;

     /**

      * Function for message output when an error occurs during data swapping.

      * Can be NULL.

      * @internal ICU 2.8

      */

     UDataPrintError *printError;

     /** Context pointer for printError. @internal ICU 2.8 */

     void *printErrorContext;

 };

 U_CDECL_END

 U_CAPI UDataSwapper * U_EXPORT2

 udata_openSwapper(UBool inIsBigEndian, uint8_t inCharset,

                   UBool outIsBigEndian, uint8_t outCharset,

                   UErrorCode *pErrorCode);

 /**

  * Open a UDataSwapper for the given input data and the specified output

  * characteristics.

  * Values of -1 for any of the characteristics mean the local platform's

  * characteristics.

  *

  * @see udata_swap

  * @internal ICU 2.8

  */

 U_CAPI UDataSwapper * U_EXPORT2

 udata_openSwapperForInputData(const void *data, int32_t length,

                               UBool outIsBigEndian, uint8_t outCharset,

                               UErrorCode *pErrorCode);

 U_CAPI void U_EXPORT2

 udata_closeSwapper(UDataSwapper *ds);

 /**

  * Read the beginning of an ICU data piece, recognize magic bytes,

  * swap the structure.

  * Set a U_UNSUPPORTED_ERROR if it does not look like an ICU data piece.

  *

  * @return The size of the data header, in bytes.

  *

  * @internal ICU 2.8

  */

 U_CAPI int32_t U_EXPORT2

 udata_swapDataHeader(const UDataSwapper *ds,

                      const void *inData, int32_t length, void *outData,

                      UErrorCode *pErrorCode);

 /**

  * Convert one int16_t from input to platform endianness.

  * @internal ICU 2.8

  */

 U_CAPI int16_t U_EXPORT2

 udata_readInt16(const UDataSwapper *ds, int16_t x);

 /**

  * Convert one int32_t from input to platform endianness.

  * @internal ICU 2.8

  */

 U_CAPI int32_t U_EXPORT2

 udata_readInt32(const UDataSwapper *ds, int32_t x);

 /**

  * Swap a block of invariant, NUL-terminated strings, but not padding

  * bytes after the last string.

  * @internal

  */

 U_CAPI int32_t U_EXPORT2

 udata_swapInvStringBlock(const UDataSwapper *ds,

                          const void *inData, int32_t length, void *outData,

                          UErrorCode *pErrorCode);

 U_CAPI void U_EXPORT2

 udata_printError(const UDataSwapper *ds,

                  const char *fmt,

                  ...);

 /* internal exports from putil.c -------------------------------------------- */

 /* declared here to keep them out of the public putil.h */

 /**

  * Swap invariant char * strings ASCII->EBCDIC.

  * @internal

  */

 U_CFUNC int32_t

 uprv_ebcdicFromAscii(const UDataSwapper *ds,

                      const void *inData, int32_t length, void *outData,

                      UErrorCode *pErrorCode);

 /**

  * Copy invariant ASCII char * strings and verify they are invariant.

  * @internal

  */

 U_CFUNC int32_t

 uprv_copyAscii(const UDataSwapper *ds,

                const void *inData, int32_t length, void *outData,

                UErrorCode *pErrorCode);

 /**

  * Swap invariant char * strings EBCDIC->ASCII.

  * @internal

  */

 U_CFUNC int32_t

 uprv_asciiFromEbcdic(const UDataSwapper *ds,

                      const void *inData, int32_t length, void *outData,

                      UErrorCode *pErrorCode);

 /**

  * Copy invariant EBCDIC char * strings and verify they are invariant.

  * @internal

  */

 U_CFUNC int32_t

 uprv_copyEbcdic(const UDataSwapper *ds,

                 const void *inData, int32_t length, void *outData,

                 UErrorCode *pErrorCode);

 /**

  * Compare ASCII invariant char * with Unicode invariant UChar *

  * @internal

  */

 U_CFUNC int32_t

 uprv_compareInvAscii(const UDataSwapper *ds,

                      const char *outString, int32_t outLength,

                      const UChar *localString, int32_t localLength);

 /**

  * Compare EBCDIC invariant char * with Unicode invariant UChar *

  * @internal

  */

 U_CFUNC int32_t

 uprv_compareInvEbcdic(const UDataSwapper *ds,

                       const char *outString, int32_t outLength,

                       const UChar *localString, int32_t localLength);

 /* material... -------------------------------------------------------------- */

 #if 0

 /* udata.h */

 /**

  * Public API function in udata.c

  *

  * Same as udata_openChoice() but automatically swaps the data.

  * isAcceptable, if not NULL, may accept data with endianness and charset family

  * different from the current platform's properties.

  * If the data is acceptable and the platform properties do not match, then

  * the swap function is called to swap an allocated version of the data.

  * Preflighting may or may not be performed depending on whether the size of

  * the loaded data item is known.

  *

  * @param isAcceptable Same as for udata_openChoice(). May be NULL.

  *

  * @internal ICU 2.8

  */

 U_CAPI UDataMemory * U_EXPORT2

 udata_openSwap(const char *path, const char *type, const char *name,

                UDataMemoryIsAcceptable *isAcceptable, void *isAcceptableContext,

                UDataSwapFn *swap,

                UDataPrintError *printError, void *printErrorContext,

                UErrorCode *pErrorCode);

 #endif

 #endif