include/SDL_rwops.h
author Eli Gottlieb <eligottlieb@gmail.com>
Sun, 23 May 2010 01:27:09 -0400
changeset 4767 dc3fd9b7fcbc
parent 3697 f7b03b6838cb
child 4864 ebcb4988b16f
permissions -rw-r--r--
I'm actually going to have to alter this proposed API a fair bit, but it's coming along. I want to keep it as orthogonal to the rest of SDL as possible.
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2010 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 maxnum objects each of size \c size 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 #else
   135 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp,
   136                                                 SDL_bool autoclose);
   137 #endif
   138 
   139 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
   140 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
   141                                                       int size);
   142 
   143 /*@}*//*RWFrom functions*/
   144 
   145 
   146 extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
   147 extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
   148 
   149 #define RW_SEEK_SET	0       /**< Seek from the beginning of data */
   150 #define RW_SEEK_CUR	1       /**< Seek relative to current read point */
   151 #define RW_SEEK_END	2       /**< Seek relative to the end of data */
   152 
   153 /**
   154  *  \name Read/write macros
   155  *  
   156  *  Macros to easily read and write from an SDL_RWops structure.
   157  */
   158 /*@{*/
   159 #define SDL_RWseek(ctx, offset, whence)	(ctx)->seek(ctx, offset, whence)
   160 #define SDL_RWtell(ctx)			(ctx)->seek(ctx, 0, RW_SEEK_CUR)
   161 #define SDL_RWread(ctx, ptr, size, n)	(ctx)->read(ctx, ptr, size, n)
   162 #define SDL_RWwrite(ctx, ptr, size, n)	(ctx)->write(ctx, ptr, size, n)
   163 #define SDL_RWclose(ctx)		(ctx)->close(ctx)
   164 /*@}*//*Read/write macros*/
   165 
   166 
   167 /** 
   168  *  \name Read endian functions
   169  *  
   170  *  Read an item of the specified endianness and return in native format.
   171  */
   172 /*@{*/
   173 extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
   174 extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
   175 extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
   176 extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
   177 extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
   178 extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
   179 /*@}*//*Read endian functions*/
   180 
   181 /** 
   182  *  \name Write endian functions
   183  *  
   184  *  Write an item of native format to the specified endianness.
   185  */
   186 /*@{*/
   187 extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
   188 extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
   189 extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
   190 extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
   191 extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
   192 extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
   193 /*@}*//*Write endian functions*/
   194 
   195 
   196 /* Ends C function definitions when using C++ */
   197 #ifdef __cplusplus
   198 /* *INDENT-OFF* */
   199 }
   200 /* *INDENT-ON* */
   201 #endif
   202 #include "close_code.h"
   203 
   204 #endif /* _SDL_rwops_h */
   205 
   206 /* vi: set ts=4 sw=4 expandtab: */