Class StreamExtensions

Namespace

Sdl3Sharp.IO

Assembly

Sdl3Sharp.dll

Provides extension methods for Stream

public static class StreamExtensions

Inheritance

object

StreamExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

ToClrStream(Stream, bool, bool?, bool?, bool?)

Creates a .NET (CLR) Stream wrapping the provided SDL Stream

public static SdlToClrStream ToClrStream(this Stream sdlStream, bool leaveOpen = false, bool? canRead = null, bool? canSeek = null, bool? canWrite = null)

Parameters

sdlStream Stream

The SDL Stream to wrap

leaveOpen bool

A value indicating whether to leave the underlying SDL stream open when the wrapper is disposed

canRead bool?

An overwrite flag indicating whether the stream can be read from

canSeek bool?

An overwrite flag indicating whether the stream can be seeked

canWrite bool?

An overwrite flag indicating whether the stream can be written to

Returns

SdlToClrStream

A SdlToClrStream wrapper around the SDL Stream

Remarks

The SdlToClrStream constructor does its best to detect the capabilities of the provided SDL Stream. But in some cases it might not be possible to determine whether the stream can be read from, seeked or written to, or the detection might be wrong. In those cases, you can use the optional canRead, canSeek and canWrite parameters to explicitly specify the capabilities of the stream. Note that, for example specifying true for canWrite for an inherently read-only stream will not magically make it writable, but it will make this wrapper report that it is writable.

Please remember to dispose the returned SdlToClrStream instance when you are done using it to free up any resources.

Exceptions

ArgumentNullException

sdlStream is null

ToSdlStream(Stream, bool)

Creates an SDL Stream wrapping the provided .NET (CLR) Stream

public static Stream ToSdlStream(this Stream clrStream, bool leaveOpen = false)

Parameters

clrStream Stream

The CLR Stream to wrap

leaveOpen bool

A value indicating whether to leave the underlying CLR stream open when the wrapper is disposed

Returns

Stream

A ClrToSdlStream wrapper around the CLR Stream

Remarks

Please remember to dispose the returned ClrToSdlStream instance when you are done using it to free up any resources.

Exceptions

ArgumentNullException

clrStream is null

TryCopyTo(Stream, Stream, out nuint, out nuint, TimeSpan?, nuint)

Tries to copy all data from the source stream into a specified destination stream

public static bool TryCopyTo(this Stream source, Stream destination, out nuint bytesRead, out nuint bytesWritten, TimeSpan? timeout, nuint bufferSize = 4096)

Parameters

source Stream

The source stream to copy data into

destination Stream

The destination stream to copy data into

bytesRead nuint

The number of bytes read from the source stream

bytesWritten nuint

The number of bytes written to the destination stream

timeout TimeSpan?

The time to wait for the destination stream to become ready or fail if exceeded. Fractional nanoseconds will get rounded to next greater whole nanosecond value. Must not be negative and must represent a rounded nanoseconds value that is less or equal to MaxValue. If null, waits indefinitely. If Zero, fails immediately.

bufferSize nuint

The size of the buffer to use for copying. Defaults to 4096.

Returns

bool

true, if the data from the source stream was successfully copied to the destination stream; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method tries to copy as many bytes as possible before returning. bytesRead will be equal to the actual number of bytes read from the stream, while bytesWritten will be equal to the actual number of bytes written to the destination stream, even in the case when not all data could be copied. You should check the stream's Sdl3Sharp.Ffi.Status property as well as the destination's Sdl3Sharp.Ffi.Status property to determine whether a shortened copy operation is recoverable or not.

You may want to specify a timeout value for the time to wait for the destination stream to become ready in asynchronous I/O scenarios. You can specify 0 to fail immediately, if the destination stream is not ready yet. You can also specify null to wait indefinitely for the destination stream to become ready. If the destination stream's Status property is any other value than Ready or NotReady, this methods still fails and returns false. Please notice that the specified timeout value is only for waiting on the destination stream; if the source stream cannot read in time, this method still fails and returns false (this behavior is identical to any other of the TryRead* methods of a Stream, except this method still returns true when the source stream's Status property is Eof and all data was successfully written).

This method is not threadsafe.

Exceptions

ArgumentOutOfRangeException

timeout is negative or the rounded nanosecond value timeout represents is greater than MaxValue

InvalidOperationException

The internal timer SDL uses may have been reset or overflowed during the execution. Only happens when timeout is neither null nor Zero.

ArgumentNullException

destination is null

ArgumentOutOfRangeException

bufferSize is not greater than 0

InvalidOperationException

The internal timer SDL uses may have been reset or overflowed during the execution. Only happens when nanosecondsTimeout is neither null nor 0.

TryCopyTo(Stream, Stream, out nuint, out nuint, uint?, nuint)

Tries to copy all data from the source stream into a specified destination stream

public static bool TryCopyTo(this Stream source, Stream destination, out nuint bytesRead, out nuint bytesWritten, uint? millisecondsTimeout, nuint bufferSize = 4096)

Parameters

source Stream

The source stream to copy data into

destination Stream

The destination stream to copy data into

bytesRead nuint

The number of bytes read from the source stream

bytesWritten nuint

The number of bytes written to the destination stream

millisecondsTimeout uint?

The number of milliseconds to wait for the destination stream to become ready or fail if exceeded. If null, waits indefinitely. If 0, fails immediately.

bufferSize nuint

The size of the buffer to use for copying. Defaults to 4096.

Returns

bool

true, if the data from the source stream was successfully copied to the destination stream; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method tries to copy as many bytes as possible before returning. bytesRead will be equal to the actual number of bytes read from the stream, while bytesWritten will be equal to the actual number of bytes written to the destination stream, even in the case when not all data could be copied. You should check the stream's Sdl3Sharp.Ffi.Status property as well as the destination's Sdl3Sharp.Ffi.Status property to determine whether a shortened copy operation is recoverable or not.

You may want to specify a timeout value for the time to wait for the destination stream to become ready in asynchronous I/O scenarios. You can specify 0 to fail immediately, if the destination stream is not ready yet. You can also specify null to wait indefinitely for the destination stream to become ready. If the destination stream's Status property is any other value than Ready or NotReady, this methods still fails and returns false. Please notice that the specified timeout value is only for waiting on the destination stream; if the source stream cannot read in time, this method still fails and returns false (this behavior is identical to any other of the TryRead* methods of a Stream, except this method still returns true when the source stream's Status property is Eof and all data was successfully written).

This method is not threadsafe.

Exceptions

InvalidOperationException

The internal timer SDL uses may have been reset or overflowed during the execution. Only happens when millisecondsTimeout is neither null nor 0.

ArgumentNullException

destination is null

ArgumentOutOfRangeException

bufferSize is not greater than 0

InvalidOperationException

The internal timer SDL uses may have been reset or overflowed during the execution. Only happens when nanosecondsTimeout is neither null nor 0.

TryCopyTo(Stream, Stream, out nuint, out nuint, ulong?, nuint)

Tries to copy all data from the source stream into a specified destination stream

public static bool TryCopyTo(this Stream source, Stream destination, out nuint bytesRead, out nuint bytesWritten, ulong? nanosecondsTimeout = 0, nuint bufferSize = 4096)

Parameters

source Stream

The source stream to copy data into

destination Stream

The destination stream to copy data into

bytesRead nuint

The number of bytes read from the source stream

bytesWritten nuint

The number of bytes written to the destination stream

nanosecondsTimeout ulong?

The number of nanoseconds to wait for the destination stream to become ready or fail if exceeded. If null, waits indefinitely. If 0, fails immediately. Defaults to 0.

bufferSize nuint

The size of the buffer to use for copying. Defaults to 4096.

Returns

bool

true, if the data from the source stream was successfully copied to the destination stream; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method tries to copy as many bytes as possible before returning. bytesRead will be equal to the actual number of bytes read from the stream, while bytesWritten will be equal to the actual number of bytes written to the destination stream, even in the case when not all data could be copied. You should check the stream's Sdl3Sharp.Ffi.Status property as well as the destination's Sdl3Sharp.Ffi.Status property to determine whether a shortened copy operation is recoverable or not.

You may want to specify a timeout value for the time to wait for the destination stream to become ready in asynchronous I/O scenarios. You can specify 0 to fail immediately, if the destination stream is not ready yet. You can also specify null to wait indefinitely for the destination stream to become ready. If the destination stream's Status property is any other value than Ready or NotReady, this methods still fails and returns false. Please notice that the specified timeout value is only for waiting on the destination stream; if the source stream cannot read in time, this method still fails and returns false (this behavior is identical to any other of the TryRead* methods of a Stream, except this method still returns true when the source stream's Status property is Eof and all data was successfully written).

This method is not threadsafe.

Exceptions

ArgumentNullException

destination is null

ArgumentOutOfRangeException

bufferSize is not greater than 0

InvalidOperationException

The internal timer SDL uses may have been reset or overflowed during the execution. Only happens when nanosecondsTimeout is neither null nor 0.