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.
--- a/docs/README-winrt.md Sun Nov 30 20:55:27 2014 -0800
+++ b/docs/README-winrt.md Tue Dec 02 21:18:50 2014 -0500
@@ -116,29 +116,28 @@
-Caveats
--------
+Upgrade Notes
+-------------
-#### SDL_GetPrefPath() usage when upgrading existing WinRT apps to SDL 2.0.4
+#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
-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):
+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 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.)
+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 @@
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");
+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).
- 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.
+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.
--- a/include/SDL_hints.h Sun Nov 30 20:55:27 2014 -0800
+++ b/include/SDL_hints.h Tue Dec 02 21:18:50 2014 -0500
@@ -492,36 +492,6 @@
#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.
*
* This hint only applies to Mac OS X.
--- a/src/filesystem/winrt/SDL_sysfilesystem.cpp Sun Nov 30 20:55:27 2014 -0800
+++ b/src/filesystem/winrt/SDL_sysfilesystem.cpp Tue Dec 02 21:18:50 2014 -0500
@@ -144,49 +144,6 @@
* 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 @@
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;