michael@0: /*
michael@0: *******************************************************************************
michael@0: *
michael@0: *   Copyright (C) 2003-2005, International Business Machines
michael@0: *   Corporation and others.  All Rights Reserved.
michael@0: *
michael@0: *******************************************************************************
michael@0: *   file name:  udataswp.h
michael@0: *   encoding:   US-ASCII
michael@0: *   tab size:   8 (not used)
michael@0: *   indentation:4
michael@0: *
michael@0: *   created on: 2003jun05
michael@0: *   created by: Markus W. Scherer
michael@0: *
michael@0: *   Definitions for ICU data transformations for different platforms,
michael@0: *   changing between big- and little-endian data and/or between
michael@0: *   charset families (ASCII<->EBCDIC).
michael@0: */
michael@0: 
michael@0: #ifndef __UDATASWP_H__
michael@0: #define __UDATASWP_H__
michael@0: 
michael@0: #include <stdarg.h>
michael@0: #include "unicode/utypes.h"
michael@0: 
michael@0: /* forward declaration */
michael@0: 
michael@0: U_CDECL_BEGIN
michael@0: 
michael@0: struct UDataSwapper;
michael@0: typedef struct UDataSwapper UDataSwapper;
michael@0: 
michael@0: /**
michael@0:  * Function type for data transformation.
michael@0:  * Transforms data, or just returns the length of the data if
michael@0:  * the input length is -1.
michael@0:  * Swap functions assume that their data pointers are aligned properly.
michael@0:  *
michael@0:  * Quick implementation outline:
michael@0:  * (best to copy and adapt and existing swapper implementation)
michael@0:  * check that the data looks like the expected format
michael@0:  * if(length<0) {
michael@0:  *   preflight:
michael@0:  *   never dereference outData
michael@0:  *   read inData and determine the data size
michael@0:  *   assume that inData is long enough for this
michael@0:  * } else {
michael@0:  *   outData can be NULL if length==0
michael@0:  *   inData==outData (in-place swapping) possible but not required!
michael@0:  *   verify that length>=(actual size)
michael@0:  *   if there is a chance that not every byte up to size is reached
michael@0:  *     due to padding etc.:
michael@0:  *   if(inData!=outData) {
michael@0:  *     memcpy(outData, inData, actual size);
michael@0:  *   }
michael@0:  *   swap contents
michael@0:  * }
michael@0:  * return actual size
michael@0:  *
michael@0:  * Further implementation notes:
michael@0:  * - read integers from inData before swapping them
michael@0:  *   because in-place swapping can make them unreadable
michael@0:  * - compareInvChars compares a local Unicode string with already-swapped
michael@0:  *   output charset strings
michael@0:  *
michael@0:  * @param ds Pointer to UDataSwapper containing global data about the
michael@0:  *           transformation and function pointers for handling primitive
michael@0:  *           types.
michael@0:  * @param inData Pointer to the input data to be transformed or examined.
michael@0:  * @param length Length of the data, counting bytes. May be -1 for preflighting.
michael@0:  *               If length>=0, then transform the data.
michael@0:  *               If length==-1, then only determine the length of the data.
michael@0:  *               The length cannot be determined from the data itself for all
michael@0:  *               types of data (e.g., not for simple arrays of integers).
michael@0:  * @param outData Pointer to the output data buffer.
michael@0:  *                If length>=0 (transformation), then the output buffer must
michael@0:  *                have a capacity of at least length.
michael@0:  *                If length==-1, then outData will not be used and can be NULL.
michael@0:  * @param pErrorCode ICU UErrorCode parameter, must not be NULL and must
michael@0:  *                   fulfill U_SUCCESS on input.
michael@0:  * @return The actual length of the data.
michael@0:  *
michael@0:  * @see UDataSwapper
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: typedef int32_t U_CALLCONV
michael@0: UDataSwapFn(const UDataSwapper *ds,
michael@0:             const void *inData, int32_t length, void *outData,
michael@0:             UErrorCode *pErrorCode);
michael@0: 
michael@0: /**
michael@0:  * Convert one uint16_t from input to platform endianness.
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: typedef uint16_t U_CALLCONV
michael@0: UDataReadUInt16(uint16_t x);
michael@0: 
michael@0: /**
michael@0:  * Convert one uint32_t from input to platform endianness.
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: typedef uint32_t U_CALLCONV
michael@0: UDataReadUInt32(uint32_t x);
michael@0: 
michael@0: /**
michael@0:  * Convert one uint16_t from platform to input endianness.
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: typedef void U_CALLCONV
michael@0: UDataWriteUInt16(uint16_t *p, uint16_t x);
michael@0: 
michael@0: /**
michael@0:  * Convert one uint32_t from platform to input endianness.
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: typedef void U_CALLCONV
michael@0: UDataWriteUInt32(uint32_t *p, uint32_t x);
michael@0: 
michael@0: /**
michael@0:  * Compare invariant-character strings, one in the output data and the
michael@0:  * other one caller-provided in Unicode.
michael@0:  * An output data string is compared because strings are usually swapped
michael@0:  * before the rest of the data, to allow for sorting of string tables
michael@0:  * according to the output charset.
michael@0:  * You can use -1 for the length parameters of NUL-terminated strings as usual.
michael@0:  * Returns Unicode code point order for invariant characters.
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: typedef int32_t U_CALLCONV
michael@0: UDataCompareInvChars(const UDataSwapper *ds,
michael@0:                      const char *outString, int32_t outLength,
michael@0:                      const UChar *localString, int32_t localLength);
michael@0: 
michael@0: /**
michael@0:  * Function for message output when an error occurs during data swapping.
michael@0:  * A format string and variable number of arguments are passed
michael@0:  * like for vprintf().
michael@0:  *
michael@0:  * @param context A function-specific context pointer.
michael@0:  * @param fmt The format string.
michael@0:  * @param args The arguments for format string inserts.
michael@0:  *
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: typedef void U_CALLCONV
michael@0: UDataPrintError(void *context, const char *fmt, va_list args);
michael@0: 
michael@0: struct UDataSwapper {
michael@0:     /** Input endianness. @internal ICU 2.8 */
michael@0:     UBool inIsBigEndian;
michael@0:     /** Input charset family. @see U_CHARSET_FAMILY @internal ICU 2.8 */
michael@0:     uint8_t inCharset;
michael@0:     /** Output endianness. @internal ICU 2.8 */
michael@0:     UBool outIsBigEndian;
michael@0:     /** Output charset family. @see U_CHARSET_FAMILY @internal ICU 2.8 */
michael@0:     uint8_t outCharset;
michael@0: 
michael@0:     /* basic functions for reading data values */
michael@0: 
michael@0:     /** Convert one uint16_t from input to platform endianness. @internal ICU 2.8 */
michael@0:     UDataReadUInt16 *readUInt16;
michael@0:     /** Convert one uint32_t from input to platform endianness. @internal ICU 2.8 */
michael@0:     UDataReadUInt32 *readUInt32;
michael@0:     /** Compare an invariant-character output string with a local one. @internal ICU 2.8 */
michael@0:     UDataCompareInvChars *compareInvChars;
michael@0: 
michael@0:     /* basic functions for writing data values */
michael@0: 
michael@0:     /** Convert one uint16_t from platform to input endianness. @internal ICU 2.8 */
michael@0:     UDataWriteUInt16 *writeUInt16;
michael@0:     /** Convert one uint32_t from platform to input endianness. @internal ICU 2.8 */
michael@0:     UDataWriteUInt32 *writeUInt32;
michael@0: 
michael@0:     /* basic functions for data transformations */
michael@0: 
michael@0:     /** Transform an array of 16-bit integers. @internal ICU 2.8 */
michael@0:     UDataSwapFn *swapArray16;
michael@0:     /** Transform an array of 32-bit integers. @internal ICU 2.8 */
michael@0:     UDataSwapFn *swapArray32;
michael@0:     /** Transform an invariant-character string. @internal ICU 2.8 */
michael@0:     UDataSwapFn *swapInvChars;
michael@0: 
michael@0:     /**
michael@0:      * Function for message output when an error occurs during data swapping.
michael@0:      * Can be NULL.
michael@0:      * @internal ICU 2.8
michael@0:      */
michael@0:     UDataPrintError *printError;
michael@0:     /** Context pointer for printError. @internal ICU 2.8 */
michael@0:     void *printErrorContext;
michael@0: };
michael@0: 
michael@0: U_CDECL_END
michael@0: 
michael@0: U_CAPI UDataSwapper * U_EXPORT2
michael@0: udata_openSwapper(UBool inIsBigEndian, uint8_t inCharset,
michael@0:                   UBool outIsBigEndian, uint8_t outCharset,
michael@0:                   UErrorCode *pErrorCode);
michael@0: 
michael@0: /**
michael@0:  * Open a UDataSwapper for the given input data and the specified output
michael@0:  * characteristics.
michael@0:  * Values of -1 for any of the characteristics mean the local platform's
michael@0:  * characteristics.
michael@0:  *
michael@0:  * @see udata_swap
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: U_CAPI UDataSwapper * U_EXPORT2
michael@0: udata_openSwapperForInputData(const void *data, int32_t length,
michael@0:                               UBool outIsBigEndian, uint8_t outCharset,
michael@0:                               UErrorCode *pErrorCode);
michael@0: 
michael@0: U_CAPI void U_EXPORT2
michael@0: udata_closeSwapper(UDataSwapper *ds);
michael@0: 
michael@0: /**
michael@0:  * Read the beginning of an ICU data piece, recognize magic bytes,
michael@0:  * swap the structure.
michael@0:  * Set a U_UNSUPPORTED_ERROR if it does not look like an ICU data piece.
michael@0:  *
michael@0:  * @return The size of the data header, in bytes.
michael@0:  *
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: U_CAPI int32_t U_EXPORT2
michael@0: udata_swapDataHeader(const UDataSwapper *ds,
michael@0:                      const void *inData, int32_t length, void *outData,
michael@0:                      UErrorCode *pErrorCode);
michael@0: 
michael@0: /**
michael@0:  * Convert one int16_t from input to platform endianness.
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: U_CAPI int16_t U_EXPORT2
michael@0: udata_readInt16(const UDataSwapper *ds, int16_t x);
michael@0: 
michael@0: /**
michael@0:  * Convert one int32_t from input to platform endianness.
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: U_CAPI int32_t U_EXPORT2
michael@0: udata_readInt32(const UDataSwapper *ds, int32_t x);
michael@0: 
michael@0: /**
michael@0:  * Swap a block of invariant, NUL-terminated strings, but not padding
michael@0:  * bytes after the last string.
michael@0:  * @internal
michael@0:  */
michael@0: U_CAPI int32_t U_EXPORT2
michael@0: udata_swapInvStringBlock(const UDataSwapper *ds,
michael@0:                          const void *inData, int32_t length, void *outData,
michael@0:                          UErrorCode *pErrorCode);
michael@0: 
michael@0: U_CAPI void U_EXPORT2
michael@0: udata_printError(const UDataSwapper *ds,
michael@0:                  const char *fmt,
michael@0:                  ...);
michael@0: 
michael@0: /* internal exports from putil.c -------------------------------------------- */
michael@0: 
michael@0: /* declared here to keep them out of the public putil.h */
michael@0: 
michael@0: /**
michael@0:  * Swap invariant char * strings ASCII->EBCDIC.
michael@0:  * @internal
michael@0:  */
michael@0: U_CAPI int32_t U_EXPORT2
michael@0: uprv_ebcdicFromAscii(const UDataSwapper *ds,
michael@0:                      const void *inData, int32_t length, void *outData,
michael@0:                      UErrorCode *pErrorCode);
michael@0: 
michael@0: /**
michael@0:  * Copy invariant ASCII char * strings and verify they are invariant.
michael@0:  * @internal
michael@0:  */
michael@0: U_CFUNC int32_t
michael@0: uprv_copyAscii(const UDataSwapper *ds,
michael@0:                const void *inData, int32_t length, void *outData,
michael@0:                UErrorCode *pErrorCode);
michael@0: 
michael@0: /**
michael@0:  * Swap invariant char * strings EBCDIC->ASCII.
michael@0:  * @internal
michael@0:  */
michael@0: U_CFUNC int32_t
michael@0: uprv_asciiFromEbcdic(const UDataSwapper *ds,
michael@0:                      const void *inData, int32_t length, void *outData,
michael@0:                      UErrorCode *pErrorCode);
michael@0: 
michael@0: /**
michael@0:  * Copy invariant EBCDIC char * strings and verify they are invariant.
michael@0:  * @internal
michael@0:  */
michael@0: U_CFUNC int32_t
michael@0: uprv_copyEbcdic(const UDataSwapper *ds,
michael@0:                 const void *inData, int32_t length, void *outData,
michael@0:                 UErrorCode *pErrorCode);
michael@0: 
michael@0: /**
michael@0:  * Compare ASCII invariant char * with Unicode invariant UChar *
michael@0:  * @internal
michael@0:  */
michael@0: U_CFUNC int32_t
michael@0: uprv_compareInvAscii(const UDataSwapper *ds,
michael@0:                      const char *outString, int32_t outLength,
michael@0:                      const UChar *localString, int32_t localLength);
michael@0: 
michael@0: /**
michael@0:  * Compare EBCDIC invariant char * with Unicode invariant UChar *
michael@0:  * @internal
michael@0:  */
michael@0: U_CFUNC int32_t
michael@0: uprv_compareInvEbcdic(const UDataSwapper *ds,
michael@0:                       const char *outString, int32_t outLength,
michael@0:                       const UChar *localString, int32_t localLength);
michael@0: 
michael@0: /* material... -------------------------------------------------------------- */
michael@0: 
michael@0: #if 0
michael@0: 
michael@0: /* udata.h */
michael@0: 
michael@0: /**
michael@0:  * Public API function in udata.c
michael@0:  *
michael@0:  * Same as udata_openChoice() but automatically swaps the data.
michael@0:  * isAcceptable, if not NULL, may accept data with endianness and charset family
michael@0:  * different from the current platform's properties.
michael@0:  * If the data is acceptable and the platform properties do not match, then
michael@0:  * the swap function is called to swap an allocated version of the data.
michael@0:  * Preflighting may or may not be performed depending on whether the size of
michael@0:  * the loaded data item is known.
michael@0:  *
michael@0:  * @param isAcceptable Same as for udata_openChoice(). May be NULL.
michael@0:  *
michael@0:  * @internal ICU 2.8
michael@0:  */
michael@0: U_CAPI UDataMemory * U_EXPORT2
michael@0: udata_openSwap(const char *path, const char *type, const char *name,
michael@0:                UDataMemoryIsAcceptable *isAcceptable, void *isAcceptableContext,
michael@0:                UDataSwapFn *swap,
michael@0:                UDataPrintError *printError, void *printErrorContext,
michael@0:                UErrorCode *pErrorCode);
michael@0: 
michael@0: #endif
michael@0: 
michael@0: #endif