Commit ecc014740aa229e7cf6729ca89f887bcd003fa1d
2014-11-27T09:55:34
WinRT: added SDL_HINT_WINRT_PREF_PATH_ROOT SDL_HINT_WINRT_PREF_PATH_ROOT allows WinRT apps to alter the path that SDL_GetPrefPath() returns. Setting it to "local" uses the app's OS-defined Local folder, setting it to "roaming" uses the app's OS-defined Roaming folder. Roaming folder support is not available in Windows Phone 8.0. Attempts to make SDL_GetPrefPath() return a Roaming folder on this OS will be ignored. Various bits of documentation on this were added to SDL_hints.h, and to README-winrt.md
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
diff --git a/docs/README-winrt.md b/docs/README-winrt.md
index 90d9889..0ff70ec 100644
--- a/docs/README-winrt.md
+++ b/docs/README-winrt.md
@@ -116,6 +116,32 @@ Here is a rough list of what works, and what doens't:
+Caveats
+-------
+
+#### SDL_GetPrefPath() usage
+
+SDL_GetPrefPath() is available for use in WinRT apps, however the following
+should be noted:
+
+1. It will return different path types, by default, depending on the WinRT
+ platform. Windows Phone apps will default to using the app's "local" path,
+ whereas Windows Store (i.e. non-Phone) apps will default to using the app's
+ "roaming" path. This behavior can be changed by calling SDL_SetHint() with
+ the key, SDL_HINT_WINRT_PREF_PATH_ROOT, and a value of either "local" or
+ "roaming".
+
+2. Windows Phone 8.0 does not provide apps access to a "roaming" folder.
+ Attempts to make SDL_GetPrefPath() return a roaming folder on Windows
+ Phone 8.0 will be ignored (and a path inside the "local" folder will be
+ used instead).
+
+Further details on this can be found in the documentation for
+SDL_HINT_WINRT_PREF_PATH_ROOT, in SDL_hints.h, as well as the docs for
+SDL_WinRT_Path, SDL_WinRTGetFSPathUNICODE, and SDL_WinRTGetFSPathUTF8,
+in SDL_system.h.
+
+
Setup, High-Level Steps
-----------------------
diff --git a/include/SDL_hints.h b/include/SDL_hints.h
index 673d347..dd44ba3 100644
--- a/include/SDL_hints.h
+++ b/include/SDL_hints.h
@@ -492,6 +492,27 @@ 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; default for
+ * Windows Phone apps.
+ * "roaming" - Use the app's 'roaming' folder to store data; default for
+ * Windows Store (non-Phone) apps. On Windows Phone 8.0, this
+ * setting will be ignored (and the 'local' folder will be used
+ * instead), as the OS does not support roaming folders.
+ *
+ * Details on 'local' verses 'roaming' folders can be found on MSDN, in the
+ * documentation for WinRT's Windows.Storage.ApplicationData class, which is
+ * 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.
diff --git a/src/filesystem/winrt/SDL_sysfilesystem.cpp b/src/filesystem/winrt/SDL_sysfilesystem.cpp
index d38c0b6..7bb1486 100644
--- a/src/filesystem/winrt/SDL_sysfilesystem.cpp
+++ b/src/filesystem/winrt/SDL_sysfilesystem.cpp
@@ -28,6 +28,7 @@
extern "C" {
#include "SDL_filesystem.h"
#include "SDL_error.h"
+#include "SDL_hints.h"
#include "SDL_stdinc.h"
#include "SDL_system.h"
#include "../../core/windows/SDL_windows.h"
@@ -149,13 +150,26 @@ SDL_GetPrefPath(const char *org, const char *app)
* compatibility with Windows Phone 8.0, and with app-installs that have
* been updated from 8.0-based, to 8.1-based apps.
*/
- const char * srcPath = SDL_WinRTGetFSPathUTF8(SDL_WINRT_PATH_LOCAL_FOLDER);
+ SDL_WinRT_Path pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
#else
/* A 'Roaming' folder is available on Windows 8 and 8.1. Use that.
*/
- const char * srcPath = SDL_WinRTGetFSPathUTF8(SDL_WINRT_PATH_ROAMING_FOLDER);
+ SDL_WinRT_Path pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
#endif
+ 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;
+ }
+#if (WINAPI_FAMILY != WINAPI_FAMILY_PHONE_APP) || (NTDDI_VERSION > NTDDI_WIN8)
+ else if (SDL_strcasecmp(hint, "roaming") == 0) {
+ pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
+ }
+#endif
+ }
+
+ const char * srcPath = SDL_WinRTGetFSPathUTF8(pathType);
size_t destPathLen;
char * destPath = NULL;