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