9ff3446f03
Most SDL functions used to indicate success or failure using an int return code. These functions have been changed to return SDL_bool. Here is a coccinelle patch to change code that previously compared the return value to 0 and changes it to a boolean test: @ bool_return_type @ identifier func =~ "^(SDL_AddEventWatch|SDL_AddHintCallback|SDL_AddSurfaceAlternateImage|SDL_AddVulkanRenderSemaphores|SDL_BindAudioStream|SDL_BindAudioStreams|SDL_BlitSurface|SDL_BlitSurface9Grid|SDL_BlitSurfaceScaled|SDL_BlitSurfaceTiled|SDL_BlitSurfaceTiledWithScale|SDL_BlitSurfaceUnchecked|SDL_BlitSurfaceUncheckedScaled|SDL_CaptureMouse|SDL_ClearAudioStream|SDL_ClearClipboardData|SDL_ClearComposition|SDL_ClearError|SDL_ClearProperty|SDL_ClearSurface|SDL_CloseIO|SDL_CloseStorage|SDL_ConvertAudioSamples|SDL_ConvertEventToRenderCoordinates|SDL_ConvertPixels|SDL_ConvertPixelsAndColorspace|SDL_CopyFile|SDL_CopyProperties|SDL_CopyStorageFile|SDL_CreateDirectory|SDL_CreateStorageDirectory|SDL_CreateWindowAndRenderer|SDL_DateTimeToTime|SDL_DestroyWindowSurface|SDL_DetachVirtualJoystick|SDL_DisableScreenSaver|SDL_EnableScreenSaver|SDL_EnumerateDirectory|SDL_EnumerateProperties|SDL_EnumerateStorageDirectory|SDL_FillSurfaceRect|SDL_FillSurfaceRects|SDL_FlashWindow|SDL_FlipSurface|SDL_FlushAudioStream|SDL_FlushRenderer|SDL_GL_DestroyContext|SDL_GL_GetAttribute|SDL_GL_GetSwapInterval|SDL_GL_LoadLibrary|SDL_GL_MakeCurrent|SDL_GL_SetAttribute|SDL_GL_SetSwapInterval|SDL_GL_SwapWindow|SDL_GetAudioDeviceFormat|SDL_GetAudioStreamFormat|SDL_GetCameraFormat|SDL_GetClosestFullscreenDisplayMode|SDL_GetCurrentRenderOutputSize|SDL_GetCurrentTime|SDL_GetDXGIOutputInfo|SDL_GetDateTimeLocalePreferences|SDL_GetDisplayBounds|SDL_GetDisplayUsableBounds|SDL_GetGDKDefaultUser|SDL_GetGDKTaskQueue|SDL_GetGamepadSensorData|SDL_GetGamepadTouchpadFinger|SDL_GetHapticEffectStatus|SDL_GetJoystickBall|SDL_GetMasksForPixelFormat|SDL_GetPathInfo|SDL_GetRectUnion|SDL_GetRectUnionFloat|SDL_GetRenderClipRect|SDL_GetRenderColorScale|SDL_GetRenderDrawBlendMode|SDL_GetRenderDrawColor|SDL_GetRenderDrawColorFloat|SDL_GetRenderLogicalPresentation|SDL_GetRenderLogicalPresentationRect|SDL_GetRenderOutputSize|SDL_GetRenderSafeArea|SDL_GetRenderScale|SDL_GetRenderVSync|SDL_GetRenderViewport|SDL_GetSensorData|SDL_GetStorageFileSize|SDL_GetStoragePathInfo|SDL_GetSurfaceAlphaMod|SDL_GetSurfaceBlendMode|SDL_GetSurfaceClipRect|SDL_GetSurfaceColorKey|SDL_GetSurfaceColorMod|SDL_GetTextInputArea|SDL_GetTextureAlphaMod|SDL_GetTextureAlphaModFloat|SDL_GetTextureBlendMode|SDL_GetTextureColorMod|SDL_GetTextureColorModFloat|SDL_GetTextureScaleMode|SDL_GetTextureSize|SDL_GetWindowAspectRatio|SDL_GetWindowBordersSize|SDL_GetWindowMaximumSize|SDL_GetWindowMinimumSize|SDL_GetWindowPosition|SDL_GetWindowRelativeMouseMode|SDL_GetWindowSafeArea|SDL_GetWindowSize|SDL_GetWindowSizeInPixels|SDL_GetWindowSurfaceVSync|SDL_HideCursor|SDL_HideWindow|SDL_Init|SDL_InitHapticRumble|SDL_InitSubSystem|SDL_LoadWAV|SDL_LoadWAV_IO|SDL_LockAudioStream|SDL_LockProperties|SDL_LockSurface|SDL_LockTexture|SDL_LockTextureToSurface|SDL_MaximizeWindow|SDL_MinimizeWindow|SDL_MixAudio|SDL_OpenURL|SDL_OutOfMemory|SDL_PauseAudioDevice|SDL_PauseAudioStreamDevice|SDL_PauseHaptic|SDL_PlayHapticRumble|SDL_PremultiplyAlpha|SDL_PremultiplySurfaceAlpha|SDL_PushEvent|SDL_PutAudioStreamData|SDL_RaiseWindow|SDL_ReadStorageFile|SDL_ReadSurfacePixel|SDL_ReadSurfacePixelFloat|SDL_RegisterApp|SDL_ReloadGamepadMappings|SDL_RemovePath|SDL_RemoveStoragePath|SDL_RemoveTimer|SDL_RenamePath|SDL_RenameStoragePath|SDL_RenderClear|SDL_RenderCoordinatesFromWindow|SDL_RenderCoordinatesToWindow|SDL_RenderFillRect|SDL_RenderFillRects|SDL_RenderGeometry|SDL_RenderGeometryRaw|SDL_RenderLine|SDL_RenderLines|SDL_RenderPoint|SDL_RenderPoints|SDL_RenderPresent|SDL_RenderRect|SDL_RenderRects|SDL_RenderTexture|SDL_RenderTexture9Grid|SDL_RenderTextureRotated|SDL_RenderTextureTiled|SDL_RequestAndroidPermission|SDL_RestoreWindow|SDL_ResumeAudioDevice|SDL_ResumeAudioStreamDevice|SDL_ResumeHaptic|SDL_RumbleGamepad|SDL_RumbleGamepadTriggers|SDL_RumbleJoystick|SDL_RumbleJoystickTriggers|SDL_RunHapticEffect|SDL_SaveBMP|SDL_SaveBMP_IO|SDL_SendAndroidMessage|SDL_SendGamepadEffect|SDL_SendJoystickEffect|SDL_SendJoystickVirtualSensorData|SDL_SetAppMetadata|SDL_SetAppMetadataProperty|SDL_SetAudioDeviceGain|SDL_SetAudioPostmixCallback|SDL_SetAudioStreamFormat|SDL_SetAudioStreamFrequencyRatio|SDL_SetAudioStreamGain|SDL_SetAudioStreamGetCallback|SDL_SetAudioStreamInputChannelMap|SDL_SetAudioStreamOutputChannelMap|SDL_SetAudioStreamPutCallback|SDL_SetBooleanProperty|SDL_SetClipboardData|SDL_SetClipboardText|SDL_SetCursor|SDL_SetFloatProperty|SDL_SetGamepadLED|SDL_SetGamepadMapping|SDL_SetGamepadPlayerIndex|SDL_SetGamepadSensorEnabled|SDL_SetHapticAutocenter|SDL_SetHapticGain|SDL_SetJoystickLED|SDL_SetJoystickPlayerIndex|SDL_SetJoystickVirtualAxis|SDL_SetJoystickVirtualBall|SDL_SetJoystickVirtualButton|SDL_SetJoystickVirtualHat|SDL_SetJoystickVirtualTouchpad|SDL_SetLinuxThreadPriority|SDL_SetLinuxThreadPriorityAndPolicy|SDL_SetLogPriorityPrefix|SDL_SetMemoryFunctions|SDL_SetNumberProperty|SDL_SetPaletteColors|SDL_SetPointerProperty|SDL_SetPointerPropertyWithCleanup|SDL_SetPrimarySelectionText|SDL_SetRenderClipRect|SDL_SetRenderColorScale|SDL_SetRenderDrawBlendMode|SDL_SetRenderDrawColor|SDL_SetRenderDrawColorFloat|SDL_SetRenderLogicalPresentation|SDL_SetRenderScale|SDL_SetRenderTarget|SDL_SetRenderVSync|SDL_SetRenderViewport|SDL_SetScancodeName|SDL_SetStringProperty|SDL_SetSurfaceAlphaMod|SDL_SetSurfaceBlendMode|SDL_SetSurfaceColorKey|SDL_SetSurfaceColorMod|SDL_SetSurfaceColorspace|SDL_SetSurfacePalette|SDL_SetSurfaceRLE|SDL_SetTLS|SDL_SetTextInputArea|SDL_SetTextureAlphaMod|SDL_SetTextureAlphaModFloat|SDL_SetTextureBlendMode|SDL_SetTextureColorMod|SDL_SetTextureColorModFloat|SDL_SetTextureScaleMode|SDL_SetThreadPriority|SDL_SetWindowAlwaysOnTop|SDL_SetWindowAspectRatio|SDL_SetWindowBordered|SDL_SetWindowFocusable|SDL_SetWindowFullscreen|SDL_SetWindowFullscreenMode|SDL_SetWindowHitTest|SDL_SetWindowIcon|SDL_SetWindowKeyboardGrab|SDL_SetWindowMaximumSize|SDL_SetWindowMinimumSize|SDL_SetWindowModalFor|SDL_SetWindowMouseGrab|SDL_SetWindowMouseRect|SDL_SetWindowOpacity|SDL_SetWindowPosition|SDL_SetWindowRelativeMouseMode|SDL_SetWindowResizable|SDL_SetWindowShape|SDL_SetWindowSize|SDL_SetWindowSurfaceVSync|SDL_SetWindowTitle|SDL_SetiOSAnimationCallback|SDL_ShowAndroidToast|SDL_ShowCursor|SDL_ShowMessageBox|SDL_ShowSimpleMessageBox|SDL_ShowWindow|SDL_ShowWindowSystemMenu|SDL_StartTextInput|SDL_StartTextInputWithProperties|SDL_StopHapticEffect|SDL_StopHapticEffects|SDL_StopHapticRumble|SDL_StopTextInput|SDL_SyncWindow|SDL_TimeToDateTime|SDL_TryLockMutex|SDL_TryLockRWLockForReading|SDL_TryLockRWLockForWriting|SDL_TryWaitSemaphore|SDL_UnlockAudioStream|SDL_UpdateHapticEffect|SDL_UpdateNVTexture|SDL_UpdateTexture|SDL_UpdateWindowSurface|SDL_UpdateWindowSurfaceRects|SDL_UpdateYUVTexture|SDL_Vulkan_CreateSurface|SDL_Vulkan_LoadLibrary|SDL_WaitConditionTimeout|SDL_WaitSemaphoreTimeout|SDL_WarpMouseGlobal|SDL_WriteStorageFile|SDL_WriteSurfacePixel|SDL_WriteSurfacePixelFloat)$"; @@ ( func( ... ) - == 0 | - func( + !func( ... ) - < 0 | - func( + !func( ... ) - != 0 | - func( + !func( ... ) - == -1 )
431 lines
16 KiB
C
431 lines
16 KiB
C
/*
|
|
Simple DirectMedia Layer
|
|
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
|
|
|
|
This software is provided 'as-is', without any express or implied
|
|
warranty. In no event will the authors be held liable for any damages
|
|
arising from the use of this software.
|
|
|
|
Permission is granted to anyone to use this software for any purpose,
|
|
including commercial applications, and to alter it and redistribute it
|
|
freely, subject to the following restrictions:
|
|
|
|
1. The origin of this software must not be misrepresented; you must not
|
|
claim that you wrote the original software. If you use this software
|
|
in a product, an acknowledgment in the product documentation would be
|
|
appreciated but is not required.
|
|
2. Altered source versions must be plainly marked as such, and must not be
|
|
misrepresented as being the original software.
|
|
3. This notice may not be removed or altered from any source distribution.
|
|
*/
|
|
|
|
/**
|
|
* # CategoryStorage
|
|
*
|
|
* SDL storage container management.
|
|
*/
|
|
|
|
#ifndef SDL_storage_h_
|
|
#define SDL_storage_h_
|
|
|
|
#include <SDL3/SDL_stdinc.h>
|
|
#include <SDL3/SDL_error.h>
|
|
#include <SDL3/SDL_filesystem.h>
|
|
#include <SDL3/SDL_properties.h>
|
|
|
|
#include <SDL3/SDL_begin_code.h>
|
|
|
|
/* Set up for C function definitions, even when using C++ */
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* !!! FIXME: Don't let this ship without async R/W support!!! */
|
|
|
|
/**
|
|
* Function interface for SDL_Storage.
|
|
*
|
|
* Apps that want to supply a custom implementation of SDL_Storage will fill
|
|
* in all the functions in this struct, and then pass it to SDL_OpenStorage to
|
|
* create a custom SDL_Storage object.
|
|
*
|
|
* It is not usually necessary to do this; SDL provides standard
|
|
* implementations for many things you might expect to do with an SDL_Storage.
|
|
*
|
|
* \since This struct is available since SDL 3.0.0.
|
|
*/
|
|
typedef struct SDL_StorageInterface
|
|
{
|
|
/* Called when the storage is closed */
|
|
SDL_bool (SDLCALL *close)(void *userdata);
|
|
|
|
/* Optional, returns whether the storage is currently ready for access */
|
|
SDL_bool (SDLCALL *ready)(void *userdata);
|
|
|
|
/* Enumerate a directory, optional for write-only storage */
|
|
SDL_bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata);
|
|
|
|
/* Get path information, optional for write-only storage */
|
|
SDL_bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info);
|
|
|
|
/* Read a file from storage, optional for write-only storage */
|
|
SDL_bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length);
|
|
|
|
/* Write a file to storage, optional for read-only storage */
|
|
SDL_bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length);
|
|
|
|
/* Create a directory, optional for read-only storage */
|
|
SDL_bool (SDLCALL *mkdir)(void *userdata, const char *path);
|
|
|
|
/* Remove a file or empty directory, optional for read-only storage */
|
|
SDL_bool (SDLCALL *remove)(void *userdata, const char *path);
|
|
|
|
/* Rename a path, optional for read-only storage */
|
|
SDL_bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath);
|
|
|
|
/* Copy a file, optional for read-only storage */
|
|
SDL_bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath);
|
|
|
|
/* Get the space remaining, optional for read-only storage */
|
|
Uint64 (SDLCALL *space_remaining)(void *userdata);
|
|
} SDL_StorageInterface;
|
|
|
|
/**
|
|
* An abstract interface for filesystem access.
|
|
*
|
|
* This is an opaque datatype. One can create this object using standard SDL
|
|
* functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create
|
|
* an object with a custom implementation using SDL_OpenStorage.
|
|
*
|
|
* \since This struct is available since SDL 3.0.0.
|
|
*/
|
|
typedef struct SDL_Storage SDL_Storage;
|
|
|
|
/**
|
|
* Opens up a read-only container for the application's filesystem.
|
|
*
|
|
* \param override a path to override the backend's default title root.
|
|
* \param props a property list that may contain backend-specific information.
|
|
* \returns a title storage container on success or NULL on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_CloseStorage
|
|
* \sa SDL_GetStorageFileSize
|
|
* \sa SDL_OpenUserStorage
|
|
* \sa SDL_ReadStorageFile
|
|
*/
|
|
extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props);
|
|
|
|
/**
|
|
* Opens up a container for a user's unique read/write filesystem.
|
|
*
|
|
* While title storage can generally be kept open throughout runtime, user
|
|
* storage should only be opened when the client is ready to read/write files.
|
|
* This allows the backend to properly batch file operations and flush them
|
|
* when the container has been closed; ensuring safe and optimal save I/O.
|
|
*
|
|
* \param org the name of your organization.
|
|
* \param app the name of your application.
|
|
* \param props a property list that may contain backend-specific information.
|
|
* \returns a user storage container on success or NULL on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_CloseStorage
|
|
* \sa SDL_GetStorageFileSize
|
|
* \sa SDL_GetStorageSpaceRemaining
|
|
* \sa SDL_OpenTitleStorage
|
|
* \sa SDL_ReadStorageFile
|
|
* \sa SDL_StorageReady
|
|
* \sa SDL_WriteStorageFile
|
|
*/
|
|
extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props);
|
|
|
|
/**
|
|
* Opens up a container for local filesystem storage.
|
|
*
|
|
* This is provided for development and tools. Portable applications should
|
|
* use SDL_OpenTitleStorage() for access to game data and
|
|
* SDL_OpenUserStorage() for access to user data.
|
|
*
|
|
* \param path the base path prepended to all storage paths, or NULL for no
|
|
* base path.
|
|
* \returns a filesystem storage container on success or NULL on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_CloseStorage
|
|
* \sa SDL_GetStorageFileSize
|
|
* \sa SDL_GetStorageSpaceRemaining
|
|
* \sa SDL_OpenTitleStorage
|
|
* \sa SDL_OpenUserStorage
|
|
* \sa SDL_ReadStorageFile
|
|
* \sa SDL_WriteStorageFile
|
|
*/
|
|
extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path);
|
|
|
|
/**
|
|
* Opens up a container using a client-provided storage interface.
|
|
*
|
|
* Applications do not need to use this function unless they are providing
|
|
* their own SDL_Storage implementation. If you just need an SDL_Storage, you
|
|
* should use the built-in implementations in SDL, like SDL_OpenTitleStorage()
|
|
* or SDL_OpenUserStorage().
|
|
*
|
|
* \param iface the function table to be used by this container.
|
|
* \param userdata the pointer that will be passed to the store interface.
|
|
* \returns a storage container on success or NULL on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_CloseStorage
|
|
* \sa SDL_GetStorageFileSize
|
|
* \sa SDL_GetStorageSpaceRemaining
|
|
* \sa SDL_ReadStorageFile
|
|
* \sa SDL_StorageReady
|
|
* \sa SDL_WriteStorageFile
|
|
*/
|
|
extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata);
|
|
|
|
/**
|
|
* Closes and frees a storage container.
|
|
*
|
|
* \param storage a storage container to close.
|
|
* \returns SDL_TRUE if the container was freed with no errors, SDL_FALSE
|
|
* otherwise; call SDL_GetError() for more information. Even if the
|
|
* function returns an error, the container data will be freed; the
|
|
* error is only for informational purposes.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_OpenFileStorage
|
|
* \sa SDL_OpenStorage
|
|
* \sa SDL_OpenTitleStorage
|
|
* \sa SDL_OpenUserStorage
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseStorage(SDL_Storage *storage);
|
|
|
|
/**
|
|
* Checks if the storage container is ready to use.
|
|
*
|
|
* This function should be called in regular intervals until it returns
|
|
* SDL_TRUE - however, it is not recommended to spinwait on this call, as the
|
|
* backend may depend on a synchronous message loop.
|
|
*
|
|
* \param storage a storage container to query.
|
|
* \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
|
|
|
|
/**
|
|
* Query the size of a file within a storage container.
|
|
*
|
|
* \param storage a storage container to query.
|
|
* \param path the relative path of the file to query.
|
|
* \param length a pointer to be filled with the file's length.
|
|
* \returns SDL_TRUE if the file could be queried or SDL_FALSE on
|
|
* failure; call SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_ReadStorageFile
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length);
|
|
|
|
/**
|
|
* Synchronously read a file from a storage container into a client-provided
|
|
* buffer.
|
|
*
|
|
* \param storage a storage container to read from.
|
|
* \param path the relative path of the file to read.
|
|
* \param destination a client-provided buffer to read the file into.
|
|
* \param length the length of the destination buffer.
|
|
* \returns SDL_TRUE if the file was read or SDL_FALSE on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_GetStorageFileSize
|
|
* \sa SDL_StorageReady
|
|
* \sa SDL_WriteStorageFile
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length);
|
|
|
|
/**
|
|
* Synchronously write a file from client memory into a storage container.
|
|
*
|
|
* \param storage a storage container to write to.
|
|
* \param path the relative path of the file to write.
|
|
* \param source a client-provided buffer to write from.
|
|
* \param length the length of the source buffer.
|
|
* \returns SDL_TRUE if the file was written or SDL_FALSE on failure;
|
|
* call SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_GetStorageSpaceRemaining
|
|
* \sa SDL_ReadStorageFile
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length);
|
|
|
|
/**
|
|
* Create a directory in a writable storage container.
|
|
*
|
|
* \param storage a storage container.
|
|
* \param path the path of the directory to create.
|
|
* \returns SDL_TRUE on success or SDL_FALSE on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path);
|
|
|
|
/**
|
|
* Enumerate a directory in a storage container through a callback function.
|
|
*
|
|
* This function provides every directory entry through an app-provided
|
|
* callback, called once for each directory entry, until all results have been
|
|
* provided or the callback returns <= 0.
|
|
*
|
|
* \param storage a storage container.
|
|
* \param path the path of the directory to enumerate.
|
|
* \param callback a function that is called for each entry in the directory.
|
|
* \param userdata a pointer that is passed to `callback`.
|
|
* \returns SDL_TRUE on success or SDL_FALSE on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata);
|
|
|
|
/**
|
|
* Remove a file or an empty directory in a writable storage container.
|
|
*
|
|
* \param storage a storage container.
|
|
* \param path the path of the directory to enumerate.
|
|
* \returns SDL_TRUE on success or SDL_FALSE on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path);
|
|
|
|
/**
|
|
* Rename a file or directory in a writable storage container.
|
|
*
|
|
* \param storage a storage container.
|
|
* \param oldpath the old path.
|
|
* \param newpath the new path.
|
|
* \returns SDL_TRUE on success or SDL_FALSE on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath);
|
|
|
|
/**
|
|
* Copy a file in a writable storage container.
|
|
*
|
|
* \param storage a storage container.
|
|
* \param oldpath the old path.
|
|
* \param newpath the new path.
|
|
* \returns SDL_TRUE on success or SDL_FALSE on failure; call
|
|
* SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath);
|
|
|
|
/**
|
|
* Get information about a filesystem path in a storage container.
|
|
*
|
|
* \param storage a storage container.
|
|
* \param path the path to query.
|
|
* \param info a pointer filled in with information about the path, or NULL to
|
|
* check for the existence of a file.
|
|
* \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist,
|
|
* or another failure; call SDL_GetError() for more information.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_StorageReady
|
|
*/
|
|
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info);
|
|
|
|
/**
|
|
* Queries the remaining space in a storage container.
|
|
*
|
|
* \param storage a storage container to query.
|
|
* \returns the amount of remaining space, in bytes.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*
|
|
* \sa SDL_StorageReady
|
|
* \sa SDL_WriteStorageFile
|
|
*/
|
|
extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *storage);
|
|
|
|
/**
|
|
* Enumerate a directory tree, filtered by pattern, and return a list.
|
|
*
|
|
* Files are filtered out if they don't match the string in `pattern`, which
|
|
* may contain wildcard characters '*' (match everything) and '?' (match one
|
|
* character). If pattern is NULL, no filtering is done and all results are
|
|
* returned. Subdirectories are permitted, and are specified with a path
|
|
* separator of '/'. Wildcard characters '*' and '?' never match a path
|
|
* separator.
|
|
*
|
|
* `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching
|
|
* case-insensitive.
|
|
*
|
|
* The returned array is always NULL-terminated, for your iterating
|
|
* convenience, but if `count` is non-NULL, on return it will contain the
|
|
* number of items in the array, not counting the NULL terminator.
|
|
*
|
|
* \param storage a storage container.
|
|
* \param path the path of the directory to enumerate.
|
|
* \param pattern the pattern that files in the directory must match. Can be
|
|
* NULL.
|
|
* \param flags `SDL_GLOB_*` bitflags that affect this search.
|
|
* \param count on return, will be set to the number of items in the returned
|
|
* array. Can be NULL.
|
|
* \returns an array of strings on success or NULL on failure; call
|
|
* SDL_GetError() for more information. The caller should pass the
|
|
* returned pointer to SDL_free when done with it. This is a single
|
|
* allocation that should be freed with SDL_free() when it is no
|
|
* longer needed.
|
|
*
|
|
* \threadsafety It is safe to call this function from any thread, assuming
|
|
* the `storage` object is thread-safe.
|
|
*
|
|
* \since This function is available since SDL 3.0.0.
|
|
*/
|
|
extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count);
|
|
|
|
/* Ends C function definitions when using C++ */
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
#include <SDL3/SDL_close_code.h>
|
|
|
|
#endif /* SDL_storage_h_ */
|