docs/README-winrt.md
changeset 9255 c2ef0d8d6da0
parent 9247 eddb899239fe
child 9335 3eb0896ecb91
     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