filesystem: SDL_GetUserFolder() now follows the SDL_GetStringRule.

It also now caches at the higher level, so the platform-specific bits don't
change their interface much.

Reference Issue libsdl-org#10229.

include/SDL3/SDL_filesystem.h

@@ -204,12 +204,13 @@ typedef enum SDL_Folder
     SDL_FOLDER_TEMPLATES,
     /** Video files that can be played using a standard video player (mp4,
       webm...). */
-    SDL_FOLDER_VIDEOS
+    SDL_FOLDER_VIDEOS,
+    /** total number of types in this enum, not a folder type by itself. */
+    SDL_FOLDER_TOTAL
 } SDL_Folder;
 
 /**
- * Finds the most suitable user folder for the specified purpose, and returns
- * its path in OS-specific notation.
+ * Finds the most suitable user folder for a specific purpose.
  *
  * Many OSes provide certain standard folders for certain purposes, such as
  * storing pictures, music or videos for a certain user. This function gives
@@ -220,14 +221,10 @@ typedef enum SDL_Folder
  * data for the application to manage, see SDL_GetBasePath() and
  * SDL_GetPrefPath().
  *
- * Note that the function is expensive, and should be called once at the
- * beginning of the execution and kept for as long as needed.
- *
  * The returned path is guaranteed to end with a path separator ('\\' on
  * Windows, '/' on most other platforms).
  *
- * The returned value is owned by the caller and should be freed with
- * SDL_free().
+ * The returned string follows the SDL_GetStringRule.
  *
  * If NULL is returned, the error may be obtained with SDL_GetError().
  *
@@ -236,10 +233,8 @@ typedef enum SDL_Folder
  *          folder, or NULL if an error happened.
  *
  * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_Folder
  */
-extern SDL_DECLSPEC char *SDLCALL SDL_GetUserFolder(SDL_Folder folder);
+extern SDL_DECLSPEC const char *SDLCALL SDL_GetUserFolder(SDL_Folder folder);
 
 
 /* Abstract filesystem interface */

src/core/SDL_core_unsupported.c

@@ -228,8 +228,9 @@ Sint32 JNI_OnLoad(void *vm, void *reserved)
 }
 #endif
 
+// !!! FIXME: this probably belongs in src/filesystem/gdk
 #if defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES)
-char *SDL_GetUserFolder(SDL_Folder folder)
+const char *SDL_GetUserFolder(SDL_Folder folder)
 {
     (void)folder;
     SDL_Unsupported();

src/dynapi/SDL_dynapi_procs.h

@@ -505,7 +505,7 @@ SDL_DYNAPI_PROC(const char*,SDL_GetTouchDeviceName,(SDL_TouchID a),(a),return)
 SDL_DYNAPI_PROC(SDL_TouchDeviceType,SDL_GetTouchDeviceType,(SDL_TouchID a),(a),return)
 SDL_DYNAPI_PROC(SDL_TouchID*,SDL_GetTouchDevices,(int *a),(a),return)
 SDL_DYNAPI_PROC(SDL_Finger**,SDL_GetTouchFingers,(SDL_TouchID a, int *b),(a,b),return)
-SDL_DYNAPI_PROC(char*,SDL_GetUserFolder,(SDL_Folder a),(a),return)
+SDL_DYNAPI_PROC(const char*,SDL_GetUserFolder,(SDL_Folder a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetVersion,(void),(),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetVideoDriver,(int a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetWindowAspectRatio,(SDL_Window *a, float *b, float *c),(a,b,c),return)

src/filesystem/SDL_filesystem.c

@@ -411,14 +411,38 @@ const char *SDL_GetBasePath(void)
     return CachedBasePath;
 }
 
+
+static char *CachedUserFolders[SDL_FOLDER_TOTAL];
+
+const char *SDL_GetUserFolder(SDL_Folder folder)
+{
+    const int idx = (int) folder;
+    if ((idx < 0) || (idx >= SDL_arraysize(CachedUserFolders))) {
+        SDL_InvalidParamError("folder");
+        return NULL;
+    }
+
+    if (!CachedUserFolders[idx]) {
+        CachedUserFolders[idx] = SDL_SYS_GetUserFolder(folder);
+    }
+    return CachedUserFolders[idx];
+}
+
+
+
 void SDL_InitFilesystem(void)
 {
     CachedBasePath = NULL;  // just in case.
+    SDL_zeroa(CachedUserFolders);
 }
 
 void SDL_QuitFilesystem(void)
 {
     SDL_free(CachedBasePath);
     CachedBasePath = NULL;
+    for (int i = 0; i < SDL_arraysize(CachedUserFolders); i++) {
+        SDL_free(CachedUserFolders[i]);
+        CachedUserFolders[i] = NULL;
+    }
 }
 

src/filesystem/SDL_sysfilesystem.h

@@ -24,6 +24,7 @@
 
 // return a string that we can SDL_free(). It will be cached at the higher level.
 extern char *SDL_SYS_GetBasePath(void);
+extern char *SDL_SYS_GetUserFolder(SDL_Folder folder);
 
 int SDL_SYS_EnumerateDirectory(const char *path, const char *dirname, SDL_EnumerateDirectoryCallback cb, void *userdata);
 int SDL_SYS_RemovePath(const char *path);

src/filesystem/android/SDL_sysfilesystem.c

@@ -49,7 +49,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return NULL;
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     /* TODO: see https://developer.android.com/reference/android/os/Environment#lfields
        and https://stackoverflow.com/questions/39332085/get-path-to-pictures-directory */

src/filesystem/cocoa/SDL_sysfilesystem.m

@@ -126,7 +126,7 @@
     }
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     @autoreleasepool {
 #ifdef SDL_PLATFORM_TVOS

src/filesystem/dummy/SDL_sysfilesystem.c

@@ -37,7 +37,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return NULL;
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/emscripten/SDL_sysfilesystem.c

@@ -81,7 +81,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return retval;
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     const char *home = NULL;
 

src/filesystem/haiku/SDL_sysfilesystem.cc

@@ -97,7 +97,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return retval;
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     const char *home = NULL;
     char *retval;

src/filesystem/n3ds/SDL_sysfilesystem.c

@@ -60,7 +60,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/ps2/SDL_sysfilesystem.c

@@ -108,7 +108,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/psp/SDL_sysfilesystem.c

@@ -78,7 +78,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/riscos/SDL_sysfilesystem.c

@@ -197,7 +197,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/unix/SDL_sysfilesystem.c

@@ -510,7 +510,7 @@ static char *xdg_user_dir_lookup (const char *type)
     return NULL;
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     const char *param = NULL;
     char *retval;

src/filesystem/vita/SDL_sysfilesystem.c

@@ -81,7 +81,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/windows/SDL_sysfilesystem.c

@@ -174,7 +174,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return retval;
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     typedef HRESULT (WINAPI *pfnSHGetKnownFolderPath)(REFGUID /* REFKNOWNFOLDERID */, DWORD, HANDLE, PWSTR*);
     HMODULE lib = LoadLibrary(L"Shell32.dll");

src/filesystem/winrt/SDL_sysfilesystem.cpp

@@ -227,7 +227,7 @@ extern "C" char *SDL_GetPrefPath(const char *org, const char *app)
     return retval;
 }
 
-char *SDL_GetUserFolder(SDL_Folder folder)
+char *SDL_SYS_GetUserFolder(SDL_Folder folder)
 {
     wstring wpath;
 

test/testdialog.c

@@ -52,7 +52,7 @@ int main(int argc, char *argv[]) {
     const SDL_FRect save_file_rect = { 50, 290, 220, 140 };
     const SDL_FRect open_folder_rect = { 370, 50, 220, 140 };
     int i;
-    char *initial_path = NULL;
+    const char *initial_path = NULL;
     const int nfilters = sizeof(filters) / sizeof(*filters);
 
     /* Initialize test framework */
@@ -147,10 +147,6 @@ int main(int argc, char *argv[]) {
         SDL_RenderPresent(r);
     }
 
-    if (initial_path) {
-        SDL_free(initial_path);
-    }
-
     SDLTest_CleanupTextDrawing();
     SDL_DestroyRenderer(r);
     SDL_DestroyWindow(w);