Handle to an owned iOStream. More...

Inheritance diagram for SDL::IOStream:

[legend]

Public Member Functions
void	Close ()
	Close and free an allocated IOStreamRef structure.

IOStreamShared	share ()
	Move this iOStream into a IOStreamShared.

constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DELETER deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

Public Member Functions inherited from SDL::ResourceUnique< IOStreamRef >
constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DefaultDeleter< IOStreamRef > deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

	~ResourceUnique ()
	Destructor.

constexpr ResourceUnique &	operator= (ResourceUnique other)
	Assignment operator.

void	reset ()
	Resets the value, destroying the resource if not nullptr.

Public Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
RESOURCE	release ()
	Returns reference and reset this.

Public Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	operator bool () const
	Check if not null.

constexpr bool	operator== (const ResourcePtrBase &other) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr reference	operator* () const
	Gets reference.

constexpr const reference *	operator-> () const
	Gets addressable reference.

constexpr reference *	operator-> ()
	Gets addressable reference.

reference	get () const
	Get reference.

Static Public Member Functions
static IOStream	FromFile (StringParam file, StringParam mode)
	Use this function to create a new IOStream structure for reading from and/or writing to a named file.

static IOStream	FromMem (TargetBytes mem)
	Use this function to prepare a read-write memory buffer for use with IOStream.

static IOStream	FromConstMem (SourceBytes mem)
	Use this function to prepare a read-only memory buffer for use with IOStreamRef.

static IOStream	FromDynamicMem ()
	Use this function to create an IOStreamRef that is backed by dynamically allocated memory.

static IOStream	Open (const IOStreamInterface &iface, void *userdata)
	Create a custom IOStreamRef.

Additional Inherited Members
Public Types inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
using	deleter = DELETER
	The deleter type.

Public Types inherited from SDL::ResourcePtrBase< RESOURCE >
using	reference = RESOURCE
	The reference resource type.

using	value_type = typename reference::value_type
	The raw resource type.

Protected Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
constexpr	ResourceOwnerBase (base::value_type value={}, DELETER deleter={})
	Constructs from raw type.

void	free ()
	Frees resource.

Protected Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	ResourcePtrBase (value_type value={})
	Constructs from raw type.

reference &	get ()
	Get reference.

Detailed Description

Category:: Resource

See also: IOStreamRef

Member Function Documentation

◆ Close()

void SDL::IOStream::Close ( )

inline

IOStream.Close() closes and cleans up the IOStreamRef stream. It releases any resources used by the stream and frees the IOStreamRef itself. This returns true on success, or false if the stream failed to flush to its output (e.g. to disk).

Note that if this fails to flush the stream for any reason, this function reports an error, but the IOStreamRef is still invalid once this function returns.

This call flushes any buffered writes to the operating system, but there are no guarantees that those writes have gone to physical media; they might be in the OS's file cache, waiting to go to disk later. If it's absolutely crucial that writes go to disk immediately, so they are definitely stored even if the power fails before the file cache would have caught up, one should call IOStreamRef.Flush() before closing. Note that flushing takes time and makes the system and your app operate less efficiently, so do so sparingly.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Open

◆ FromConstMem()

static IOStream SDL::IOStream::FromConstMem ( SourceBytes mem )

inlinestatic

This function sets up an IOStreamRef struct based on a memory area of a certain size. It assumes the memory area is not writable.

Attempting to write to this IOStreamRef stream will report an error without writing to the memory buffer.

This memory buffer is not copied by the IOStreamRef; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to write to a memory buffer, you should use IOStream.FromMem() with a writable buffer of memory instead.

The following properties will be set at creation time by SDL:

prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a read-only buffer to feed an IOStreamRef stream.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.FromMem; IOStream.Close; IOStreamRef.Read; IOStreamRef.Seek; IOStreamRef.Tell

◆ FromDynamicMem()

static IOStream SDL::IOStream::FromDynamicMem ( )

inlinestatic

This supports the following properties to provide access to the memory and control over allocations:

prop::IOStream.DYNAMIC_MEMORY_POINTER: a pointer to the internal memory of the stream. This can be set to nullptr to transfer ownership of the memory to the application, which should free the memory with free(). If this is done, the next operation on the stream must be IOStream.Close().
prop::IOStream.DYNAMIC_CHUNKSIZE_NUMBER: memory will be allocated in multiples of this size, defaulting to 1024.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; IOStreamRef.Read; IOStreamRef.Seek; IOStreamRef.Tell; IOStreamRef.Write

◆ FromFile()

static IOStream SDL::IOStream::FromFile	(	StringParam	file,
		StringParam	mode
	)

inlinestatic

The mode string is treated roughly the same as in a call to the C library's fopen(), even if SDL doesn't happen to use fopen() behind the scenes.

Available mode strings:

"r": Open a file for reading. The file must exist.
"w": Create an empty file for writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
"a": Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
"r+": Open a file for update both reading and writing. The file must exist.
"w+": Create an empty file for both reading and writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
"a+": Open a file for reading and appending. All writing operations are performed at the end of the file, protecting the previous content to be overwritten. You can reposition (fseek, rewind) the internal pointer to anywhere in the file for reading, but writing operations will move it back to the end of file. The file is created if it does not exist.

NOTE: In order to open a file as a binary file, a "b" character has to be included in the mode string. This additional "b" character can either be appended at the end of the string (thus making the following compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). Additional characters may follow the sequence, although they should have no effect. For example, "t" is sometimes appended to make explicit the file is a text file.

This function supports Unicode filenames, but they must be encoded in UTF-8 format, regardless of the underlying operating system.

In Android, IOStream.FromFile() can be used to open content:// URIs. As a fallback, IOStream.FromFile() will transparently open a matching filename in the app's assets.

Closing the IOStreamRef will close SDL's internal file handle.

The following properties may be set at creation time by SDL:

prop::IOStream.WINDOWS_HANDLE_POINTER: a pointer, that can be cast to a win32 HANDLE, that this IOStreamRef is using to access the filesystem. If the program isn't running on Windows, or SDL used some other method to access the filesystem, this property will not be set.
prop::IOStream.STDIO_FILE_POINTER: a pointer, that can be cast to a stdio FILE *, that this IOStreamRef is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set. PLEASE NOTE that if SDL is using a different C runtime than your app, trying to use this pointer will almost certainly result in a crash! This is mostly a problem on Windows; make sure you build SDL and your app with the same compiler and settings to avoid it.
prop::IOStream.FILE_DESCRIPTOR_NUMBER: a file descriptor that this IOStreamRef is using to access the filesystem.
prop::IOStream.ANDROID_AASSET_POINTER: a pointer, that can be cast to an Android NDK AAsset *, that this IOStreamRef is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set.

Parameters

file	a UTF-8 string representing the filename to open.
mode	an ASCII string representing the mode to be used for opening the file.

Returns: a pointer to the IOStreamRef structure that is created or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; IOStreamRef.Flush; IOStreamRef.Read; IOStreamRef.Seek; IOStreamRef.Tell; IOStreamRef.Write

◆ FromMem()

static IOStream SDL::IOStream::FromMem ( TargetBytes mem )

inlinestatic

This function sets up an IOStreamRef struct based on a memory area of a certain size, for both read and write access.

This memory buffer is not copied by the IOStreamRef; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to make sure the IOStreamRef never writes to the memory buffer, you should use IOStream.FromConstMem() with a read-only buffer of memory instead.

The following properties will be set at creation time by SDL:

prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a buffer to feed an IOStreamRef stream.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.FromConstMem; IOStream.Close; IOStreamRef.Flush; IOStreamRef.Read; IOStreamRef.Seek; IOStreamRef.Tell; IOStreamRef.Write

◆ Open()

static IOStream SDL::IOStream::Open	(	const IOStreamInterface &	iface,
		void *	userdata
	)

inlinestatic

Applications do not need to use this function unless they are providing their own IOStreamRef implementation. If you just need an IOStreamRef to read/write a common data source, you should use the built-in implementations in SDL, like IOStream.FromFile() or IOStream.FromMem(), etc.

This function makes a copy of iface and the caller does not need to keep it around after this call.

Parameters

iface	the interface that implements this IOStreamRef, initialized using SDL_INIT_INTERFACE().
userdata	the pointer that will be passed to the interface functions.

Returns: a valid stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; SDL_INIT_INTERFACE; IOStream.FromConstMem; IOStream.FromFile; IOStream.FromMem

The documentation for this struct was generated from the following file:

SDL3pp/SDL3pp_iostream.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Close()

◆ FromConstMem()

◆ FromDynamicMem()

◆ FromFile()

◆ FromMem()

◆ Open()