include/SDL.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 9023 276802355854
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.h
slouken@7191
    24
 *
slouken@3407
    25
 *  Main include header for the SDL library
slouken@1895
    26
 */
slouken@3407
    27
slouken@0
    28
slouken@0
    29
#ifndef _SDL_H
slouken@0
    30
#define _SDL_H
slouken@0
    31
slouken@1423
    32
#include "SDL_main.h"
slouken@1353
    33
#include "SDL_stdinc.h"
slouken@5347
    34
#include "SDL_assert.h"
slouken@5017
    35
#include "SDL_atomic.h"
slouken@0
    36
#include "SDL_audio.h"
slouken@4493
    37
#include "SDL_clipboard.h"
slouken@1358
    38
#include "SDL_cpuinfo.h"
slouken@1358
    39
#include "SDL_endian.h"
slouken@1358
    40
#include "SDL_error.h"
slouken@0
    41
#include "SDL_events.h"
icculus@7667
    42
#include "SDL_filesystem.h"
icculus@6918
    43
#include "SDL_joystick.h"
slouken@6690
    44
#include "SDL_gamecontroller.h"
icculus@6918
    45
#include "SDL_haptic.h"
slouken@5189
    46
#include "SDL_hints.h"
slouken@1358
    47
#include "SDL_loadso.h"
slouken@5221
    48
#include "SDL_log.h"
slouken@6602
    49
#include "SDL_messagebox.h"
slouken@1358
    50
#include "SDL_mutex.h"
icculus@3170
    51
#include "SDL_power.h"
slouken@5145
    52
#include "SDL_render.h"
slouken@1358
    53
#include "SDL_rwops.h"
slouken@6342
    54
#include "SDL_system.h"
slouken@1358
    55
#include "SDL_thread.h"
slouken@1358
    56
#include "SDL_timer.h"
slouken@3647
    57
#include "SDL_version.h"
slouken@0
    58
#include "SDL_video.h"
slouken@0
    59
slouken@0
    60
#include "begin_code.h"
slouken@0
    61
/* Set up for C function definitions, even when using C++ */
slouken@0
    62
#ifdef __cplusplus
slouken@0
    63
extern "C" {
slouken@0
    64
#endif
slouken@0
    65
slouken@0
    66
/* As of version 0.5, SDL is loaded dynamically into the application */
slouken@0
    67
slouken@3407
    68
/**
slouken@3407
    69
 *  \name SDL_INIT_*
slouken@7191
    70
 *
slouken@3407
    71
 *  These are the flags which may be passed to SDL_Init().  You should
slouken@3407
    72
 *  specify the subsystems which you will be using in your application.
slouken@3407
    73
 */
gabomdq@7678
    74
/* @{ */
slouken@2713
    75
#define SDL_INIT_TIMER          0x00000001
slouken@2713
    76
#define SDL_INIT_AUDIO          0x00000010
slouken@7360
    77
#define SDL_INIT_VIDEO          0x00000020  /**< SDL_INIT_VIDEO implies SDL_INIT_EVENTS */
slouken@7360
    78
#define SDL_INIT_JOYSTICK       0x00000200  /**< SDL_INIT_JOYSTICK implies SDL_INIT_EVENTS */
slouken@2713
    79
#define SDL_INIT_HAPTIC         0x00001000
philipp@7370
    80
#define SDL_INIT_GAMECONTROLLER 0x00002000  /**< SDL_INIT_GAMECONTROLLER implies SDL_INIT_JOYSTICK */
slouken@7360
    81
#define SDL_INIT_EVENTS         0x00004000
icculus@8999
    82
#define SDL_INIT_NOPARACHUTE    0x00100000  /**< compatibility; this flag is ignored. */
icculus@6981
    83
#define SDL_INIT_EVERYTHING ( \
slouken@7360
    84
                SDL_INIT_TIMER | SDL_INIT_AUDIO | SDL_INIT_VIDEO | SDL_INIT_EVENTS | \
icculus@6981
    85
                SDL_INIT_JOYSTICK | SDL_INIT_HAPTIC | SDL_INIT_GAMECONTROLLER \
icculus@6981
    86
            )
gabomdq@7678
    87
/* @} */
slouken@0
    88
slouken@3348
    89
/**
slouken@4863
    90
 *  This function initializes  the subsystems specified by \c flags
slouken@0
    91
 */
slouken@337
    92
extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
slouken@0
    93
slouken@3348
    94
/**
slouken@3407
    95
 *  This function initializes specific SDL subsystems
alfred@8970
    96
 *
alfred@8970
    97
 *  Subsystem initialization is ref-counted, you must call
alfred@8970
    98
 *  SDL_QuitSubSystem for each SDL_InitSubSystem to correctly
alfred@8970
    99
 *  shutdown a subsystem manually (or call SDL_Quit to force shutdown).
alfred@8970
   100
 *  If a subsystem is already loaded then this call will
alfred@8970
   101
 *  increase the ref-count and return.
slouken@3348
   102
 */
slouken@337
   103
extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
slouken@0
   104
slouken@3407
   105
/**
slouken@3407
   106
 *  This function cleans up specific SDL subsystems
slouken@3407
   107
 */
slouken@337
   108
extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
slouken@0
   109
slouken@3348
   110
/**
slouken@4627
   111
 *  This function returns a mask of the specified subsystems which have
slouken@4627
   112
 *  previously been initialized.
slouken@7191
   113
 *
slouken@3407
   114
 *  If \c flags is 0, it returns a mask of all initialized subsystems.
slouken@3407
   115
 */
slouken@337
   116
extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
slouken@0
   117
slouken@3348
   118
/**
slouken@4627
   119
 *  This function cleans up all initialized subsystems. You should
slouken@4627
   120
 *  call it upon all exit conditions.
slouken@0
   121
 */
slouken@337
   122
extern DECLSPEC void SDLCALL SDL_Quit(void);
slouken@0
   123
slouken@0
   124
/* Ends C function definitions when using C++ */
slouken@0
   125
#ifdef __cplusplus
slouken@0
   126
}
slouken@0
   127
#endif
slouken@0
   128
#include "close_code.h"
slouken@0
   129
slouken@0
   130
#endif /* _SDL_H */
slouken@1895
   131
slouken@1895
   132
/* vi: set ts=4 sw=4 expandtab: */