From 5fee84f24bac965c3cf4340601b12760823effc3 Mon Sep 17 00:00:00 2001 From: David Ludwig Date: Tue, 2 Dec 2014 21:18:50 -0500 Subject: [PATCH] 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 | 76 ++++++++-------------- include/SDL_hints.h | 30 --------- src/filesystem/winrt/SDL_sysfilesystem.cpp | 45 +------------ 3 files changed, 27 insertions(+), 124 deletions(-) diff --git a/docs/README-winrt.md b/docs/README-winrt.md index f573a776c..fdc669f10 100644 --- a/docs/README-winrt.md +++ b/docs/README-winrt.md @@ -116,29 +116,28 @@ Here is a rough list of what works, and what doens't: -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 @@ 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"); +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. diff --git a/include/SDL_hints.h b/include/SDL_hints.h index 7c9e4dfd8..673d347eb 100644 --- a/include/SDL_hints.h +++ b/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. * diff --git a/src/filesystem/winrt/SDL_sysfilesystem.cpp b/src/filesystem/winrt/SDL_sysfilesystem.cpp index 8345b9a78..370508dc1 100644 --- a/src/filesystem/winrt/SDL_sysfilesystem.cpp +++ b/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;