endianrw.h

GPRS模块设计资料包

/**
 * \file endianrw.h
 * \author Wei Yongming <[e-mail]>
 * \date 2002/01/06
 * 
 *  This file includes functions for reading and writing data 
 *  from general sources, such as file, memory, etc., and also
 *  includes functions for reading and writing endian-specific 
 *  values.
 *
 \verbatim
    Copyright (C) 1998-2002 Wei Yongming.
    Copyright (C) 2002-2004 Feynman Software.

    This file is part of MiniGUI, a compact cross-platform Graphics 
    User Interface (GUI) support system for real-time embedded systems.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 \endverbatim
 */

/*
 * $Id: endianrw.h,v 1.21 2004/06/26 08:41:44 weiym Exp $
 * 
 *             MiniGUI for Linux/uClinux, eCos, uC/OS-II, VxWorks version 1.6.x
 *             Copyright (C) 1998-2002 Wei Yongming.
 *             Copyright (C) 2002-2004 Feynman Software.
 *
 *             The idea and most code come from
 *             LGPL'ed SDL by (Sam Lantinga, [e-mail]).
 *             Copyright (C) 1997-2001 Sam Lantinga
 */

#ifndef _MGUI_ENDIAN_RW_H
#define _MGUI_ENDIAN_RW_H

/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif

/************************** General RW operations ****************************/

    /**
     * \addtogroup fns Functions
     * @{
     */

    /**
     * \addtogroup global_fns Global/general functions
     * @{
     */

    /**
     * \defgroup general_rw_fns General read/write operations
     *
     * MiniGUI's general read/write operation provides a general interface 
     * to read from and write to various data source, such as files, memory, 
     * and so on.
     *
     * @{
     */

#define RWAREA_TYPE_UNKNOWN 0
#define RWAREA_TYPE_STDIO   1
#define RWAREA_TYPE_MEM     2

/**
 * The read/write operation structure.
 */
typedef struct MG_RWops {
    /**
     * Seek to \a offset relative to whence, one of stdio's whence values:\n
     *      SEEK_SET, SEEK_CUR, SEEK_END\n
     * Returns the final offset in the data source.
     */
    int (*seek)(struct MG_RWops *context, int offset, int whence);

    /**
     * Read up to \a num objects each of size \a objsize from the data
     * source to the area pointed at by \a ptr.
     * Returns the number of objects read, or -1 if the read failed.
     */
    int (*read)(struct MG_RWops *context, void *ptr, int objsize, int num);

    /**
     * Write exactly \a num objects each of size \a objsize from the area
     * pointed at by \a ptr to data source.
     * Returns \a num, or -1 if the write failed.
     */
    int (*write)(struct MG_RWops *context, const void *ptr, int objsize, int num);

#ifdef _USE_OWN_STDIO
    /* */
    int (*ungetc)(struct MG_RWops *context, unsigned char c);
#endif

    /*
     * Close and free an allocated MG_RWops structure.
     */
    int (*close)(struct MG_RWops *context);

    /**
     * Test the end-of-file indicator.
     */
    int (*eof)(struct MG_RWops *context);

    /**
     * Indicates the type of data source.
     *  can be one of the following values:
     *  - RWAREA_TYPE_UNKNOWN\n
     *      A unknown (uninitialized) data source type.
     *  - RWAREA_TYPE_STDIO\n
     *      Stdio stream data source.
     *  - RWAREA_TYPE_MEM\n
     *      Memory data source.
     */
    Uint32 type;

    union {
        struct {
            int autoclose;
            FILE *fp;
        } stdio;
        struct {
            Uint8 *base;
            Uint8 *here;
            Uint8 *stop;
        } mem;
        struct {
            void *data1;
        } unknown;
    } hidden;
} MG_RWops;

/**
 * \fn MG_RWops* MGUI_RWFromFile(const char *file, const char *mode)
 * \brief Creates an MG_RWops object from a file.
 *
 * This function uses the mode specified by \a mode and opens the file \a file
 * by using stdio function \a fopen. If success, this function creates a MG_RWops
 * object and returns it.
 *
 * \param file The file name.
 * \param mode The mode will be passed to \a fopen.
 * \return The pointer to created MG_RWops structure, NULL indicates error.
 *
 * \sa MG_RWops, MGUI_RWFromFP, MGUI_FreeRW, fopen(3)
 */

MG_RWops* MGUI_RWFromFile(const char *file, const char *mode);

/**
 * \fn MG_RWops* MGUI_RWFromFP(FILE *fp, int autoclose)
 * \brief Creates an MG_RWops object from an opened stdio FILE object.
 *
 * This function uses an opened stdio FILE object \a fp to create a MG_RWops object.
 *
 * \param fp The opened stdio FILE object.
 * \param autoclose Indicates whether to close the FILE object when \a close method is called.
 * \return The pointer to created MG_RWops structure, NULL indicates error.
 *
 * \sa MG_RWops, MGUI_RWFromFile, MGUI_FreeRW
 */
MG_RWops* MGUI_RWFromFP(FILE *fp, int autoclose);

/**
 * \fn MG_RWops* MGUI_RWFromMem(void *mem, int size)
 * \brief Creates an MG_RWops object from a block of memory.
 *
 * This function creates an MG_RWops object from a block of memory pointed to by \a mem,
 * which is \a size bytes long.
 *
 * \param mem The pointer to the memory block.
 * \param size The size of the memory block.
 *
 * \return The pointer to created MG_RWops structure, NULL indicates error.
 *
 * \sa MG_RWops, MGUI_FreeRW
 */
MG_RWops* MGUI_RWFromMem(void *mem, int size);

/**
 * \fn void MGUI_InitMemRW (MG_RWops* area, , void *mem, int size)
 * \brief Initialize an MG_RWops object from a block of memory.
 *
 * This function initializes an MG_RWops object pointed to by \a area 
 * from a block of memory pointed to by \a mem, which is \a size bytes long.
 *
 * \param area The pointer to the MG_RWops object.
 * \param mem The pointer to the memory block.
 * \param size The size of the memory block.
 *
 * \return none.
 *
 * \sa MG_RWops, MGUI_FreeRW, MGUI_RWFromMem
 */
void MGUI_InitMemRW (MG_RWops* area, void *mem, int size);

/**
 * \fn MG_RWops* MGUI_AllocRW(void)
 * \brief Allocates an uninitialized MG_RWops object.
 *
 * This function allocates an uninitialized MG_RWops object. You can specify the 
 * fields of the structure, and implemente a customized MG_RWops object.
 *
 * \return The pointer to allocated MG_RWops structure, NULL indicates error.
 *
 * \sa MG_RWops
 */
MG_RWops* MGUI_AllocRW(void);

/**
 * \fn void MGUI_FreeRW(MG_RWops *area)
 * \brief Frees an MG_RWops object.
 *
 * This function frees the MG_RWops object pointed to by \a area.
 *
 * \param area The pointer to the MG_RWops object.
 *
 * \sa MGUI_RWFromFile, MGUI_RWFromFP, MGUI_RWFromMem
 */
void MGUI_FreeRW(MG_RWops *area);

/* Macros to easily read and write from an MG_RWops structure */
/**
 * \def MGUI_RWseek(ctx, offset, whence)
 * \brief Seeks an MG_RWops object.
 *
 * This macro seeks to \a offset relative to \a whence.
 *
 * \param ctx The pointer to the MG_RWops object.
 * \param offset The offset relative to \a whence.
 * \param whence One of stdio's \a whence values:
 *
 *      - SEEK_SET\n
 *        the offset is relative to the start of the file.
 *      - SEEK_CUR\n
 *        the offset is relative to the current position indicator.
 *      - SEEK_END\n
 *        the offset is relative to the end of the file.
 *
 * \return The final offset in the data source.
 * \sa MGUI_RWtell
 */
#define MGUI_RWseek(ctx, offset, whence)    (ctx)->seek(ctx, offset, whence)

/**
 * \def MGUI_RWtell(ctx)
 * \brief Obtains the current value of the position indicator for a data source.
 *
 * This macro obtains the current value of the position indicator for the data source
 * pointed to by \a ctx.
 *
 * \param ctx The pointer to the MG_RWops object.
 * \return the current value of the position indicator.
 *
 * \sa MGUI_RWseek
 */
#define MGUI_RWtell(ctx)                    (ctx)->seek(ctx, 0, SEEK_CUR)

/**
 * \def MGUI_RWread(ctx, ptr, size, n)
 * \brief Reads data blocks from a data source.
 *
 * This macro reads up to \a n objects each of size \a size from the data
 * source \a ctx to the area pointed to by \a ptr.
 *
 * \param ctx The pointer to the MG_RWops object.
 * \param ptr The buffer will save the data read.
 * \param size The size of each object.
 * \param n The number of objects to be read.
 * \return The number of objects read, or -1 if the read failed.
 *
 * \sa MGUI_RWwrite
 */
#define MGUI_RWread(ctx, ptr, size, n)      (ctx)->read(ctx, ptr, size, n)

/**
 * \def MGUI_RWwrite(ctx, ptr, size, n)
 * \brief Writes data blocks to a data source.
 *
 * This macro writes exactly \a n objects each of size \a size from the area
 * pointed to by \a ptr to the data source \a ctx.
 *
 * \param ctx The pointer to the MG_RWops object.
 * \param ptr The buffer contains the data to be written.
 * \param size The size of each object.
 * \param n The number of objects to be written.
 * \return The number written, or -1 if the write failed.
 *
 * \sa MGUI_RWread
 */
#define MGUI_RWwrite(ctx, ptr, size, n)     (ctx)->write(ctx, ptr, size, n)

/**
 * \def MGUI_RWclose(ctx)
 * \brief Closes an MG_RWops object.
 *
 * This macro close the MG_RWops object pointed to by \a ctx.
 *
 * \param ctx The pointer to the MG_RWops object.
 * \return Upon successful completion 0 is returned, otherwise non-zero on error.
 *
 * \sa MGUI_RWread
 */
#define MGUI_RWclose(ctx)                   (ctx)->close(ctx)

/**
 * \def MGUI_RWeof(ctx)
 * \brief Tests the end-of-file indicator for an data source.
 *
 * This macro tests the end-of-file indicator for the data source pointed to by \a ctx.
 *
 * \param ctx The pointer to the MG_RWops object.
 * \return Non-zero if end-of-file indicator is set.
 *
 * \sa MGUI_RWtell
 */
#define MGUI_RWeof(ctx)                     (ctx)->eof(ctx)

/**
 * \fn int MGUI_RWgetc (MG_RWops* area)
 * \brief Reads the next character from an data source.
 *
 * This function reads the next character from the data source pointed to by \a area,
 * and returns it as an \a unsigned char cast to an \a int, or \a EOF on end of file
 * or error.
 *
 * \param area The pointer to the MG_RWops object.
 * \return The character read, \a EOF indicates end-of-file or error.
 *
 * \sa MGUI_RWread
 */
int MGUI_RWgetc (MG_RWops* area);

    /** @} end of general_rw_fns */

/****************** Endian specific read/write interfaces *********************/

    /**
     * \defgroup endian_rw_fns Endian specific read/write interfaces
     *
     * The endian specific read/write functions read and write data
     * of the specified endianness, dynamically translating to 
     * the host machine endianness.
     *
     * e.g.: If you want to read a 16 bit value on big-endian machine from
     * an opened file containing little endian values, you would use:
     *
     * \code
     *  value = MGUI_ReadLE16(rp);
     * \endcode
     *
     * \sa general_rw_fns
     *
     * Example:
     *
     * \include endianness.c
     * @{
     */

/* The macros used to swap values */
/* Try to use superfast macros on systems that support them */
#ifdef linux
#include <endian.h>
#ifdef __arch__swab16
#define ArchSwap16  __arch__swab16
#endif
#ifdef __arch__swab32
#define ArchSwap32  __arch__swab32