NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Stream Class

Provides a way to write and read bytes to and from a backing store. This class is abstract.

Object
   Stream

[Visual Basic]
MustInherit Public Class Stream
[C#]
public abstract class Stream
[C++]
public __gc __abstract class Stream
[JScript]
public abstract class Stream

Remarks

This Stream class supports the mixing of synchronous and asynchronous reads and writes on the same stream, regardless of whether the operating system allows this. Stream provides default implementations of asynchronous read and write operations in terms of their synchronous implementations, and provides default implementations of synchronous read and write operations in terms of their asynchronous implementations.

Notes to Implementers: When implementing a subclass of Stream, it is necessary to provide an implementation for either the synchronous or asynchronous Read and Write methods. Overriding Read and Write is sufficient; the default implementations of the asynchronous methods (BeginRead, EndRead, BeginWrite, and EndWrite) will work with your implementation of the synchronous methods. Similarly, the synchronous Read and Write methods will work correctly if you provide an implementation of the asynchronous methods. The default implementations of ReadByte and WriteByte call the synchronous Read and Write methods with a one-element byte array. When subclassing Stream, if you have an internal byte buffer, it is strongly recommended that you override these methods to access your internal buffer for better performance.

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.

Streams involve these three fundamental operations:

  1. Streams can be read from. Reading is the transfer of data from a stream into a data structure, such as an array of bytes.
  2. Streams can be written to. Writing is the transfer of data from a data structure into a stream.
  3. 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.

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 CanRead, CanWrite, and CanSeek properties.

The Read and Write methods read and write data in a variety of formats. For streams that support seeking, the Seek and SetLength methods and the Position and 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 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 Close on a Stream flushes any buffered data, essentially calling Flush for you. Close also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The BufferedStream class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance.

The FileStream class is for reading from and writing to files. This class can be used to read and write bytes, characters, strings, and other data-type values to a file. It is also used to implement the standard in, standard out, and standard error streams.

The File class, used in conjunction with FileStream, is a utility class with static methods primarily for the creation of FileStream objects based on file paths and the standard input, standard output, and standard error devices.

The MemoryStream class provides a way to create streams that have memory as a backing store instead of a disk or a network connection. The MemoryStream class creates a stream out of an array of bytes.

Use BinaryWriter and BinaryReader for writing and reading primitive data types.

Requirements

Namespace: System.IO

Assembly: mscorlib.dll

See Also

Stream Members | System.IO Namespace