docs/README-winrt.md
changeset 9247 eddb899239fe
parent 9242 f4d353bd5d16
child 9255 c2ef0d8d6da0
     1.1 --- a/docs/README-winrt.md	Fri Nov 28 04:51:33 2014 -0800
     1.2 +++ b/docs/README-winrt.md	Sat Nov 29 10:09:30 2014 -0500
     1.3 @@ -119,27 +119,64 @@
     1.4  Caveats
     1.5  -------
     1.6  
     1.7 -#### SDL_GetPrefPath() usage
     1.8 +#### SDL_GetPrefPath() usage when upgrading existing WinRT apps to SDL 2.0.4
     1.9 +
    1.10 +SDL 2.0.4 fixes two bugs found in SDL_GetPrefPath() which can affect
    1.11 +an app's save data.  These bugs only apply to WinRT apps (and not
    1.12 +Windows Desktop / Win32 apps, or to apps on any other SDL platform).
    1.13 +In particular, for older versions of SDL (anything before 2.0.4):
    1.14  
    1.15 -SDL_GetPrefPath() is available for use in WinRT apps, however the following
    1.16 -should be noted:
    1.17 +1. SDL_GetPrefPath() would return an invalid path, one in which attempts
    1.18 +   to write files to would fail, in many cases.  Some of the path elements
    1.19 +   returned by SDL_GetPrefPath() would not get created (as done on other
    1.20 +   SDL platforms).  Files could be written to this path, however apps would
    1.21 +   need to explicitly create the missing directories first.
    1.22 +   
    1.23 +2. SDL_GetPrefPath() would return a path inside a WinRT 'Roaming' folder,
    1.24 +   the contents of which could get automatically synchronized across multiple
    1.25 +   devices, by Windows.  This process could occur while an app was running.
    1.26 +   Apps which were not explicitly built to handle this scenario could
    1.27 +   have their SDL_GetPrefPath-backed save data swapped out by Windows at
    1.28 +   unexpected times, which raised potential for data-loss (if apps weren't
    1.29 +   designed to support live file-synchronization.)
    1.30 +
    1.31 +
    1.32 +SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
    1.33 +
    1.34 +1. making sure that SDL_GetPrefPath() returns a directory in which data
    1.35 +   can be written to immediately, without first needing to create directories.
    1.36  
    1.37 -1. It will return different path types, by default, depending on the WinRT
    1.38 -   platform.  Windows Phone apps will default to using the app's "local" path,
    1.39 -   whereas Windows Store (i.e. non-Phone) apps will default to using the app's
    1.40 -   "roaming" path.  This behavior can be changed by calling SDL_SetHint() with
    1.41 -   the key, SDL_HINT_WINRT_PREF_PATH_ROOT, and a value of either "local" or
    1.42 -   "roaming".
    1.43 +2. basing SDL_GetPrefPath() off of a non-Roaming / 'Local' folder, the
    1.44 +   contents of which do not get automatically synchronized across devices,
    1.45 +   and which may be safer in terms of data-integrity.
    1.46 +   
    1.47 +   Apps can, at their discretion, choose to utilize WinRT's Roaming
    1.48 +   functionality by calling the following before calling SDL_GetPrefPath():
    1.49 +   
    1.50 +       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "roaming");
    1.51  
    1.52 -2. Windows Phone 8.0 does not provide apps access to a "roaming" folder.
    1.53 -   Attempts to make SDL_GetPrefPath() return a roaming folder on Windows
    1.54 -   Phone 8.0 will be ignored (and a path inside the "local" folder will be
    1.55 -   used instead).
    1.56 +   Alternatively, to restore SDL_GetPrefPath()'s old behavior (found in
    1.57 +   SDL 2.0.3, and in many pre-2.0.4 versions of SDL found on hg.libsdl.org),
    1.58 +   whereby a Roaming path is returned for Windows Store apps, and a Local
    1.59 +   folder is returned for Windows Phone apps, use the following code:
    1.60 +   
    1.61 +       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "old");
    1.62 +   
    1.63 +   Before using Roaming data in any capacity, it is highly recommended that
    1.64 +   one read the following:
    1.65 +   
    1.66 +   1. Microsoft's documentation on the Roaming data.  Details on this can be
    1.67 +      found on MSDN, at:
    1.68 +      [Guidelines for roaming app data](http://msdn.microsoft.com/en-us/library/windows/apps/hh465094.aspx).
    1.69 +   
    1.70 +   2. the SDL documentation for SDL_HINT_WINRT_PREF_PATH_ROOT, which is
    1.71 +      listed inside SDL_hints.h.
    1.72  
    1.73 -Further details on this can be found in the documentation for
    1.74 -SDL_HINT_WINRT_PREF_PATH_ROOT, in SDL_hints.h, as well as the docs for
    1.75 -SDL_WinRT_Path, SDL_WinRTGetFSPathUNICODE, and SDL_WinRTGetFSPathUTF8,
    1.76 -in SDL_system.h.
    1.77 +   Please note that Roaming support is not available on Windows Phone 8.0,
    1.78 +   due to limitations in the OS itself.  Attempts to use it will fail, with
    1.79 +   SDL_GetPrefPath() returning NULL (if SDL_HINT_WINRT_PREF_PATH_ROOT is
    1.80 +   set to "roaming" on that platform).  Windows Phone 8.1 does not have this
    1.81 +   limitation, and does support Roaming data.
    1.82  
    1.83  
    1.84