icuSources/common/udataswp.h

   1 /*
   2 *******************************************************************************
   3 *
   4 *   Copyright (C) 2003-2014, International Business Machines
   5 *   Corporation and others.  All Rights Reserved.
   6 *
   7 *******************************************************************************
   8 *   file name:  udataswp.h
   9 *   encoding:   US-ASCII
  10 *   tab size:   8 (not used)
  11 *   indentation:4
  12 *
  13 *   created on: 2003jun05
  14 *   created by: Markus W. Scherer
  15 *
  16 *   Definitions for ICU data transformations for different platforms,
  17 *   changing between big- and little-endian data and/or between
  18 *   charset families (ASCII<->EBCDIC).
  19 */
  20
  21 #ifndef __UDATASWP_H__
  22 #define __UDATASWP_H__
  23
  24 #include <stdarg.h>
  25 #include "unicode/utypes.h"
  26
  27 /* forward declaration */
  28
  29 U_CDECL_BEGIN
  30
  31 struct UDataSwapper;
  32 typedef struct UDataSwapper UDataSwapper;
  33
  34 /**
  35  * Function type for data transformation.
  36  * Transforms data, or just returns the length of the data if
  37  * the input length is -1.
  38  * Swap functions assume that their data pointers are aligned properly.
  39  *
  40  * Quick implementation outline:
  41  * (best to copy and adapt and existing swapper implementation)
  42  * check that the data looks like the expected format
  43  * if(length<0) {
  44  *   preflight:
  45  *   never dereference outData
  46  *   read inData and determine the data size
  47  *   assume that inData is long enough for this
  48  * } else {
  49  *   outData can be NULL if length==0
  50  *   inData==outData (in-place swapping) possible but not required!
  51  *   verify that length>=(actual size)
  52  *   if there is a chance that not every byte up to size is reached
  53  *     due to padding etc.:
  54  *   if(inData!=outData) {
  55  *     memcpy(outData, inData, actual size);
  56  *   }
  57  *   swap contents
  58  * }
  59  * return actual size
  60  *
  61  * Further implementation notes:
  62  * - read integers from inData before swapping them
  63  *   because in-place swapping can make them unreadable
  64  * - compareInvChars compares a local Unicode string with already-swapped
  65  *   output charset strings
  66  *
  67  * @param ds Pointer to UDataSwapper containing global data about the
  68  *           transformation and function pointers for handling primitive
  69  *           types.
  70  * @param inData Pointer to the input data to be transformed or examined.
  71  * @param length Length of the data, counting bytes. May be -1 for preflighting.
  72  *               If length>=0, then transform the data.
  73  *               If length==-1, then only determine the length of the data.
  74  *               The length cannot be determined from the data itself for all
  75  *               types of data (e.g., not for simple arrays of integers).
  76  * @param outData Pointer to the output data buffer.
  77  *                If length>=0 (transformation), then the output buffer must
  78  *                have a capacity of at least length.
  79  *                If length==-1, then outData will not be used and can be NULL.
  80  * @param pErrorCode ICU UErrorCode parameter, must not be NULL and must
  81  *                   fulfill U_SUCCESS on input.
  82  * @return The actual length of the data.
  83  *
  84  * @see UDataSwapper
  85  * @internal ICU 2.8
  86  */
  87 typedef int32_t U_CALLCONV
  88 UDataSwapFn(const UDataSwapper *ds,
  89             const void *inData, int32_t length, void *outData,
  90             UErrorCode *pErrorCode);
  91
  92 /**
  93  * Convert one uint16_t from input to platform endianness.
  94  * @internal ICU 2.8
  95  */
  96 typedef uint16_t U_CALLCONV
  97 UDataReadUInt16(uint16_t x);
  98
  99 /**
 100  * Convert one uint32_t from input to platform endianness.
 101  * @internal ICU 2.8
 102  */
 103 typedef uint32_t U_CALLCONV
 104 UDataReadUInt32(uint32_t x);
 105
 106 /**
 107  * Convert one uint16_t from platform to input endianness.
 108  * @internal ICU 2.8
 109  */
 110 typedef void U_CALLCONV
 111 UDataWriteUInt16(uint16_t *p, uint16_t x);
 112
 113 /**
 114  * Convert one uint32_t from platform to input endianness.
 115  * @internal ICU 2.8
 116  */
 117 typedef void U_CALLCONV
 118 UDataWriteUInt32(uint32_t *p, uint32_t x);
 119
 120 /**
 121  * Compare invariant-character strings, one in the output data and the
 122  * other one caller-provided in Unicode.
 123  * An output data string is compared because strings are usually swapped
 124  * before the rest of the data, to allow for sorting of string tables
 125  * according to the output charset.
 126  * You can use -1 for the length parameters of NUL-terminated strings as usual.
 127  * Returns Unicode code point order for invariant characters.
 128  * @internal ICU 2.8
 129  */
 130 typedef int32_t U_CALLCONV
 131 UDataCompareInvChars(const UDataSwapper *ds,
 132                      const char *outString, int32_t outLength,
 133                      const UChar *localString, int32_t localLength);
 134
 135 /**
 136  * Function for message output when an error occurs during data swapping.
 137  * A format string and variable number of arguments are passed
 138  * like for vprintf().
 139  *
 140  * @param context A function-specific context pointer.
 141  * @param fmt The format string.
 142  * @param args The arguments for format string inserts.
 143  *
 144  * @internal ICU 2.8
 145  */
 146 typedef void U_CALLCONV
 147 UDataPrintError(void *context, const char *fmt, va_list args);
 148
 149 struct UDataSwapper {
 150     /** Input endianness. @internal ICU 2.8 */
 151     UBool inIsBigEndian;
 152     /** Input charset family. @see U_CHARSET_FAMILY @internal ICU 2.8 */
 153     uint8_t inCharset;
 154     /** Output endianness. @internal ICU 2.8 */
 155     UBool outIsBigEndian;
 156     /** Output charset family. @see U_CHARSET_FAMILY @internal ICU 2.8 */
 157     uint8_t outCharset;
 158
 159     /* basic functions for reading data values */
 160
 161     /** Convert one uint16_t from input to platform endianness. @internal ICU 2.8 */
 162     UDataReadUInt16 *readUInt16;
 163     /** Convert one uint32_t from input to platform endianness. @internal ICU 2.8 */
 164     UDataReadUInt32 *readUInt32;
 165     /** Compare an invariant-character output string with a local one. @internal ICU 2.8 */
 166     UDataCompareInvChars *compareInvChars;
 167
 168     /* basic functions for writing data values */
 169
 170     /** Convert one uint16_t from platform to input endianness. @internal ICU 2.8 */
 171     UDataWriteUInt16 *writeUInt16;
 172     /** Convert one uint32_t from platform to input endianness. @internal ICU 2.8 */
 173     UDataWriteUInt32 *writeUInt32;
 174
 175     /* basic functions for data transformations */
 176
 177     /** Transform an array of 16-bit integers. @internal ICU 2.8 */
 178     UDataSwapFn *swapArray16;
 179     /** Transform an array of 32-bit integers. @internal ICU 2.8 */
 180     UDataSwapFn *swapArray32;
 181     /** Transform an array of 64-bit integers. @internal ICU 53 */
 182     UDataSwapFn *swapArray64;
 183     /** Transform an invariant-character string. @internal ICU 2.8 */
 184     UDataSwapFn *swapInvChars;
 185
 186     /**
 187      * Function for message output when an error occurs during data swapping.
 188      * Can be NULL.
 189      * @internal ICU 2.8
 190      */
 191     UDataPrintError *printError;
 192     /** Context pointer for printError. @internal ICU 2.8 */
 193     void *printErrorContext;
 194 };
 195
 196 U_CDECL_END
 197
 198 U_CAPI UDataSwapper * U_EXPORT2
 199 udata_openSwapper(UBool inIsBigEndian, uint8_t inCharset,
 200                   UBool outIsBigEndian, uint8_t outCharset,
 201                   UErrorCode *pErrorCode);
 202
 203 /**
 204  * Open a UDataSwapper for the given input data and the specified output
 205  * characteristics.
 206  * Values of -1 for any of the characteristics mean the local platform's
 207  * characteristics.
 208  *
 209  * @see udata_swap
 210  * @internal ICU 2.8
 211  */
 212 U_CAPI UDataSwapper * U_EXPORT2
 213 udata_openSwapperForInputData(const void *data, int32_t length,
 214                               UBool outIsBigEndian, uint8_t outCharset,
 215                               UErrorCode *pErrorCode);
 216
 217 U_CAPI void U_EXPORT2
 218 udata_closeSwapper(UDataSwapper *ds);
 219
 220 /**
 221  * Read the beginning of an ICU data piece, recognize magic bytes,
 222  * swap the structure.
 223  * Set a U_UNSUPPORTED_ERROR if it does not look like an ICU data piece.
 224  *
 225  * @return The size of the data header, in bytes.
 226  *
 227  * @internal ICU 2.8
 228  */
 229 U_CAPI int32_t U_EXPORT2
 230 udata_swapDataHeader(const UDataSwapper *ds,
 231                      const void *inData, int32_t length, void *outData,
 232                      UErrorCode *pErrorCode);
 233
 234 /**
 235  * Convert one int16_t from input to platform endianness.
 236  * @internal ICU 2.8
 237  */
 238 U_CAPI int16_t U_EXPORT2
 239 udata_readInt16(const UDataSwapper *ds, int16_t x);
 240
 241 /**
 242  * Convert one int32_t from input to platform endianness.
 243  * @internal ICU 2.8
 244  */
 245 U_CAPI int32_t U_EXPORT2
 246 udata_readInt32(const UDataSwapper *ds, int32_t x);
 247
 248 /**
 249  * Swap a block of invariant, NUL-terminated strings, but not padding
 250  * bytes after the last string.
 251  * @internal
 252  */
 253 U_CAPI int32_t U_EXPORT2
 254 udata_swapInvStringBlock(const UDataSwapper *ds,
 255                          const void *inData, int32_t length, void *outData,
 256                          UErrorCode *pErrorCode);
 257
 258 U_CAPI void U_EXPORT2
 259 udata_printError(const UDataSwapper *ds,
 260                  const char *fmt,
 261                  ...);
 262
 263 /* internal exports from putil.c -------------------------------------------- */
 264
 265 /* declared here to keep them out of the public putil.h */
 266
 267 /**
 268  * Swap invariant char * strings ASCII->EBCDIC.
 269  * @internal
 270  */
 271 U_CAPI int32_t U_EXPORT2
 272 uprv_ebcdicFromAscii(const UDataSwapper *ds,
 273                      const void *inData, int32_t length, void *outData,
 274                      UErrorCode *pErrorCode);
 275
 276 /**
 277  * Copy invariant ASCII char * strings and verify they are invariant.
 278  * @internal
 279  */
 280 U_CFUNC int32_t
 281 uprv_copyAscii(const UDataSwapper *ds,
 282                const void *inData, int32_t length, void *outData,
 283                UErrorCode *pErrorCode);
 284
 285 /**
 286  * Swap invariant char * strings EBCDIC->ASCII.
 287  * @internal
 288  */
 289 U_CFUNC int32_t
 290 uprv_asciiFromEbcdic(const UDataSwapper *ds,
 291                      const void *inData, int32_t length, void *outData,
 292                      UErrorCode *pErrorCode);
 293
 294 /**
 295  * Copy invariant EBCDIC char * strings and verify they are invariant.
 296  * @internal
 297  */
 298 U_CFUNC int32_t
 299 uprv_copyEbcdic(const UDataSwapper *ds,
 300                 const void *inData, int32_t length, void *outData,
 301                 UErrorCode *pErrorCode);
 302
 303 /**
 304  * Compare ASCII invariant char * with Unicode invariant UChar *
 305  * @internal
 306  */
 307 U_CFUNC int32_t
 308 uprv_compareInvAscii(const UDataSwapper *ds,
 309                      const char *outString, int32_t outLength,
 310                      const UChar *localString, int32_t localLength);
 311
 312 /**
 313  * Compare EBCDIC invariant char * with Unicode invariant UChar *
 314  * @internal
 315  */
 316 U_CFUNC int32_t
 317 uprv_compareInvEbcdic(const UDataSwapper *ds,
 318                       const char *outString, int32_t outLength,
 319                       const UChar *localString, int32_t localLength);
 320
 321 /* material... -------------------------------------------------------------- */
 322
 323 #if 0
 324
 325 /* udata.h */
 326
 327 /**
 328  * Public API function in udata.c
 329  *
 330  * Same as udata_openChoice() but automatically swaps the data.
 331  * isAcceptable, if not NULL, may accept data with endianness and charset family
 332  * different from the current platform's properties.
 333  * If the data is acceptable and the platform properties do not match, then
 334  * the swap function is called to swap an allocated version of the data.
 335  * Preflighting may or may not be performed depending on whether the size of
 336  * the loaded data item is known.
 337  *
 338  * @param isAcceptable Same as for udata_openChoice(). May be NULL.
 339  *
 340  * @internal ICU 2.8
 341  */
 342 U_CAPI UDataMemory * U_EXPORT2
 343 udata_openSwap(const char *path, const char *type, const char *name,
 344                UDataMemoryIsAcceptable *isAcceptable, void *isAcceptableContext,
 345                UDataSwapFn *swap,
 346                UDataPrintError *printError, void *printErrorContext,
 347                UErrorCode *pErrorCode);
 348
 349 #endif
 350
 351 #endif