/// <summary>
/// Method to read a fixed-size buffer from the <see cref="Stream"/>. The read must return all bytes
/// in the buffer's length; or else the <see cref="IoResult.Result"/> is
/// <see cref="IoResultState.BadData"/>. Note that this method catches all exceptions and will
/// <see cref="IoResult.Fault"/> the result. The read operation updates the
/// <see cref="IoResult.BytesReadOrWritten"/> property: if there is an incoming value, it is incremented.
/// </summary>
/// <param name="ioResult">Not null.</param>
/// <param name="sourceStream">Not null.</param>
/// <param name="fixedBuffer">Not null.</param>
/// <returns>Completes when the read completes.</returns>
/// <exception cref="ArgumentNullException"></exception>
public static Task <IoResult> ReadAllAsync(this IoResult ioResult, Stream sourceStream, byte[] fixedBuffer)
{
if (ioResult == null)
{
throw new ArgumentNullException(nameof(ioResult));
}
return(IoHelper.ReadAllAsync(sourceStream, fixedBuffer, ioResult));
}
/// <summary>
/// Method to read a fixed-size buffer from the <see cref="Stream"/>. The read must return all bytes
/// in the buffer's length; or else the <see cref="IoResult.Result"/> is
/// <see cref="IoResultState.BadData"/>. Note that this method catches all exceptions and will
/// <see cref="IoResult.Fault"/> the result. The read operation updates the
/// <see cref="IoResult.BytesReadOrWritten"/> property: if there is an incoming value, it is incremented.
/// </summary>
/// <param name="sourceStream">Not null.</param>
/// <param name="fixedBuffer">Not null.</param>
/// <param name="ioResult">Optional. If null, a new instance is created; with any given
/// <see cref="CancellationToken"/>.</param>
/// <param name="cancellationToken">Optional.</param>
/// <returns>Not null. If you provided an argument, the same object is returned.</returns>
/// <exception cref="ArgumentNullException"></exception>
public static async Task <IoResult> ReadAllAsync(
Stream sourceStream,
byte[] fixedBuffer,
IoResult ioResult = null,
CancellationToken cancellationToken = default)
=> await IoHelper.ReadAllAsync(
sourceStream,
fixedBuffer,
0,
fixedBuffer.Length,
ioResult,
cancellationToken);
/// <summary>
/// Method to read from the source <see cref="Stream"/> and write to the sink. NOTICE: this method
/// will ONLY update the <see cref="IoResult.BytesReadOrWritten"/> property if one of the given
/// streams supports seeking. You must test <see cref="Stream.CanSeek"/> to know. Notice also that
/// <see cref="IoResult.BytesReadOrWritten"/> may be 0 when the <see cref="IoResult.Result"/>
/// is <see cref="IoResultState.Success"/>.
/// </summary>
/// <param name="ioResult">Not null.</param>
/// <param name="sourceStream">Not null.</param>
/// <param name="sinkStream">Not null.</param>
/// <param name="bufferSize">Required.</param>
/// <returns>Completes when the copy is coplete.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentOutOfRangeException"></exception>
public static Task <IoResult> CopyToAsync(
this IoResult ioResult,
Stream sourceStream,
Stream sinkStream,
int bufferSize)
{
if (ioResult == null)
{
throw new ArgumentNullException(nameof(ioResult));
}
return(IoHelper.CopyToAsync(sourceStream, sinkStream, bufferSize, ioResult));
}
/// <summary>
/// NOTICE: this method ALWAYS updates the <see cref="IoResult.BytesReadOrWritten"/> property by the given
/// length if the stream does not support seeking. This writes from a buffer to the sink <see cref="Stream"/>.
/// The write may write any length. Note that this method catches all exceptions and will
/// <see cref="IoResult.Fault"/> the result. IF the stream supports seeking, this method updates the
/// <see cref="IoResult.BytesReadOrWritten"/> property based on the change in the stream's Position. Otherwise
/// the value is always explicitly updated by the given length: you must test the stream to know. If there is
/// an incoming value, it is incremented.
/// </summary>
/// <param name="ioResult">Not null.</param>
/// <param name="sinkStream">Not null.</param>
/// <param name="buffer">Not null.</param>
/// <param name="offset">Offset within <c>buffer</c> to begin writing.</param>
/// <param name="length">Length within <c>buffer</c> to write.</param>
/// <returns>Completes when the indicated write completes.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentOutOfRangeException"></exception>
public static Task <IoResult> WriteAsync(
this IoResult ioResult,
Stream sinkStream,
byte[] buffer,
int offset,
int length)
{
if (ioResult == null)
{
throw new ArgumentNullException(nameof(ioResult));
}
return(IoHelper.WriteAsync(sinkStream, buffer, offset, length, ioResult));
}