System.IO.Stream Class

public abstract class Stream : MarshalByRefObject, IDisposable

Base Types

Object
  MarshalByRefObject
    Stream

This type implements IDisposable.

Assembly

mscorlib

Library

BCL

Summary

Abstract base class for all stream implementations.

Description

Streams involve three fundamental operations:

All classes that represent streams inherit from the Stream class. The Stream class and its subclasses provide a generic view of data sources and repositories, isolating the programmer from the specific details of the operating system and underlying devices.

Subclasses are required to provide implementations only for the synchronous read and write methods. The asynchronous read and write methods are implemented via the synchronous ones. [Note: The Stream synchronous read and write methods are System.IO.Stream.Read(System.Byte[],System.Int32,System.Int32) and System.IO.Stream.Write(System.Byte[],System.Int32,System.Int32). The asynchronous read and write methods are System.IO.Stream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object), System.IO.Stream.EndRead(System.IAsyncResult), System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object), and System.IO.Stream.EndWrite(System.IAsyncResult).]

Depending on the underlying data source or repository, streams might support only some of these capabilities. An application can query a stream for its capabilities by using the System.IO.Stream.CanRead, System.IO.Stream.CanWrite, and System.IO.Stream.CanSeek properties.

The System.IO.Stream.Read(System.Byte[],System.Int32,System.Int32) and System.IO.Stream.Write(System.Byte[],System.Int32,System.Int32) methods read and write data in a variety of formats. For streams that support seeking, the System.IO.Stream.Seek(System.Int64,System.IO.SeekOrigin) and System.IO.Stream.SetLength(System.Int64) methods, and the System.IO.Stream.Position and System.IO.Stream.Length properties can be used to query and modify the current position and length of a stream.

Some stream implementations perform local buffering of the underlying data to improve performance. For such streams, the System.IO.Stream.Flush method can be used to clear any internal buffers and ensure that all data has been written to the underlying data source or repository.

Calling System.IO.Stream.Close on a Stream flushes any buffered data, essentially calling System.IO.Stream.Flush for you. System.IO.Stream.Close also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The System.IO.BufferedStream class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance.

If you need a Stream with no backing store (i.e., a bit bucket), use System.IO.Stream.Null .

See Also

System.IO Namespace

Members

Stream Constructors

Stream Constructor

Stream Methods

Stream.BeginRead Method
Stream.BeginWrite Method
Stream.Close Method
Stream.CreateWaitHandle Method
Stream.EndRead Method
Stream.EndWrite Method
Stream.Flush Method
Stream.Read Method
Stream.ReadByte Method
Stream.Seek Method
Stream.SetLength Method
Stream.System.IDisposable.Dispose Method
Stream.Write Method
Stream.WriteByte Method

Stream Fields

Stream.Null Field

Stream Properties

Stream.CanRead Property
Stream.CanSeek Property
Stream.CanWrite Property
Stream.Length Property
Stream.Position Property


Stream Constructor

protected Stream();

Summary

Constructs a new instance of the Stream class.

See Also

System.IO.Stream Class, System.IO Namespace

Stream.BeginRead Method

public virtual IAsyncResult BeginRead(byte[] buffer, int offset, int count, AsyncCallback callback, object state);

Summary

Begins an asynchronous read operation.

Parameters

buffer
The Byte array to read the data into.
offset
A Int32 that specifies the byte offset in buffer at which to begin writing data read from the stream.
count
A Int32 that specifies the maximum number of bytes to read from the stream.
callback
A AsyncCallback delegate to be called when the read is complete, or null .
state
An application-defined object, or null .

Return Value

A IAsyncResult that contains information about the asynchronous read operation, which could still be pending.

Exceptions

Exception TypeCondition
IOExceptionAn I/O error occurred.
NotSupportedExceptionThe current Stream does not support reading.

Description

This method starts an asynchronous read operation. To determine how many bytes were read and release resources allocated by this method, call the System.IO.Stream.EndRead(System.IAsyncResult) method and specify the IAsyncResult object returned by this method. [Note: The System.IO.Stream.EndRead(System.IAsyncResult) method should be called exactly once for each call to System.IO.Stream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object).]

If the callback parameter is not null , the method referenced by callback is invoked when the asynchronous operation completes. The IAsyncResult object returned by this method is passed as the argument to the method referenced by callback.

The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes.

Multiple simultaneous asynchronous requests render the request completion order uncertain.

The state parameter can be any object that the caller wishes to have available for the duration of the asynchronous operation. This object is available via the System.IAsyncResult.AsyncState property of the object returned by this method.

[Note: Use the System.IO.Stream.CanRead property to determine whether the current instance supports reading.]

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.BeginWrite Method

public virtual IAsyncResult BeginWrite(byte[] buffer, int offset, int count, AsyncCallback callback, object state);

Summary

Begins an asynchronous write operation.

Parameters

buffer
The Byte array to be written to the current stream.
offset
A Int32 that specifies the byte offset in buffer at which to begin copying bytes to the current stream.
count
A Int32 that specifies the maximum number of bytes to be written to the current stream.
callback
A AsyncCallback delegate to be called when the write is complete, or null .
state
An application-defined object, or null .

Return Value

A IAsyncResult that represents the asynchronous write, which could still be pending.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe current Stream does not support writing.
IOExceptionAn I/O error occurred.

Description

Pass the IAsyncResult returned by this method to System.IO.Stream.EndWrite(System.IAsyncResult) to ensure that the write completes and frees resources appropriately. If an error occurs during an asynchronous write, an exception will not be thrown until System.IO.Stream.EndWrite(System.IAsyncResult) is called with the IAsyncResult returned by this method. [Note: If a failure is detected from the underlying OS (such as if a floppy is ejected in the middle of the operation), the results of the write operation are undefined.]

If the callback parameter is not null , the method referenced by callback is invoked when the asynchronous operation completes. The IAsyncResult object returned by this method is passed as the argument to the method referenced by callback.

The state parameter can be any object that the caller wishes to have available for the duration of the asynchronous operation. This object is available via the System.IAsyncResult.AsyncState property of the object returned by this method.

If a stream is writable, writing at the end of it expands the stream.

The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain.

[Note: buffer should generally be greater than 64 KB.

Use the System.IO.Stream.CanWrite property to determine whether the current instance supports writing.

]

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Close Method

public virtual void Close();

Summary

Closes the current stream and releases any resources associated with the current stream.

Description

Following a call to this method, other operations on the stream might throw exceptions. If the stream is already closed, a call to System.IO.Stream.Close throws no exceptions.

[Note: If this method is called while an asynchronous read or write is pending for a stream, the behavior of the stream is undefined. ]

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.CreateWaitHandle Method

protected virtual WaitHandle CreateWaitHandle();

Summary

Allocates a WaitHandle object.

Return Value

A reference to the allocated WaitHandle.

Description

When called for the first time this method creates a WaitHandle object and returns it. On subsequent calls, the System.IO.Stream.CreateWaitHandle method returns a reference to the same wait handle.

[Note: System.IO.Stream.CreateWaitHandle is useful if you implement the asynchronous methods and require a way of blocking in System.IO.Stream.EndRead(System.IAsyncResult) or System.IO.Stream.EndWrite(System.IAsyncResult) until the asynchronous operation is complete.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.EndRead Method

public virtual int EndRead(IAsyncResult asyncResult);

Summary

Ends a pending asynchronous read request.

Parameters

asyncResult
The IAsyncResult object that references the pending asynchronous read request.

Return Value

A Int32 that indicates the number of bytes read from the stream, between 0 and the number of bytes specified via the System.IO.Stream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object)count parameter. Streams only return 0 at the end of the stream, otherwise, they block until at least 1 byte is available.

Exceptions

Exception TypeCondition
ArgumentNullExceptionasyncResult is null .
ArgumentExceptionasyncResult did not originate from a System.IO.Stream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method on the current stream.

Description

System.IO.Stream.EndRead(System.IAsyncResult) blocks until the I/O operation has completed.

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.EndWrite Method

public virtual void EndWrite(IAsyncResult asyncResult);

Summary

Ends an asynchronous write operation.

Parameters

asyncResult
A IAsyncResult that references the outstanding asynchronous I/O request.

Exceptions

Exception TypeCondition
ArgumentNullExceptionThe asyncResult parameter is null .
ArgumentExceptionasyncResult did not originate from a System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method on the current stream.

Description

System.IO.Stream.EndWrite(System.IAsyncResult) is required to be called exactly once for every System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object). System.IO.Stream.EndWrite(System.IAsyncResult) blocks until the write I/O operation has completed.

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Flush Method

public abstract void Flush();

Summary

Flushes the internal buffer.

Exceptions

Exception TypeCondition
IOExceptionAn I/O error occurs, such as the file being already closed.

Description

[Note: Implementers should use this method to move any information from an underlying buffer to its destination. The System.IO.Stream.Flush method should clear the buffer, but the stream should not be closed. Depending upon the state of the object, the current position within the stream might need to be modified (for example, if the underlying stream supports seeking). For additional information see System.IO.Stream.CanSeek .]

[Behaviors: As described above.]

[Overrides: Override System.IO.Stream.Flush on streams that implement a buffer.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Read Method

public abstract int Read(byte[] buffer, int offset, int count);

Summary

Reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Parameters

buffer
A Byte array. When this method returns, the elements between offset and (offset + count) are replaced by the bytes read from the current source.
offset
A Int32 that specifies the zero based byte offset in buffer at which to begin storing the data read from the current stream.
count
A Int32 that specifies the maximum number of bytes to be read from the current stream.

Return Value

A Int32 that specifies the total number of bytes read into the buffer, or zero if the end of the stream has been reached before any data can be read.

Exceptions

Exception TypeCondition
ArgumentException(offset + count ) is greater than the length of buffer.
ArgumentNullExceptionbuffer is null .
ArgumentOutOfRangeExceptionoffset or count is less than zero.
IOException An I/O error occurred.
NotSupportedExceptionThe current stream does not support reading.

Description

[Note: Use the System.IO.Stream.CanRead property to determine whether the current instance supports reading.]

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.ReadByte Method

public virtual int ReadByte();

Summary

Reads a byte from the stream and advances the position within the stream by one byte.

Return Value

The unsigned byte cast to a Int32 , or -1 if at the end of the stream.

Exceptions

Exception TypeCondition
IOExceptionThe stream is closed.
NotSupportedExceptionThe stream does not support reading.

Description

[Behaviors: As described above.]

[Note: Use the System.IO.Stream.CanRead property to determine whether the current instance supports reading.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Seek Method

public abstract long Seek(long offset, SeekOrigin origin);

Summary

Sets the position within the current stream.

Parameters

offset
A Int64 that specifies the byte offset relative to origin.
origin
A SeekOrigin value indicating the reference point used to obtain the new position.

Return Value

A Int64 that specifies the new position within the current stream.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe stream does not support seeking, such as if the stream is constructed from a pipe or console output.
ObjectDisposedExceptionThe current Stream is closed.
IOExceptionAn I/O error has occurred.

Description

[Note: Use the System.IO.Stream.CanSeek property to determine whether the current instance supports seeking.]

[Behaviors: If offset is negative, the new position is required to precede the position specified by origin by the number of bytes specified by offset. If offset is zero, the new position is required to be the position specified by origin. If offset is positive, the new position is required to follow the position specified by origin by the number of bytes specified by offset.]

[Overrides: If you intend to use a file as a backing store for a stream implementation, you are required to override System.IO.Stream.Seek(System.Int64,System.IO.SeekOrigin) to set the System.IO.Stream.Position property one byte beyond the end of the stream. Opening a new file and then writing to it requires that the position be set to one byte beyond the end of the stream. The position cannot be set to more than one byte beyond the end of the stream.

Classes derived from Stream that support seeking are required to override this method.

]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.SetLength Method

public abstract void SetLength(long value);

Summary

Sets the length of the current stream.

Parameters

value
A Int64 that specifies the desired length of the current stream in bytes.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe stream does not support both writing and seeking, such as if the stream is constructed from a pipe or console output.
ObjectDisposedExceptionThe current Stream is closed.
IOExceptionAn I/O error occurred.

Description

[Note: Use the System.IO.Stream.CanWrite property to determine whether the current instance supports writing, and the System.IO.Stream.CanSeek property to determine whether seeking is supported. ]

[Behaviors: If the specified value is less than the current length of the stream, the stream is truncated. If the specified value is larger than the current length of the stream, the stream is expanded. If the stream is expanded, the contents of the stream between the old and the new length are initialized to zeros.]

[Default: There is no default implementation.]

[Overrides: Classes derived from Stream are required to support both writing and seeking for System.IO.Stream.SetLength(System.Int64) to work.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.System.IDisposable.Dispose Method

void IDisposable.Dispose();

Summary

Implemented to support the IDisposable interface. [Note: For more information, see System.IDisposable.Dispose.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Write Method

public abstract void Write(byte[] buffer, int offset, int count);

Summary

Writes a sequence of bytes to the current stream and advances the current position within the current stream by the number of bytes written.

Parameters

buffer
A Byte array containing the data to write.
offset
A Int32 that specifies the zero based byte offset in buffer at which to begin copying bytes to the current stream.
count
A Int32 that specifies the number of bytes to be written to the current stream.

Exceptions

Exception TypeCondition
ArgumentException(offset + count ) is greater than the length of buffer.
ArgumentNullExceptionbuffer is null .
ArgumentOutOfRangeExceptionoffset or count is negative.
IOExceptionAn I/O error occurred.
NotSupportedExceptionThe stream does not support writing.

Description

[Note: Use the System.IO.Stream.CanWrite property to determine whether the current instance supports writing.]

[Behaviors: If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.WriteByte Method

public virtual void WriteByte(byte value);

Summary

Writes a Byte to the current position in the stream and advances the position within the stream by one byte.

Parameters

value
The Byte to write to the stream.

Exceptions

Exception TypeCondition
IOExceptionThe stream is closed.
NotSupportedExceptionThe stream does not support writing.

Description

[Note: Use the System.IO.Stream.CanWrite property to determine whether the current instance supports writing.]

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Null Field

public static readonly Stream Null;

Summary

Returns a Stream with no backing store.

Description

[Note: System.IO.Stream.Null is used to redirect output to a stream that does not consume any operating system resources. When the methods of Stream that provide writing are invoked on System.IO.Stream.Null , they simply return, and no data is written. System.IO.Stream.Null also implements a System.IO.Stream.Read(System.Byte[],System.Int32,System.Int32) method that returns zero without reading data.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.CanRead Property

public abstract bool CanRead { get; }

Summary

Gets a Boolean value indicating whether the current stream supports reading.

Property Value

true if the stream supports reading; otherwise, false .

Description

If a class derived from Stream does not support reading, the following methods throw a NotSupportedException : System.IO.Stream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) , System.IO.Stream.Read(System.Byte[],System.Int32,System.Int32) and System.IO.Stream.ReadByte .

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.CanSeek Property

public abstract bool CanSeek { get; }

Summary

Gets a Boolean value indicating whether the current stream supports seeking.

Property Value

true if the stream supports seeking; otherwise, false .

Description

If a class derived from Stream does not support seeking, the following methods throw a NotSupportedException: System.IO.Stream.Length, System.IO.Stream.SetLength(System.Int64), System.IO.Stream.Position, or System.IO.Stream.Seek(System.Int64,System.IO.SeekOrigin).

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.CanWrite Property

public abstract bool CanWrite { get; }

Summary

Gets a Boolean value indicating whether the current stream supports writing.

Property Value

true if the stream supports writing; otherwise, false .

Description

If a class derived from Stream does not support writing, the following methods throw a NotSupportedException: System.IO.Stream.Write(System.Byte[],System.Int32,System.Int32), System.IO.Stream.WriteByte(System.Byte), and System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object).

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Length Property

public abstract long Length { get; }

Summary

Gets the length in bytes of the stream.

Property Value

A Int64 value representing the length of the stream in bytes.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe stream does not support seeking.

Description

[Note: Use the System.IO.Stream.CanSeek property to determine whether the current instance supports seeking.]

[Behaviors: This property is read-only.]

See Also

System.IO.Stream Class, System.IO Namespace

Stream.Position Property

public abstract long Position { get; set; }

Summary

Gets or sets the position within the current stream.

Property Value

A Int64 that specifies the current position within the stream.

Exceptions

Exception TypeCondition
IOExceptionAn I/O error has occurred, such as the stream being closed.
NotSupportedExceptionThe stream does not support seeking.

Description

The stream is required to support seeking to get or set the position. [Note: Use the System.IO.Stream.CanSeek property to determine whether the current instance supports seeking.]

Classes that derive from Stream are required to provide an implementation of this property.

[Note: If you intend to use a file as a backing store for a stream implementation, opening a new file and then writing to it requires that the position be set to just beyond the last byte so you can append to the file. The position cannot be set more than one byte beyond the end of the stream.

]

[Behaviors: As described above.]

See Also

System.IO.Stream Class, System.IO Namespace