include/SDL_rwops.h
author Sam Lantinga <slouken@libsdl.org>
Mon, 19 Oct 2009 13:31:58 +0000
changeset 3407 d3baf5ac4e37
parent 3253 5d7ef5970073
child 3564 d264d99576c1
permissions -rw-r--r--
Partial fix for bug #859

Header file update from Ken for improved doxygen output
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2009 Sam Lantinga
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21 */
    22 
    23 /**
    24  *  \file SDL_rwops.h
    25  *  
    26  *  This file provides a general interface for SDL to read and write
    27  *  data sources.  It can easily be extended to files, memory, etc.
    28  */
    29 
    30 #ifndef _SDL_rwops_h
    31 #define _SDL_rwops_h
    32 
    33 #include "SDL_stdinc.h"
    34 #include "SDL_error.h"
    35 
    36 #include "begin_code.h"
    37 /* Set up for C function definitions, even when using C++ */
    38 #ifdef __cplusplus
    39 /* *INDENT-OFF* */
    40 extern "C" {
    41 /* *INDENT-ON* */
    42 #endif
    43 
    44 /**
    45  * This is the read/write operation structure -- very basic.
    46  */
    47 typedef struct SDL_RWops
    48 {
    49     /**
    50      *  Seek to \c offset relative to \c whence, one of stdio's whence values:
    51      *  RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
    52      *  
    53      *  \return the final offset in the data source.
    54      */
    55     long (SDLCALL * seek) (struct SDL_RWops * context, long offset,
    56                            int whence);
    57 
    58     /**
    59      *  Read up to \c num objects each of size \c objsize from the data
    60      *  source to the area pointed at by \c ptr.
    61      *  
    62      *  \return the number of objects read, or 0 at error or end of file.
    63      */
    64     size_t(SDLCALL * read) (struct SDL_RWops * context, void *ptr,
    65                             size_t size, size_t maxnum);
    66 
    67     /**
    68      *  Write exactly \c num objects each of size \c objsize from the area
    69      *  pointed at by \c ptr to data source.
    70      *  
    71      *  \return the number of objects written, or 0 at error or end of file.
    72      */
    73     size_t(SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
    74                              size_t size, size_t num);
    75 
    76     /**
    77      *  Close and free an allocated SDL_RWops structure.
    78      *  
    79      *  \return 0 if successful or -1 on write error when flushing data.
    80      */
    81     int (SDLCALL * close) (struct SDL_RWops * context);
    82 
    83     Uint32 type;
    84     union
    85     {
    86 #ifdef __WIN32__
    87         struct
    88         {
    89             SDL_bool append;
    90             void *h;
    91             struct
    92             {
    93                 void *data;
    94                 size_t size;
    95                 size_t left;
    96             } buffer;
    97         } win32io;
    98 #endif
    99 #ifdef HAVE_STDIO_H
   100         struct
   101         {
   102             SDL_bool autoclose;
   103             FILE *fp;
   104         } stdio;
   105 #endif
   106         struct
   107         {
   108             Uint8 *base;
   109             Uint8 *here;
   110             Uint8 *stop;
   111         } mem;
   112         struct
   113         {
   114             void *data1;
   115         } unknown;
   116     } hidden;
   117 
   118 } SDL_RWops;
   119 
   120 
   121 /**
   122  *  \name RWFrom functions
   123  *  
   124  *  Functions to create SDL_RWops structures from various data sources.
   125  */
   126 /*@{*/
   127 
   128 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
   129                                                   const char *mode);
   130 
   131 #ifdef HAVE_STDIO_H
   132 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp,
   133                                                 SDL_bool autoclose);
   134 #endif
   135 
   136 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
   137 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
   138                                                       int size);
   139 
   140 /*@}*//*RWFrom functions*/
   141 
   142 
   143 extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
   144 extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
   145 
   146 #define RW_SEEK_SET	0       /**< Seek from the beginning of data */
   147 #define RW_SEEK_CUR	1       /**< Seek relative to current read point */
   148 #define RW_SEEK_END	2       /**< Seek relative to the end of data */
   149 
   150 /**
   151  *  \name Read/write macros
   152  *  
   153  *  Macros to easily read and write from an SDL_RWops structure.
   154  */
   155 /*@{*/
   156 #define SDL_RWseek(ctx, offset, whence)	(ctx)->seek(ctx, offset, whence)
   157 #define SDL_RWtell(ctx)			(ctx)->seek(ctx, 0, RW_SEEK_CUR)
   158 #define SDL_RWread(ctx, ptr, size, n)	(ctx)->read(ctx, ptr, size, n)
   159 #define SDL_RWwrite(ctx, ptr, size, n)	(ctx)->write(ctx, ptr, size, n)
   160 #define SDL_RWclose(ctx)		(ctx)->close(ctx)
   161 /*@}*//*Read/write macros*/
   162 
   163 
   164 /** 
   165  *  \name Read endian functions
   166  *  
   167  *  Read an item of the specified endianness and return in native format.
   168  */
   169 /*@{*/
   170 extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
   171 extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
   172 extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
   173 extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
   174 extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
   175 extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
   176 /*@}*//*Read endian functions*/
   177 
   178 /** 
   179  *  \name Write endian functions
   180  *  
   181  *  Write an item of native format to the specified endianness.
   182  */
   183 /*@{*/
   184 extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
   185 extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
   186 extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
   187 extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
   188 extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
   189 extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
   190 /*@}*//*Write endian functions*/
   191 
   192 
   193 /* Ends C function definitions when using C++ */
   194 #ifdef __cplusplus
   195 /* *INDENT-OFF* */
   196 }
   197 /* *INDENT-ON* */
   198 #endif
   199 #include "close_code.h"
   200 
   201 #endif /* _SDL_rwops_h */
   202 
   203 /* vi: set ts=4 sw=4 expandtab: */