mirror of https://github.com/encounter/SDL.git
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.
This commit is contained in:
David Ludwig
parent
52760dcdf1
commit
5fee84f24b
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue