System.Net.Sockets.NetworkStream Class

public class NetworkStream : Stream

Base Types

Object
  MarshalByRefObject
    Stream
      NetworkStream

This type implements IDisposable.

Assembly

System

Library

Networking

Summary

Implements the standard stream mechanism to read and write network data through an instance of the Socket class.

Description

The NetworkStream class allows network data to be read and written in the same manner as the Stream class.

This class supports simultaneous synchronous and asynchronous access to the network data. Random access is not supported and thus the System.Net.Sockets.NetworkStream.CanSeek property always returns false.

The following properties and methods inherited from the Stream class are not supported and throw a NotSupportedException exception when accessed:

• System.Net.Sockets.NetworkStream.Length
• System.Net.Sockets.NetworkStream.Position
• System.Net.Sockets.NetworkStream.Seek(System.Int64,System.IO.SeekOrigin)
• System.Net.Sockets.NetworkStream.SetLength(System.Int64)

The System.Net.Sockets.NetworkStream.Flush method is reserved for future use but does not throw an exception.

See Also

System.Net.Sockets Namespace

Members

NetworkStream Constructors

NetworkStream(System.Net.Sockets.Socket) Constructor
NetworkStream(System.Net.Sockets.Socket, bool) Constructor
NetworkStream(System.Net.Sockets.Socket, System.IO.FileAccess) Constructor
NetworkStream(System.Net.Sockets.Socket, System.IO.FileAccess, bool) Constructor

NetworkStream Methods

NetworkStream.BeginRead Method
NetworkStream.BeginWrite Method
NetworkStream.Close Method
NetworkStream.Dispose Method
NetworkStream.EndRead Method
NetworkStream.EndWrite Method
NetworkStream.Finalize Method
NetworkStream.Flush Method
NetworkStream.Read Method
NetworkStream.Seek Method
NetworkStream.SetLength Method
NetworkStream.Write Method

NetworkStream Properties

NetworkStream.CanRead Property
NetworkStream.CanSeek Property
NetworkStream.CanWrite Property
NetworkStream.DataAvailable Property
NetworkStream.Length Property
NetworkStream.Position Property

Constructs and initializes a new instance of the NetworkStream class.

Parameters

socket

An instance of the Socket class.

Exceptions

Exception Type	Condition
ArgumentNullException	socket is null .
IOException	The System.Net.Sockets.Socket.Blocking property of socket is false . -or- The System.Net.Sockets.Socket.Connected property of socket is false . -or- The System.Net.Sockets.Socket.SocketType property of socket is not System.Net.Sockets.SocketType.Stream.

Description

This constructor is equivalent to System.Net.Sockets.NetworkStream.NetworkStream(socket, System.IO.FileAccess.ReadWrite, false ).

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Constructs and initializes a new instance of the NetworkStream class.

Parameters

socket

An instance of the Socket class.

ownsSocket

true if socket is owned by the current instance; otherwise, false .

Exceptions

Exception Type	Condition
ArgumentNullException	socket is null .
IOException	The System.Net.Sockets.Socket.Blocking property of socket is false . -or- The System.Net.Sockets.Socket.Connected property of socket is false . -or- The System.Net.Sockets.Socket.SocketType property of socket is not System.Net.Sockets.SocketType.Stream.

Description

This constructor is equivalent to System.Net.Sockets.NetworkStream.NetworkStream(socket, System.IO.FileAccess.ReadWrite, ownsSocket).

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Constructs and initializes a new instance of the NetworkStream class.

Parameters

socket

An instance of the Socket class.

access

One of the values of the FileAccess enumeration.

Exceptions

Exception Type	Condition
ArgumentNullException	socket is null .
IOException	The System.Net.Sockets.Socket.Blocking property of socket is false . -or- The System.Net.Sockets.Socket.Connected property of socket is false . -or- The System.Net.Sockets.Socket.SocketType property of socket is not System.Net.Sockets.SocketType.Stream.

Description

This constructor is equivalent to System.Net.Sockets.NetworkStream.NetworkStream(socket, access, false ).

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Constructs and initializes a new instance of the NetworkStream class.

Parameters

socket

An instance of the Socket class.

access

One of the values of the FileAccess enumeration.

ownsSocket

true if socket is owned by the current instance; otherwise, false .

Exceptions

Exception Type	Condition
ArgumentNullException	socket is null .
IOException	The System.Net.Sockets.Socket.Blocking property of socket is false . -or- The System.Net.Sockets.Socket.Connected property of socket is false . -or- The System.Net.Sockets.Socket.SocketType property of socket is not System.Net.Sockets.SocketType.Stream.

Description

socket is required to be an instance of the Socket class with its System.Net.Sockets.Socket.Connected property equal to true , System.Net.Sockets.Socket.Blocking property equal to true , and SocketType equal to System.Net.Sockets.SocketType.Stream.

When ownsSocket is true , the current instance owns socket, meaning the System.Net.Sockets.NetworkStream.Close and System.Net.Sockets.NetworkStream.Dispose(System.Boolean) methods call the System.Net.Sockets.Socket.Close method of socket.

The System.Net.Sockets.NetworkStream.Readable and System.Net.Sockets.NetworkStream.Writeable properties are set depending on the value of access. If access is not one of the values defined in the FileAccess enumeration, the System.Net.Sockets.NetworkStream.Readable and System.Net.Sockets.NetworkStream.Writeable properties are set to true .

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

buffer

A Byte array to store data read from the stream.

offset

A Int32 containing the zero-based position in buffer at which to begin storing the data.

size

A Int32 containing the number of bytes to read.

callback

A AsyncCallback delegate, or null .

state

An application-defined object, or null .

Return Value

A IAsyncResult instance that contains information about the asynchronous operation.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null .
ArgumentOutOfRangeException	offset < 0. -or- offset > buffer.Length. -or- size < 0. -or- size > buffer.Length - offset.
IOException	An error occurred while accessing the underlying socket. [Note: Any exception thrown by the System.Net.Sockets.Socket.BeginReceive(System.Byte[],System.Int32,System.Int32,System.Net.Sockets.SocketFlags,System.AsyncCallback,System.Object) method is caught and rethrown as an IOException with the original exception stored in the System.Exception.InnerException property.]
ObjectDisposedException	The current instance has been disposed.

Description

To retrieve the results of the operation and release resources allocated by the System.Net.Sockets.NetworkStream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method, call the System.Net.Sockets.NetworkStream.EndRead(System.IAsyncResult) method, and specify the IAsyncResult object returned by this method.

[Note: The System.Net.Sockets.NetworkStream.EndRead(System.IAsyncResult) method should be called exactly once for each call to the System.Net.Sockets.NetworkStream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method.]

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 method referenced by callback can retrieve the results of the operation by calling the System.Net.Sockets.NetworkStream.EndRead(System.IAsyncResult) method.

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: This method overrides System.IO.Stream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object).

]

Example

For an outline of an asynchronous operation, see the System.Net.Sockets.Socket.BeginAccept(System.AsyncCallback,System.Object) method. For the complete example, see the Socket class overview.

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

buffer

A Byte array containing data to write to the stream.

offset

A Int32 containing the zero-based position in buffer containing the starting location of the data to write.

size

A Int32 containing the number of bytes to write to the stream.

callback

A AsyncCallback delegate, or null .

state

An application-defined object, or null .

Return Value

A IAsyncResult instance that contains information about the asynchronous operation.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null .
ArgumentOutOfRangeException	offset < 0. -or- offset > buffer.Length. -or- size < 0. -or- size > buffer.Length - offset.
IOException	An error occurred while accessing the underlying socket. [Note: Any exception thrown by the System.Net.Sockets.Socket.BeginSend(System.Byte[],System.Int32,System.Int32,System.Net.Sockets.SocketFlags,System.AsyncCallback,System.Object) method is caught and rethrown as an IOException with the original exception stored in the System.Exception.InnerException property.]
ObjectDisposedException	The current instance has been disposed.

Description

To release resources allocated by the System.Net.Sockets.NetworkStream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method, call the System.Net.Sockets.NetworkStream.EndWrite(System.IAsyncResult) method, and specify the IAsyncResult object returned by this method.

[Note: The System.Net.Sockets.NetworkStream.EndWrite(System.IAsyncResult) method should be called exactly once for each call to the System.Net.Sockets.NetworkStream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method.]

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 method referenced by callback can retrieve the results of the operation by calling the System.Net.Sockets.NetworkStream.EndWrite(System.IAsyncResult) method.

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: This method overrides System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object).

]

Example

For an outline of an asynchronous operation, see the System.Net.Sockets.Socket.BeginAccept(System.AsyncCallback,System.Object) method. For the complete example, see the Socket class overview.

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

This method calls System.Net.Sockets.NetworkStream.Dispose(System.Boolean)(true ), which frees both managed and unmanaged resources used by the current instance. When the underlying socket is owned by the current instance, the System.Net.Sockets.Socket.Close method of the socket is called, which frees both managed and unmanaged resources used by the socket.

[Note: Ownership of a socket is specified using the NetworkStream constructor.

This method overrides System.IO.Stream.Close.

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

disposing

A Boolean. Specify true to release both managed and unmanaged resources; specify false to release only unmanaged resources.

Description

[Note: Ownership of a socket is specified using the NetworkStream constructor.

The System.Net.Sockets.NetworkStream.Close method calls this method with the disposing parameter set to true . The finalizer calls this method with the disposing parameter set to false .

]

[Behaviors: This method closes the current NetworkStream instance releasing all unmanaged resources allocated by the current instance. When the underlying socket is owned by the current instance, the System.Net.Sockets.Socket.Close method of the socket is called, which frees the managed and unmanaged resources used by the socket. When the disposing parameter is true , this method also releases all resources held by any other managed objects allocated by the current instance. ]

[Default: This method closes the current NetworkStream instance releasing all unmanaged resources allocated by the current instance. When the underlying socket is owned by the current instance, the System.Net.Sockets.Socket.Close method of the socket is called, which frees the managed and unmanaged resources used by the socket. ]

[Overrides: The System.Net.Sockets.Socket.Dispose(System.Boolean) method can be called multiple times by other objects. When overriding this method, do not reference objects that have been previously disposed in an earlier call. ]

[Usage: Use this method to release resources allocated by the current instance. ]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

asyncResult

A IAsyncResult object that holds the state information for the asynchronous operation.

Return Value

A Int32 containing the number of bytes read from the stream.

Exceptions

Exception Type	Condition
ArgumentNullException	asyncResult is null .
IOException	An error occurred while accessing the underlying socket. [Note: This method catches all exceptions thrown by the System.Net.Sockets.Socket.EndReceive(System.IAsyncResult) method.]
ObjectDisposedException	The current instance has been disposed.

Description

This method blocks if the asynchronous operation has not completed.

The System.Net.Sockets.NetworkStream.EndRead(System.IAsyncResult) method completes an asynchronous request that was started with a call to the System.Net.Sockets.NetworkStream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method. The object specified for the asyncResult parameter is required to be the same object as was returned by the System.Net.Sockets.NetworkStream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method call that began the request.

If the System.Net.Sockets.NetworkStream.EndRead(System.IAsyncResult) method is invoked via the AsyncCallback delegate specified to the System.Net.Sockets.NetworkStream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method, the asyncResult parameter is the IAsyncResult argument passed to the delegate's method.

[Note: This method overrides System.IO.Stream.EndRead(System.IAsyncResult).

]

Example

For an outline of an asynchronous operation, see the System.Net.Sockets.Socket.BeginAccept(System.AsyncCallback,System.Object) method. For the complete example, see the Socket class overview.

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

asyncResult

A IAsyncResult object that holds the state information for the asynchronous operation.

Exceptions

Exception Type	Condition
ArgumentNullException	asyncResult is null .
IOException	An error occurred while accessing the underlying socket. [Note: This method catches all exceptions thrown by the System.Net.Sockets.Socket.EndSend(System.IAsyncResult) method.]
ObjectDisposedException	The current instance has been disposed.

Description

This method blocks if the asynchronous operation has not completed.

The System.Net.Sockets.NetworkStream.EndWrite(System.IAsyncResult) method completes an asynchronous request that was started with a call to the System.Net.Sockets.NetworkStream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method. The object specified for the asyncResult parameter is required to be the same object as was returned by the System.Net.Sockets.NetworkStream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method call that began the request.

If the System.Net.Sockets.NetworkStream.EndWrite(System.IAsyncResult) method is invoked via the AsyncCallback delegate specified to the System.Net.Sockets.NetworkStream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object) method, the asyncResult parameter is the IAsyncResult argument passed to the delegate's method.

[Note: This method overrides System.IO.Stream.EndWrite(System.IAsyncResult).

]

Example

For an outline of an asynchronous operation, see the System.Net.Sockets.Socket.BeginAccept(System.AsyncCallback,System.Object) method. For the complete example, see the Socket class overview.

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

[Note: Application code does not call this method; it is automatically invoked during garbage collection unless finalization by the garbage collector has been disabled. For more information, see System.GC.SuppressFinalize(System.Object), and System.Object.Finalize.

This method calls System.Net.Sockets.NetworkStream.Dispose(System.Boolean)(false ), which frees unmanaged resources used by the current instance. When the underlying socket is owned by the current instance, it is closed and the managed and unmanaged resources used by the socket are freed.

Ownership of a socket is specified using the NetworkStream constructor.

This method overrides System.Object.Finalize.

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

buffer

A Byte array to store data read from the stream.

offset

A Int32 containing the zero-based position in buffer at which to begin storing the data.

size

A Int32 containing the number of bytes to read.

Return Value

A Int32 containing the number of bytes read from the stream.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null .
ArgumentOutOfRangeException	offset < 0. -or- offset > buffer.Length. -or- size < 0. -or- size > buffer.Length - offset.
IOException	An error occurred while accessing the underlying socket. [Note: This method catches all exceptions thrown by the System.Net.Sockets.Socket.Receive(System.Byte[],System.Int32,System.Net.Sockets.SocketFlags) method.]
ObjectDisposedException	The current instance has been disposed.

Description

When no incoming data is available, this method blocks and waits for data to arrive.

If the remote socket was shut down gracefully (System.Net.Sockets.Socket.Shutdown(System.Net.Sockets.SocketShutdown) was called on the socket or the System.Net.Sockets.SocketOptionName.Linger option was enabled and System.Net.Sockets.Socket.Close was called on the socket) and all data was received, this method immediately returns zero.

[Note: This method overrides System.IO.Stream.Read(System.Byte[],System.Int32,System.Int32).

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Throws a NotSupportedException.

Parameters

offset

This parameter is not used.

origin

This parameter is not used.

Exceptions

Exception Type	Condition
NotSupportedException	Any call to this method.

Description

[Note: The Stream base class uses this method to set the current position in the stream. This functionality is not supported in the NetworkStream class.

This method overrides System.IO.Stream.Seek(System.Int64,System.IO.SeekOrigin).

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Throws a NotSupportedException.

Parameters

value

This parameter is not used.

Exceptions

Exception Type	Condition
NotSupportedException	Any call to this method.

Description

[Note: The Stream base class uses this method to set the length of the data available on the stream. This functionality is not supported in the NetworkStream class.

This method overrides System.IO.Stream.SetLength(System.Int64).

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

buffer

A Byte array containing data to write to the stream.

offset

A Int32 containing the zero-based position in buffer containing the starting location of the data to write.

size

A Int32 containing the number of bytes to write to the stream.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null .
ArgumentOutOfRangeException	offset < 0. -or- offset > buffer.Length. -or- size < 0. -or- size > buffer.Length - offset.
IOException	An error occurred while accessing the underlying socket. [Note: This method catches all exceptions thrown by the System.Net.Sockets.Socket.Send(System.Byte[],System.Int32,System.Net.Sockets.SocketFlags) method.]
ObjectDisposedException	The current instance has been disposed.

Description

When no buffer space is available within the underlying protocol, this method blocks unless the socket is in non-blocking mode.

[Note: This method overrides System.IO.Stream.Write(System.Byte[],System.Int32,System.Int32).

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

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

Property Value

true indicates that the current stream supports reading; false . indicates that the current stream does not support reading.

Description

This property is read-only.

The value of this property is initially set by the NetworkStream constructors and can be changed using the System.Net.Sockets.NetworkStream.Readable property.

[Note: This property overrides System.IO.Stream.CanRead.

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Returns the Boolean value false to indicate that the NetworkStream class cannot access a specific location in the data stream.

Property Value

false .

Description

This property is read-only.

[Note: This property overrides System.IO.Stream.CanSeek.

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

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

Property Value

true indicates that the current stream supports writing; false indicates that the current stream does not support writing.

Description

This property is read-only.

The value of this property is initially set by the NetworkStream constructors and can be changed using the System.Net.Sockets.NetworkStream.Writeable property.

[Note: This property overrides System.IO.Stream.CanWrite.

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Gets a Boolean value indicating whether data is available to be read from the underlying socket buffer.

Property Value

true indicates that data is available to be read; false indicates that there is no data available to be read.

Exceptions

Exception Type	Condition
ObjectDisposedException	The current instance has been disposed.

Description

This property is read-only.

[Behaviors: As described above. ]

[Default: Accessing this property causes a call to the System.Net.Sockets.Socket.Available method of the underlying Socket instance. If the Available method returns a non-zero value, indicating data is available to be read, this property returns true ; otherwise, this property returns false . ]

[Overrides: Override this property to determine if data is available to be read in the underlying socket buffer. ]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Throws a NotSupportedException.

Exceptions

Exception Type	Condition
NotSupportedException	Any attempt to access this property.

Description

[Note: The Stream base class implements this property to return the length of the data available on the stream. This functionality is not supported in the NetworkStream class.

This property overrides System.IO.Stream.Length.

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace

Throws a NotSupportedException.

Exceptions

Exception Type	Condition
NotSupportedException	Any attempt to access this property.

Description

[Note: The Stream base class implements this property to return or set the current position in the stream. This functionality is not supported in the NetworkStream class.

This property overrides System.IO.Stream.Position.

]

See Also

System.Net.Sockets.NetworkStream Class, System.Net.Sockets Namespace