endianrw.h

usoc在北京博创兴业有限公司的实验平台s3c2410上运行。 2. 各实验的全部源代码分别存放在各实验目录下面。

/**
 * \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-2003 Feynman Software.

    This file is part of MiniGUI, a lightweight Graphics User Interface
    support library for real-time embedded Linux.

    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.18 2004/02/28 08:31:27 weiym Exp $
 * 
 *             MiniGUI for Linux, uClinux, eCos, and uC/OS-II version 1.5.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
#endif
#endif /* linux */

/* Use inline functions for compilers that support them, and static
   functions for those that do not.  Because these functions become
   static for compilers that do not support inline functions, this
   header should only be included in files that actually use them.
*/