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.
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;