Object
MarshalByRefObject
StreamThis type implements IDisposable.
mscorlib
BCL
Abstract base class for all stream implementations.
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.
- You can read from streams. Reading is the transfer of data from a stream into a data structure, such as an array of bytes.
- You can write to streams. Writing is the transfer of data from a data structure into a stream.
- Streams can support seeking. Seeking is the querying and modifying of the current position within a stream. Seek capability depends on the kind of backing store a stream has. For example, network streams have no unified concept of a current position, and therefore typically do not support seeking.
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 .
System.IO Namespace
Stream Constructors
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 Properties
Stream.CanRead Property
Stream.CanSeek Property
Stream.CanWrite Property
Stream.Length Property
Stream.Position Property
Constructs a new instance of the Stream class.
System.IO.Stream Class, System.IO Namespace
Begins an asynchronous read operation.
- 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.
A IAsyncResult that contains information about the asynchronous read operation, which could still be pending.
Exception Type Condition IOException An I/O error occurred. NotSupportedException The current Stream does not support reading.
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.]
System.IO.Stream Class, System.IO Namespace
Begins an asynchronous write operation.
- 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.
A IAsyncResult that represents the asynchronous write, which could still be pending.
Exception Type Condition NotSupportedException The current Stream does not support writing. IOException An I/O error occurred.
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.]
System.IO.Stream Class, System.IO Namespace
Closes the current stream and releases any resources associated with the current stream.
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.]
System.IO.Stream Class, System.IO Namespace
Allocates a WaitHandle object.
A reference to the allocated WaitHandle.
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.]
System.IO.Stream Class, System.IO Namespace
Ends a pending asynchronous read request.
- asyncResult
- The IAsyncResult object that references the pending asynchronous read request.
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.
Exception Type Condition ArgumentNullException asyncResult is null.ArgumentException asyncResult did not originate from a System.IO.Stream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method on the current stream.
System.IO.Stream.EndRead(System.IAsyncResult) blocks until the I/O operation has completed.[Behaviors: As described above.]
System.IO.Stream Class, System.IO Namespace
Ends an asynchronous write operation.
- asyncResult
- A IAsyncResult that references the outstanding asynchronous I/O request.
Exception Type Condition ArgumentNullException The asyncResult parameter is null.ArgumentException asyncResult did not originate from a System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method on the current stream.
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.]
System.IO.Stream Class, System.IO Namespace
Flushes the internal buffer.
Exception Type Condition IOException An I/O error occurs, such as the file being already closed.
[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.]
System.IO.Stream Class, System.IO Namespace
Reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
- 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.
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.
Exception Type Condition ArgumentException (offset + count ) is greater than the length of buffer. ArgumentNullException buffer is null.ArgumentOutOfRangeException offset or count is less than zero. IOException An I/O error occurred. NotSupportedException The current stream does not support reading.
[Note: Use the System.IO.Stream.CanRead property to determine whether the current instance supports reading.]
[Behaviors: As described above.]
System.IO.Stream Class, System.IO Namespace
Reads a byte from the stream and advances the position within the stream by one byte.
The unsigned byte cast to a Int32 , or -1 if at the end of the stream.
Exception Type Condition IOException The stream is closed. NotSupportedException The stream does not support reading.
[Behaviors: As described above.]
[Note: Use the System.IO.Stream.CanRead property to determine whether the current instance supports reading.]
System.IO.Stream Class, System.IO Namespace
Sets the position within the current stream.
- 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.
A Int64 that specifies the new position within the current stream.
Exception Type Condition NotSupportedException The stream does not support seeking, such as if the stream is constructed from a pipe or console output. ObjectDisposedException The current Stream is closed. IOException An I/O error has occurred.
[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.
]
System.IO.Stream Class, System.IO Namespace
Sets the length of the current stream.
- value
- A Int64 that specifies the desired length of the current stream in bytes.
Exception Type Condition NotSupportedException The stream does not support both writing and seeking, such as if the stream is constructed from a pipe or console output. ObjectDisposedException The current Stream is closed. IOException An I/O error occurred.
[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.]
System.IO.Stream Class, System.IO Namespace
Implemented to support the IDisposable interface. [Note: For more information, see System.IDisposable.Dispose.]
System.IO.Stream Class, System.IO Namespace
Writes a sequence of bytes to the current stream and advances the current position within the current stream by the number of bytes written.
- 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.
Exception Type Condition ArgumentException (offset + count ) is greater than the length of buffer. ArgumentNullException buffer is null.ArgumentOutOfRangeException offset or count is negative. IOException An I/O error occurred. NotSupportedException The stream does not support writing.
[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.]
System.IO.Stream Class, System.IO Namespace
Writes a Byte to the current position in the stream and advances the position within the stream by one byte.
- value
- The Byte to write to the stream.
Exception Type Condition IOException The stream is closed. NotSupportedException The stream does not support writing.
[Note: Use the System.IO.Stream.CanWrite property to determine whether the current instance supports writing.]
[Behaviors: As described above.]
System.IO.Stream Class, System.IO Namespace
Returns a Stream with no backing store.
[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.]
System.IO.Stream Class, System.IO Namespace
public abstract bool CanRead { get; }
Gets a Boolean value indicating whether the current stream supports reading.
trueif the stream supports reading; otherwise,false.
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.]
System.IO.Stream Class, System.IO Namespace
public abstract bool CanSeek { get; }
Gets a Boolean value indicating whether the current stream supports seeking.
trueif the stream supports seeking; otherwise,false.
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.]
System.IO.Stream Class, System.IO Namespace
public abstract bool CanWrite { get; }
Gets a Boolean value indicating whether the current stream supports writing.
trueif the stream supports writing; otherwise,false.
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.]
System.IO.Stream Class, System.IO Namespace
public abstract long Length { get; }
Gets the length in bytes of the stream.
A Int64 value representing the length of the stream in bytes.
Exception Type Condition NotSupportedException The stream does not support seeking.
[Note: Use the System.IO.Stream.CanSeek property to determine whether the current instance supports seeking.]
[Behaviors: This property is read-only.]
System.IO.Stream Class, System.IO Namespace
public abstract long Position { get; set; }
Gets or sets the position within the current stream.
A Int64 that specifies the current position within the stream.
Exception Type Condition IOException An I/O error has occurred, such as the stream being closed. NotSupportedException The stream does not support seeking.
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.]
System.IO.Stream Class, System.IO Namespace