include/SDL_rwops.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 8850 7e248a233387
child 9619 b94b6d0bff0f
permissions -rw-r--r--
WinRT: bug and data-integrity fixes for SDL_GetPrefPath()

This change does a few things, all with regards to the WinRT implementation of
SDL_GetPrefPath():

1. it fixes a bug whereby SDL_GetPrefPath() did not create the directory it
returned. On other SDL platforms, SDL_GetPrefPath() will create separate
directories for its 'org' and 'app' folders. Without this, attempts to create
files in the pref-path would fail, unless those directories were first created
by the app, or by some other library the app used. This change makes sure
that these directories get created, before SDL_GetPrefPath() returns to its
caller(s).


2. it defaults to having SDL_GetPrefPath() return a WinRT 'Local' folder
on all platforms. Previously, for Windows Store apps, it would have used a
different, 'Roaming' folder. Files in Roaming folders can be automatically,
and synchronized across multiple devices by Windows. This synchronization can
happen while the app runs, with new files being copied into a running app's
pref-path. Unless an app is specifically designed to handle this scenario,
there is a chance that save-data could be overwritten in unwanted or
unexpected ways.

The default is now to use a Local folder, which does not get synchronized, and
which is arguably a bit safer to use. Apps that wish to use Roaming folders
can do so by setting SDL_HINT_WINRT_PREF_PATH_ROOT to "roaming", however it
is recommended that one first read Microsoft's documentation for Roaming
files, a link to which is provided in README-winrt.md.

To preserve older pref-path selection behavior (found in SDL 2.0.3, as well as
many pre-2.0.4 versions of SDL from hg.libsdl.org), which uses a Roaming path
in Windows Store apps, and a Local path in Windows Phone, set
SDL_HINT_WINRT_PREF_PATH_ROOT to "old".

Please note that Roaming paths are not supported on Windows Phone 8.0, due to
limitations in the OS itself. Attempts to use this will fail.
(Windows Phone 8.1 does not have this limitation, however.)


3. It makes SDL_GetPrefPath(), when on Windows Phone 8.0, and when
SDL_HINT_WINRT_PREF_PATH_ROOT is set to "roaming", return NULL, rather than
silently defaulting to a Local path (then switching to a Roaming path if and
when the user upgraded to Windows Phone 8.1).
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
slouken@0
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@0
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@0
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@0
    20
*/
slouken@0
    21
slouken@1895
    22
/**
slouken@3407
    23
 *  \file SDL_rwops.h
slouken@7191
    24
 *
slouken@3407
    25
 *  This file provides a general interface for SDL to read and write
slouken@4971
    26
 *  data streams.  It can easily be extended to files, memory, etc.
slouken@1895
    27
 */
slouken@0
    28
slouken@1402
    29
#ifndef _SDL_rwops_h
slouken@1402
    30
#define _SDL_rwops_h
slouken@0
    31
slouken@1354
    32
#include "SDL_stdinc.h"
slouken@1358
    33
#include "SDL_error.h"
slouken@1330
    34
slouken@0
    35
#include "begin_code.h"
slouken@0
    36
/* Set up for C function definitions, even when using C++ */
slouken@0
    37
#ifdef __cplusplus
slouken@0
    38
extern "C" {
slouken@0
    39
#endif
slouken@0
    40
aschiffler@6999
    41
/* RWops Types */
slouken@7191
    42
#define SDL_RWOPS_UNKNOWN   0   /* Unknown stream type */
slouken@7191
    43
#define SDL_RWOPS_WINFILE   1   /* Win32 file */
slouken@7191
    44
#define SDL_RWOPS_STDFILE   2   /* Stdio file */
slouken@7191
    45
#define SDL_RWOPS_JNIFILE   3   /* Android asset */
slouken@7191
    46
#define SDL_RWOPS_MEMORY    4   /* Memory stream */
slouken@7191
    47
#define SDL_RWOPS_MEMORY_RO 5   /* Read-Only memory stream */
aschiffler@6999
    48
slouken@3407
    49
/**
slouken@3407
    50
 * This is the read/write operation structure -- very basic.
slouken@3407
    51
 */
slouken@1895
    52
typedef struct SDL_RWops
slouken@1895
    53
{
slouken@3407
    54
    /**
slouken@6642
    55
     *  Return the size of the file in this rwops, or -1 if unknown
slouken@6642
    56
     */
slouken@6642
    57
    Sint64 (SDLCALL * size) (struct SDL_RWops * context);
slouken@6642
    58
slouken@6642
    59
    /**
slouken@3407
    60
     *  Seek to \c offset relative to \c whence, one of stdio's whence values:
slouken@3407
    61
     *  RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
slouken@7191
    62
     *
aschiffler@6996
    63
     *  \return the final offset in the data stream, or -1 on error.
slouken@1895
    64
     */
slouken@6642
    65
    Sint64 (SDLCALL * seek) (struct SDL_RWops * context, Sint64 offset,
slouken@6642
    66
                             int whence);
slouken@0
    67
slouken@3407
    68
    /**
icculus@3614
    69
     *  Read up to \c maxnum objects each of size \c size from the data
slouken@4971
    70
     *  stream to the area pointed at by \c ptr.
slouken@7191
    71
     *
slouken@3407
    72
     *  \return the number of objects read, or 0 at error or end of file.
slouken@1895
    73
     */
slouken@6642
    74
    size_t (SDLCALL * read) (struct SDL_RWops * context, void *ptr,
slouken@6642
    75
                             size_t size, size_t maxnum);
slouken@0
    76
slouken@3407
    77
    /**
slouken@4864
    78
     *  Write exactly \c num objects each of size \c size from the area
slouken@4971
    79
     *  pointed at by \c ptr to data stream.
slouken@7191
    80
     *
slouken@3407
    81
     *  \return the number of objects written, or 0 at error or end of file.
slouken@1895
    82
     */
slouken@6642
    83
    size_t (SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
slouken@6642
    84
                              size_t size, size_t num);
slouken@0
    85
slouken@3407
    86
    /**
slouken@3407
    87
     *  Close and free an allocated SDL_RWops structure.
slouken@7191
    88
     *
slouken@3407
    89
     *  \return 0 if successful or -1 on write error when flushing data.
slouken@2160
    90
     */
slouken@1895
    91
    int (SDLCALL * close) (struct SDL_RWops * context);
slouken@0
    92
slouken@1895
    93
    Uint32 type;
slouken@1895
    94
    union
slouken@1895
    95
    {
dimitris@8761
    96
#if defined(__ANDROID__)
icculus@5582
    97
        struct
icculus@5582
    98
        {
icculus@5582
    99
            void *fileNameRef;
icculus@5582
   100
            void *inputStreamRef;
icculus@5582
   101
            void *readableByteChannelRef;
icculus@5582
   102
            void *readMethod;
gabomdq@6806
   103
            void *assetFileDescriptorRef;
icculus@5582
   104
            long position;
gabomdq@6806
   105
            long size;
gabomdq@6806
   106
            long offset;
gabomdq@6806
   107
            int fd;
icculus@5582
   108
        } androidio;
icculus@5582
   109
#elif defined(__WIN32__)
slouken@1895
   110
        struct
slouken@1895
   111
        {
slouken@2160
   112
            SDL_bool append;
slouken@1895
   113
            void *h;
slouken@2159
   114
            struct
slouken@2159
   115
            {
slouken@2159
   116
                void *data;
slouken@3253
   117
                size_t size;
slouken@3253
   118
                size_t left;
slouken@2159
   119
            } buffer;
slouken@5062
   120
        } windowsio;
slouken@1447
   121
#endif
icculus@5582
   122
slouken@1895
   123
#ifdef HAVE_STDIO_H
slouken@1895
   124
        struct
slouken@1895
   125
        {
slouken@2160
   126
            SDL_bool autoclose;
slouken@1895
   127
            FILE *fp;
slouken@1895
   128
        } stdio;
slouken@1330
   129
#endif
slouken@1895
   130
        struct
slouken@1895
   131
        {
slouken@1895
   132
            Uint8 *base;
slouken@1895
   133
            Uint8 *here;
slouken@1895
   134
            Uint8 *stop;
slouken@1895
   135
        } mem;
slouken@1895
   136
        struct
slouken@1895
   137
        {
slouken@1895
   138
            void *data1;
icculus@7064
   139
            void *data2;
slouken@1895
   140
        } unknown;
slouken@1895
   141
    } hidden;
slouken@0
   142
slouken@0
   143
} SDL_RWops;
slouken@0
   144
slouken@0
   145
slouken@3407
   146
/**
slouken@3407
   147
 *  \name RWFrom functions
slouken@7191
   148
 *
slouken@4971
   149
 *  Functions to create SDL_RWops structures from various data streams.
slouken@3407
   150
 */
gabomdq@7678
   151
/* @{ */
slouken@0
   152
slouken@1895
   153
extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
slouken@1895
   154
                                                  const char *mode);
slouken@0
   155
slouken@1330
   156
#ifdef HAVE_STDIO_H
slouken@2161
   157
extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp,
slouken@2161
   158
                                                SDL_bool autoclose);
slouken@3564
   159
#else
slouken@3564
   160
extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp,
slouken@3564
   161
                                                SDL_bool autoclose);
slouken@1330
   162
#endif
slouken@0
   163
slouken@1895
   164
extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
slouken@1895
   165
extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
slouken@1895
   166
                                                      int size);
slouken@0
   167
gabomdq@7678
   168
/* @} *//* RWFrom functions */
slouken@3407
   169
slouken@3407
   170
slouken@1895
   171
extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
slouken@1895
   172
extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
slouken@0
   173
slouken@7191
   174
#define RW_SEEK_SET 0       /**< Seek from the beginning of data */
slouken@7191
   175
#define RW_SEEK_CUR 1       /**< Seek relative to current read point */
slouken@7191
   176
#define RW_SEEK_END 2       /**< Seek relative to the end of data */
slouken@1330
   177
slouken@3407
   178
/**
slouken@3407
   179
 *  \name Read/write macros
slouken@7191
   180
 *
slouken@3407
   181
 *  Macros to easily read and write from an SDL_RWops structure.
slouken@3407
   182
 */
gabomdq@7678
   183
/* @{ */
slouken@7191
   184
#define SDL_RWsize(ctx)         (ctx)->size(ctx)
slouken@7191
   185
#define SDL_RWseek(ctx, offset, whence) (ctx)->seek(ctx, offset, whence)
slouken@7191
   186
#define SDL_RWtell(ctx)         (ctx)->seek(ctx, 0, RW_SEEK_CUR)
slouken@7191
   187
#define SDL_RWread(ctx, ptr, size, n)   (ctx)->read(ctx, ptr, size, n)
slouken@7191
   188
#define SDL_RWwrite(ctx, ptr, size, n)  (ctx)->write(ctx, ptr, size, n)
slouken@7191
   189
#define SDL_RWclose(ctx)        (ctx)->close(ctx)
gabomdq@7678
   190
/* @} *//* Read/write macros */
slouken@0
   191
slouken@0
   192
slouken@7191
   193
/**
slouken@3407
   194
 *  \name Read endian functions
slouken@7191
   195
 *
slouken@3407
   196
 *  Read an item of the specified endianness and return in native format.
slouken@3407
   197
 */
gabomdq@7678
   198
/* @{ */
slouken@6655
   199
extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src);
slouken@1895
   200
extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
slouken@1895
   201
extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
slouken@1895
   202
extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
slouken@1895
   203
extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
slouken@1895
   204
extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
slouken@1895
   205
extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
gabomdq@7678
   206
/* @} *//* Read endian functions */
slouken@1354
   207
slouken@7191
   208
/**
slouken@3407
   209
 *  \name Write endian functions
slouken@7191
   210
 *
slouken@3407
   211
 *  Write an item of native format to the specified endianness.
slouken@3407
   212
 */
gabomdq@7678
   213
/* @{ */
slouken@6655
   214
extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value);
slouken@3253
   215
extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
slouken@3253
   216
extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
slouken@3253
   217
extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
slouken@3253
   218
extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
slouken@3253
   219
extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
slouken@3253
   220
extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
gabomdq@7678
   221
/* @} *//* Write endian functions */
slouken@1354
   222
slouken@0
   223
/* Ends C function definitions when using C++ */
slouken@0
   224
#ifdef __cplusplus
slouken@0
   225
}
slouken@0
   226
#endif
slouken@0
   227
#include "close_code.h"
slouken@0
   228
slouken@1402
   229
#endif /* _SDL_rwops_h */
slouken@1895
   230
slouken@1895
   231
/* vi: set ts=4 sw=4 expandtab: */