WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
authorDavid Ludwig <dludwig@pobox.com>
Tue, 02 Dec 2014 21:18:50 -0500
changeset 9255c2ef0d8d6da0
parent 9254 6c469ea796e4
child 9256 9c45fc8605d9
child 11072 4d8984d051a2
WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)

A WinRT app's Roaming folder-path can still be retrieved via calls to
SDL_WinRTGetFSPathUTF8() or SDL_WinRTGetFSPathUNICODE(), if need be.
docs/README-winrt.md
include/SDL_hints.h
src/filesystem/winrt/SDL_sysfilesystem.cpp
     1.1 --- a/docs/README-winrt.md	Sun Nov 30 20:55:27 2014 -0800
     1.2 +++ b/docs/README-winrt.md	Tue Dec 02 21:18:50 2014 -0500
     1.3 @@ -116,29 +116,28 @@
     1.4  
     1.5  
     1.6  
     1.7 -Caveats
     1.8 --------
     1.9 +Upgrade Notes
    1.10 +-------------
    1.11  
    1.12 -#### SDL_GetPrefPath() usage when upgrading existing WinRT apps to SDL 2.0.4
    1.13 +#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
    1.14  
    1.15 -SDL 2.0.4 fixes two bugs found in SDL_GetPrefPath() which can affect
    1.16 -an app's save data.  These bugs only apply to WinRT apps (and not
    1.17 -Windows Desktop / Win32 apps, or to apps on any other SDL platform).
    1.18 -In particular, for older versions of SDL (anything before 2.0.4):
    1.19 +SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
    1.20 +The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
    1.21 +that these changes only apply to SDL-based WinRT apps, and not to apps for
    1.22 +any other platform.
    1.23  
    1.24 -1. SDL_GetPrefPath() would return an invalid path, one in which attempts
    1.25 -   to write files to would fail, in many cases.  Some of the path elements
    1.26 -   returned by SDL_GetPrefPath() would not get created (as done on other
    1.27 -   SDL platforms).  Files could be written to this path, however apps would
    1.28 -   need to explicitly create the missing directories first.
    1.29 -   
    1.30 -2. SDL_GetPrefPath() would return a path inside a WinRT 'Roaming' folder,
    1.31 -   the contents of which could get automatically synchronized across multiple
    1.32 -   devices, by Windows.  This process could occur while an app was running.
    1.33 -   Apps which were not explicitly built to handle this scenario could
    1.34 -   have their SDL_GetPrefPath-backed save data swapped out by Windows at
    1.35 -   unexpected times, which raised potential for data-loss (if apps weren't
    1.36 -   designed to support live file-synchronization.)
    1.37 +1. SDL_GetPrefPath() would return an invalid path, one in which the path's
    1.38 +   directory had not been created.  Attempts to create files there
    1.39 +   (via fopen(), for example), would fail, unless that directory was
    1.40 +   explicitly created beforehand.
    1.41 +
    1.42 +2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
    1.43 +   a WinRT 'Roaming' folder, the contents of which get automatically
    1.44 +   synchronized across multiple devices.  This process can occur while an
    1.45 +   application runs, and can cause existing save-data to be overwritten
    1.46 +   at unexpected times, with data from other devices.  (Windows Phone apps
    1.47 +   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
    1.48 +   restrictions in Windows Phone 8.0).
    1.49  
    1.50  
    1.51  SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
    1.52 @@ -146,37 +145,14 @@
    1.53  1. making sure that SDL_GetPrefPath() returns a directory in which data
    1.54     can be written to immediately, without first needing to create directories.
    1.55  
    1.56 -2. basing SDL_GetPrefPath() off of a non-Roaming / 'Local' folder, the
    1.57 -   contents of which do not get automatically synchronized across devices,
    1.58 -   and which may be safer in terms of data-integrity.
    1.59 -   
    1.60 -   Apps can, at their discretion, choose to utilize WinRT's Roaming
    1.61 -   functionality by calling the following before calling SDL_GetPrefPath():
    1.62 -   
    1.63 -       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "roaming");
    1.64 +2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
    1.65 +   contents of which do not automatically get synchronized across devices
    1.66 +   (and which require less work to use safely, in terms of data integrity).
    1.67  
    1.68 -   Alternatively, to restore SDL_GetPrefPath()'s old behavior (found in
    1.69 -   SDL 2.0.3, and in many pre-2.0.4 versions of SDL found on hg.libsdl.org),
    1.70 -   whereby a Roaming path is returned for Windows Store apps, and a Local
    1.71 -   folder is returned for Windows Phone apps, use the following code:
    1.72 -   
    1.73 -       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "old");
    1.74 -   
    1.75 -   Before using Roaming data in any capacity, it is highly recommended that
    1.76 -   one read the following:
    1.77 -   
    1.78 -   1. Microsoft's documentation on the Roaming data.  Details on this can be
    1.79 -      found on MSDN, at:
    1.80 -      [Guidelines for roaming app data](http://msdn.microsoft.com/en-us/library/windows/apps/hh465094.aspx).
    1.81 -   
    1.82 -   2. the SDL documentation for SDL_HINT_WINRT_PREF_PATH_ROOT, which is
    1.83 -      listed inside SDL_hints.h.
    1.84 -
    1.85 -   Please note that Roaming support is not available on Windows Phone 8.0,
    1.86 -   due to limitations in the OS itself.  Attempts to use it will fail, with
    1.87 -   SDL_GetPrefPath() returning NULL (if SDL_HINT_WINRT_PREF_PATH_ROOT is
    1.88 -   set to "roaming" on that platform).  Windows Phone 8.1 does not have this
    1.89 -   limitation, and does support Roaming data.
    1.90 +Apps that wish to get their Roaming folder's path can do so either by using
    1.91 +SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
    1.92 +UCS-2/wide-char string), or directly through the WinRT class,
    1.93 +Windows.Storage.ApplicationData.
    1.94  
    1.95  
    1.96  
     2.1 --- a/include/SDL_hints.h	Sun Nov 30 20:55:27 2014 -0800
     2.2 +++ b/include/SDL_hints.h	Tue Dec 02 21:18:50 2014 -0500
     2.3 @@ -492,36 +492,6 @@
     2.4  #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"
     2.5  
     2.6  /**
     2.7 - *  \brief  A variable that dictates what SDL_GetPrefPath() returns in WinRT apps.
     2.8 - *
     2.9 - *  The variable can be set to the following values:
    2.10 - *   * "local"   - Use the app's 'local' folder to store data.
    2.11 - *   * "roaming" - Use the app's 'roaming' folder to store data.
    2.12 - *                 On Windows Phone 8.0, this setting is not supported due to
    2.13 - *                 limitations in the OS itself.  Attempts to use this (via
    2.14 - *                 SDL_GetPrefPath()) on Windows Phone 8.0 will fail, with
    2.15 - *                 SDL_GetPrefPath() returning NULL.  (Windows Phone 8.1 does,
    2.16 - *                 however, support roaming folders.)
    2.17 - *   * "old"     - Use the app's 'local' folder on Windows Phone, and 'roaming'
    2.18 - *                 on non-Phone versions of WinRT.  This mimics behavior found
    2.19 - *                 in SDL 2.0.3's implementation of SDL_GetPrefPath() for WinRT
    2.20 - *                 (and was changed for SDL 2.0.4, further details of which are
    2.21 - *                 in the "Caveats" section of SDL's
    2.22 - *                 [WinRT README file](README-winrt.md).
    2.23 - *
    2.24 - *  The default is to use the app's "local" folder.
    2.25 - *
    2.26 - *  Details on 'local' verses 'roaming' folders can be found on MSDN, in
    2.27 - *  the documentation for WinRT's Windows.Storage.ApplicationData class,
    2.28 - *  (available at http://msdn.microsoft.com/en-us/library/windows/apps/windows.storage.applicationdata ).
    2.29 - *
    2.30 - *  The application's local and roaming paths may, alternatively, be retrieved
    2.31 - *  via the SDL_WinRTGetFSPathUTF8() and SDL_WinRTGetFSPathUNICODE() functions,
    2.32 - *  which are defined in SDL_system.h.
    2.33 - */
    2.34 -#define SDL_HINT_WINRT_PREF_PATH_ROOT "SDL_WINRT_PREF_PATH_ROOT"
    2.35 -
    2.36 -/**
    2.37   *  \brief  A variable that dictates policy for fullscreen Spaces on Mac OS X.
    2.38   *
    2.39   *  This hint only applies to Mac OS X.
     3.1 --- a/src/filesystem/winrt/SDL_sysfilesystem.cpp	Sun Nov 30 20:55:27 2014 -0800
     3.2 +++ b/src/filesystem/winrt/SDL_sysfilesystem.cpp	Tue Dec 02 21:18:50 2014 -0500
     3.3 @@ -144,49 +144,6 @@
     3.4       * without violating Microsoft's app-store requirements.
     3.5       */
     3.6  
     3.7 -    /* Default to using a Local/non-Roaming path.  WinRT will often attempt
     3.8 -     * to synchronize files in Roaming paths, and will do so while an app is
     3.9 -     * running.  Using a Local path prevents the possibility that an app's
    3.10 -     * save-data files will get changed from underneath it, without it
    3.11 -     * being ready.
    3.12 -     *
    3.13 -     * This behavior can be changed via use of the
    3.14 -     * SDL_HINT_WINRT_PREF_PATH_ROOT hint.
    3.15 -     */
    3.16 -    SDL_WinRT_Path pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
    3.17 -
    3.18 -    const char * hint = SDL_GetHint(SDL_HINT_WINRT_PREF_PATH_ROOT);
    3.19 -    if (hint) {
    3.20 -        if (SDL_strcasecmp(hint, "local") == 0) {
    3.21 -            pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
    3.22 -        } else if (SDL_strcasecmp(hint, "roaming") == 0) {
    3.23 -#if (WINAPI_FAMILY != WINAPI_FAMILY_PHONE_APP) || (NTDDI_VERSION > NTDDI_WIN8)
    3.24 -            pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
    3.25 -#else
    3.26 -            /* Don't apply a 'Roaming' path on Windows Phone 8.0.  Roaming
    3.27 -             * data is not supported by that version of the operating system.
    3.28 -             */
    3.29 -            SDL_SetError("A Roaming path was specified via SDL_HINT_WINRT_PREF_PATH_ROOT, but Roaming is not supported on Windows Phone 8.0");
    3.30 -            return NULL;
    3.31 -#endif
    3.32 -        } else if (SDL_strcasecmp(hint, "old") == 0) {
    3.33 -            /* Older versions of SDL/WinRT, including 2.0.3, would return a
    3.34 -             * pref-path that used a Roaming folder on non-Phone versions of
    3.35 -             * Windows, such as Windows 8.0 and Windows 8.1.  This has since
    3.36 -             * been reverted to using a Local folder, in order to prevent
    3.37 -             * problems arising from WinRT automatically synchronizing files
    3.38 -             * during an app's lifetime.  In case this functionality is
    3.39 -             * desired, setting SDL_HINT_WINRT_PREF_PATH_ROOT to "old" will
    3.40 -             * trigger the older behavior.
    3.41 -             */
    3.42 -#if WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP
    3.43 -            pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
    3.44 -#else
    3.45 -            pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
    3.46 -#endif
    3.47 -        }
    3.48 -    }
    3.49 -
    3.50      const WCHAR * srcPath = NULL;
    3.51      WCHAR path[MAX_PATH];
    3.52      char *retval = NULL;
    3.53 @@ -195,7 +152,7 @@
    3.54      size_t new_wpath_len = 0;
    3.55      BOOL api_result = FALSE;
    3.56  
    3.57 -    srcPath = SDL_WinRTGetFSPathUNICODE(pathType);
    3.58 +    srcPath = SDL_WinRTGetFSPathUNICODE(SDL_WINRT_PATH_LOCAL_FOLDER);
    3.59      if ( ! srcPath) {
    3.60          SDL_SetError("Unable to find a source path");
    3.61          return NULL;