include/SDL_test_random.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 8149 681eb46b8ac4
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).
aschiffler@6699
     1
/*
aschiffler@6699
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
aschiffler@6699
     4
aschiffler@6699
     5
  This software is provided 'as-is', without any express or implied
aschiffler@6699
     6
  warranty.  In no event will the authors be held liable for any damages
aschiffler@6699
     7
  arising from the use of this software.
aschiffler@6699
     8
aschiffler@6699
     9
  Permission is granted to anyone to use this software for any purpose,
aschiffler@6699
    10
  including commercial applications, and to alter it and redistribute it
aschiffler@6699
    11
  freely, subject to the following restrictions:
aschiffler@6699
    12
aschiffler@6699
    13
  1. The origin of this software must not be misrepresented; you must not
aschiffler@6699
    14
     claim that you wrote the original software. If you use this software
aschiffler@6699
    15
     in a product, an acknowledgment in the product documentation would be
aschiffler@6699
    16
     appreciated but is not required.
aschiffler@6699
    17
  2. Altered source versions must be plainly marked as such, and must not be
aschiffler@6699
    18
     misrepresented as being the original software.
aschiffler@6699
    19
  3. This notice may not be removed or altered from any source distribution.
aschiffler@6699
    20
*/
aschiffler@6699
    21
aschiffler@6699
    22
/**
aschiffler@6699
    23
 *  \file SDL_test_random.h
slouken@7191
    24
 *
aschiffler@6699
    25
 *  Include file for SDL test framework.
aschiffler@6699
    26
 *
aschiffler@6699
    27
 *  This code is a part of the SDL2_test library, not the main SDL library.
aschiffler@6699
    28
 */
aschiffler@6699
    29
slouken@7191
    30
/*
aschiffler@6699
    31
slouken@7191
    32
 A "32-bit Multiply with carry random number generator. Very fast.
slouken@7191
    33
 Includes a list of recommended multipliers.
aschiffler@6699
    34
aschiffler@6699
    35
 multiply-with-carry generator: x(n) = a*x(n-1) + carry mod 2^32.
aschiffler@6699
    36
 period: (a*2^31)-1
slouken@7191
    37
aschiffler@6699
    38
*/
aschiffler@6699
    39
aschiffler@6699
    40
#ifndef _SDL_test_random_h
aschiffler@6699
    41
#define _SDL_test_random_h
aschiffler@6699
    42
aschiffler@6699
    43
#include "begin_code.h"
aschiffler@6699
    44
/* Set up for C function definitions, even when using C++ */
aschiffler@6699
    45
#ifdef __cplusplus
aschiffler@6699
    46
extern "C" {
aschiffler@6699
    47
#endif
aschiffler@6699
    48
aschiffler@6713
    49
/* --- Definitions */
aschiffler@6699
    50
aschiffler@6699
    51
/*
aschiffler@6711
    52
 * Macros that return a random number in a specific format.
aschiffler@6699
    53
 */
slouken@7191
    54
#define SDLTest_RandomInt(c)        ((int)SDLTest_Random(c))
aschiffler@6699
    55
aschiffler@6699
    56
/*
aschiffler@6699
    57
 * Context structure for the random number generator state.
aschiffler@6699
    58
 */
aschiffler@6699
    59
  typedef struct {
aschiffler@6699
    60
    unsigned int a;
aschiffler@6699
    61
    unsigned int x;
aschiffler@6699
    62
    unsigned int c;
aschiffler@6699
    63
    unsigned int ah;
aschiffler@6699
    64
    unsigned int al;
aschiffler@6699
    65
  } SDLTest_RandomContext;
aschiffler@6699
    66
aschiffler@6713
    67
aschiffler@6713
    68
/* --- Function prototypes */
aschiffler@6699
    69
aschiffler@6699
    70
/**
slouken@7191
    71
 *  \brief Initialize random number generator with two integers.
aschiffler@6699
    72
 *
aschiffler@6713
    73
 *  Note: The random sequence of numbers returned by ...Random() is the
aschiffler@6713
    74
 *  same for the same two integers and has a period of 2^31.
aschiffler@6699
    75
 *
aschiffler@6699
    76
 *  \param rndContext     pointer to context structure
aschiffler@6699
    77
 *  \param xi         integer that defines the random sequence
aschiffler@6699
    78
 *  \param ci         integer that defines the random sequence
aschiffler@6699
    79
 *
aschiffler@6699
    80
 */
aschiffler@6699
    81
 void SDLTest_RandomInit(SDLTest_RandomContext * rndContext, unsigned int xi,
slouken@7191
    82
                  unsigned int ci);
aschiffler@6699
    83
aschiffler@6699
    84
/**
slouken@7191
    85
 *  \brief Initialize random number generator based on current system time.
aschiffler@6699
    86
 *
aschiffler@6699
    87
 *  \param rndContext     pointer to context structure
aschiffler@6699
    88
 *
aschiffler@6699
    89
 */
aschiffler@6699
    90
 void SDLTest_RandomInitTime(SDLTest_RandomContext *rndContext);
aschiffler@6699
    91
aschiffler@6699
    92
aschiffler@6699
    93
/**
slouken@7191
    94
 *  \brief Initialize random number generator based on current system time.
aschiffler@6699
    95
 *
aschiffler@6713
    96
 *  Note: ...RandomInit() or ...RandomInitTime() must have been called
aschiffler@6713
    97
 *  before using this function.
aschiffler@6699
    98
 *
aschiffler@6699
    99
 *  \param rndContext     pointer to context structure
aschiffler@6699
   100
 *
aschiffler@6699
   101
 *  \returns A random number (32bit unsigned integer)
aschiffler@6699
   102
 *
aschiffler@6699
   103
 */
aschiffler@6699
   104
 unsigned int SDLTest_Random(SDLTest_RandomContext *rndContext);
aschiffler@6699
   105
aschiffler@6699
   106
aschiffler@6699
   107
/* Ends C function definitions when using C++ */
aschiffler@6699
   108
#ifdef __cplusplus
aschiffler@6699
   109
}
aschiffler@6699
   110
#endif
aschiffler@6699
   111
#include "close_code.h"
aschiffler@6699
   112
aschiffler@6699
   113
#endif /* _SDL_test_random_h */
aschiffler@6699
   114
aschiffler@6699
   115
/* vi: set ts=4 sw=4 expandtab: */