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

@@ -116,29 +116,28 @@ Here is a rough list of what works, and what doens't:
 
 
 
-Caveats
--------
-
-#### SDL_GetPrefPath() usage when upgrading existing WinRT apps to SDL 2.0.4
-
-SDL 2.0.4 fixes two bugs found in SDL_GetPrefPath() which can affect
-an app's save data.  These bugs only apply to WinRT apps (and not
-Windows Desktop / Win32 apps, or to apps on any other SDL platform).
-In particular, for older versions of SDL (anything before 2.0.4):
-
-1. SDL_GetPrefPath() would return an invalid path, one in which attempts
-   to write files to would fail, in many cases.  Some of the path elements
-   returned by SDL_GetPrefPath() would not get created (as done on other
-   SDL platforms).  Files could be written to this path, however apps would
-   need to explicitly create the missing directories first.
-   
-2. SDL_GetPrefPath() would return a path inside a WinRT 'Roaming' folder,
-   the contents of which could get automatically synchronized across multiple
-   devices, by Windows.  This process could occur while an app was running.
-   Apps which were not explicitly built to handle this scenario could
-   have their SDL_GetPrefPath-backed save data swapped out by Windows at
-   unexpected times, which raised potential for data-loss (if apps weren't
-   designed to support live file-synchronization.)
+Upgrade Notes
+-------------
+
+#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
+
+SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
+The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
+that these changes only apply to SDL-based WinRT apps, and not to apps for
+any other platform.
+
+1. SDL_GetPrefPath() would return an invalid path, one in which the path's
+   directory had not been created.  Attempts to create files there
+   (via fopen(), for example), would fail, unless that directory was
+   explicitly created beforehand.
+
+2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
+   a WinRT 'Roaming' folder, the contents of which get automatically
+   synchronized across multiple devices.  This process can occur while an
+   application runs, and can cause existing save-data to be overwritten
+   at unexpected times, with data from other devices.  (Windows Phone apps
+   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
+   restrictions in Windows Phone 8.0).
 
 
 SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
@@ -146,37 +145,14 @@ SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
 1. making sure that SDL_GetPrefPath() returns a directory in which data
    can be written to immediately, without first needing to create directories.
 
-2. basing SDL_GetPrefPath() off of a non-Roaming / 'Local' folder, the
-   contents of which do not get automatically synchronized across devices,
-   and which may be safer in terms of data-integrity.
-   
-   Apps can, at their discretion, choose to utilize WinRT's Roaming
-   functionality by calling the following before calling SDL_GetPrefPath():
-   
-       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "roaming");
-
-   Alternatively, to restore SDL_GetPrefPath()'s old behavior (found in
-   SDL 2.0.3, and in many pre-2.0.4 versions of SDL found on hg.libsdl.org),
-   whereby a Roaming path is returned for Windows Store apps, and a Local
-   folder is returned for Windows Phone apps, use the following code:
-   
-       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "old");
-   
-   Before using Roaming data in any capacity, it is highly recommended that
-   one read the following:
-   
-   1. Microsoft's documentation on the Roaming data.  Details on this can be
-      found on MSDN, at:
-      [Guidelines for roaming app data](http://msdn.microsoft.com/en-us/library/windows/apps/hh465094.aspx).
-   
-   2. the SDL documentation for SDL_HINT_WINRT_PREF_PATH_ROOT, which is
-      listed inside SDL_hints.h.
-
-   Please note that Roaming support is not available on Windows Phone 8.0,
-   due to limitations in the OS itself.  Attempts to use it will fail, with
-   SDL_GetPrefPath() returning NULL (if SDL_HINT_WINRT_PREF_PATH_ROOT is
-   set to "roaming" on that platform).  Windows Phone 8.1 does not have this
-   limitation, and does support Roaming data.
+2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
+   contents of which do not automatically get synchronized across devices
+   (and which require less work to use safely, in terms of data integrity).
+
+Apps that wish to get their Roaming folder's path can do so either by using
+SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
+UCS-2/wide-char string), or directly through the WinRT class,
+Windows.Storage.ApplicationData.
 
 
 

include/SDL_hints.h

@@ -491,36 +491,6 @@ extern "C" {
  */
 #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"
 
-/**
- *  \brief  A variable that dictates what SDL_GetPrefPath() returns in WinRT apps.
- *
- *  The variable can be set to the following values:
- *   * "local"   - Use the app's 'local' folder to store data.
- *   * "roaming" - Use the app's 'roaming' folder to store data.
- *                 On Windows Phone 8.0, this setting is not supported due to
- *                 limitations in the OS itself.  Attempts to use this (via
- *                 SDL_GetPrefPath()) on Windows Phone 8.0 will fail, with
- *                 SDL_GetPrefPath() returning NULL.  (Windows Phone 8.1 does,
- *                 however, support roaming folders.)
- *   * "old"     - Use the app's 'local' folder on Windows Phone, and 'roaming'
- *                 on non-Phone versions of WinRT.  This mimics behavior found
- *                 in SDL 2.0.3's implementation of SDL_GetPrefPath() for WinRT
- *                 (and was changed for SDL 2.0.4, further details of which are
- *                 in the "Caveats" section of SDL's
- *                 [WinRT README file](README-winrt.md).
- *
- *  The default is to use the app's "local" folder.
- *
- *  Details on 'local' verses 'roaming' folders can be found on MSDN, in
- *  the documentation for WinRT's Windows.Storage.ApplicationData class,
- *  (available at http://msdn.microsoft.com/en-us/library/windows/apps/windows.storage.applicationdata ).
- *
- *  The application's local and roaming paths may, alternatively, be retrieved
- *  via the SDL_WinRTGetFSPathUTF8() and SDL_WinRTGetFSPathUNICODE() functions,
- *  which are defined in SDL_system.h.
- */
-#define SDL_HINT_WINRT_PREF_PATH_ROOT "SDL_WINRT_PREF_PATH_ROOT"
-
 /**
  *  \brief  A variable that dictates policy for fullscreen Spaces on Mac OS X.
  *

src/filesystem/winrt/SDL_sysfilesystem.cpp

@@ -144,49 +144,6 @@ SDL_GetPrefPath(const char *org, const char *app)
      * without violating Microsoft's app-store requirements.
      */
 
-    /* Default to using a Local/non-Roaming path.  WinRT will often attempt
-     * to synchronize files in Roaming paths, and will do so while an app is
-     * running.  Using a Local path prevents the possibility that an app's
-     * save-data files will get changed from underneath it, without it
-     * being ready.
-     *
-     * This behavior can be changed via use of the
-     * SDL_HINT_WINRT_PREF_PATH_ROOT hint.
-     */
-    SDL_WinRT_Path pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
-
-    const char * hint = SDL_GetHint(SDL_HINT_WINRT_PREF_PATH_ROOT);
-    if (hint) {
-        if (SDL_strcasecmp(hint, "local") == 0) {
-            pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
-        } else if (SDL_strcasecmp(hint, "roaming") == 0) {
-#if (WINAPI_FAMILY != WINAPI_FAMILY_PHONE_APP) || (NTDDI_VERSION > NTDDI_WIN8)
-            pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
-#else
-            /* Don't apply a 'Roaming' path on Windows Phone 8.0.  Roaming
-             * data is not supported by that version of the operating system.
-             */
-            SDL_SetError("A Roaming path was specified via SDL_HINT_WINRT_PREF_PATH_ROOT, but Roaming is not supported on Windows Phone 8.0");
-            return NULL;
-#endif
-        } else if (SDL_strcasecmp(hint, "old") == 0) {
-            /* Older versions of SDL/WinRT, including 2.0.3, would return a
-             * pref-path that used a Roaming folder on non-Phone versions of
-             * Windows, such as Windows 8.0 and Windows 8.1.  This has since
-             * been reverted to using a Local folder, in order to prevent
-             * problems arising from WinRT automatically synchronizing files
-             * during an app's lifetime.  In case this functionality is
-             * desired, setting SDL_HINT_WINRT_PREF_PATH_ROOT to "old" will
-             * trigger the older behavior.
-             */
-#if WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP
-            pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
-#else
-            pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
-#endif
-        }
-    }
-
     const WCHAR * srcPath = NULL;
     WCHAR path[MAX_PATH];
     char *retval = NULL;
@@ -195,7 +152,7 @@ SDL_GetPrefPath(const char *org, const char *app)
     size_t new_wpath_len = 0;
     BOOL api_result = FALSE;
 
-    srcPath = SDL_WinRTGetFSPathUNICODE(pathType);
+    srcPath = SDL_WinRTGetFSPathUNICODE(SDL_WINRT_PATH_LOCAL_FOLDER);
     if ( ! srcPath) {
         SDL_SetError("Unable to find a source path");
         return NULL;