xtd::net::sockets::network_stream Class Reference

Inheritance diagram for xtd::net::sockets::network_stream:

Definition

Provides the underlying stream of data for network access.

class core_export_ network_stream : public xtd::io::stream;

Inheritance

xtd::object → xtd::abstract_object → xtd::io::stream → xtd::net::sockets::network_stream

Header

#include <xtd/net/sockets/network_stream>

Namespace

xtd::net::sockets

Library

xtd.core

Remarks

The xtd::net::sockets::network_stream class provides methods for sending and receiving data over std::iostream sockets in blocking mode. You can use the xtd::net::sockets::network_stream class for both synchronous and asynchronous data transfer.

To create a xtd::net::sockets::network_stream, you must provide a connected xtd::net::sockets::socket. By default, closing the xtd::net::sockets::network_stream does not close the provided xtd::net::sockets::socket. If you want the xtd::net::sockets::network_stream to have permission to close the provided xtd::net::sockets::socket, you must specify true for the value of the owns_socket parameter.

Use the std::iostream::write and std::iostream::read methods for simple single thread synchronous blocking I/O.

The xtd::net::sockets::network_stream does not support random access to the network data stream.

std::iostream::read and std::iostream::write operations can be performed simultaneously on an instance of the xtd::net::sockets::network_stream class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required.

Examples

The following example shows how to use xtd::net::sockets::network_stream class with xtd::net::sockets::socket, xtd::io::stream_reader and xtd::io::stream_writer classes.

#include <xtd/xtd>
 
auto main() -> int {
  auto terminate_app = false;
  
  auto server = thread {[&] {
    auto server_socket = net::sockets::socket {net::sockets::address_family::inter_network, net::sockets::socket_type::stream, net::sockets::protocol_type::tcp};
    server_socket.bind(net::ip_end_point {net::ip_address::any, 9400});
    server_socket.listen();
    auto stream = net::sockets::network_stream {server_socket.accept(), file_access::read};
    auto reader = stream_reader {stream};
    
    while (!terminate_app)
      if (stream.data_available()) console::write_line(reader.read_line());
  }};
  server.start();
  
  auto client = thread {[&] {
    auto stream = net::sockets::network_stream {net::sockets::socket {net::sockets::address_family::inter_network, net::sockets::socket_type::stream, net::sockets::protocol_type::tcp}, file_access::write};
    stream.socket().connect(net::ip_address::loopback, 9400);
    auto writer = stream_writer {stream};
    
    auto counter = 0;
    while (!terminate_app) {
      writer.write_line("counter={}", ++counter);
      thread::sleep(50_ms);
    }
  }};
  client.start();
  
  console::read_key();
  terminate_app = true;
  server.join();
  client.join();
}
 
// This code produces the following output :
//
// counter=1
// counter=2
// counter=3
// counter=4
// counter=5
// ...

Public Constructors
	network_stream (const xtd::net::sockets::socket &socket)
	Creates a new instance of the network_stream class for the specified xtd::net::sockets::socket.
	network_stream (const xtd::net::sockets::socket &socket, bool owns_socket)
	Initializes a new instance of the xtd::net::sockets::network_stream class for the specified xtd::net::sockets::socket with the specified xtd::net::sockets::socket ownership.
	network_stream (const xtd::net::sockets::socket &socket, xtd::io::file_access access)
	Initializes a new instance of the network_stream class for the specified xtd::net::sockets::socket with the specified access rights.
	network_stream (const xtd::net::sockets::socket &socket, xtd::io::file_access access, bool owns_socket)
	Initializes a new instance of the network_stream class for the specified xtd::net::sockets::socket with the specified access rights and the specified xtd::net::sockets::socket ownership.

Public Properties
auto	can_read () const noexcept -> bool override
	Gets a value indicating whether the current stream supports reading.
auto	can_seek () const noexcept -> bool override
	Gets a value indicating whether the current stream supports seeking.
auto	can_timeout () const noexcept -> bool override
	Indicates whether timeout properties are usable for xtd::net::sockets::network_stream.
auto	can_write () const noexcept -> bool override
	Gets a value indicating whether the current stream supports writing.
virtual auto	data_available () const -> bool
	Gets a value that indicates whether data is available on the xtd::net::sockets::network_stream to be read.
auto	length () const -> xtd::size override
	Gets the length of the stream in bytes.
auto	position () const -> xtd::size override
	Gets the current position within the stream.
auto	position (xtd::size value) -> void override
	Sets the current position within the stream.
auto	read_timeout () const -> xtd::int32 override
	Gets the amount of time that a read operation blocks waiting for data.
auto	read_timeout (xtd::int32 value) -> void override
	Sets the amount of time that a read operation blocks waiting for data.
auto	write_timeout () const -> xtd::int32 override
	Gets the amount of time that a write operation blocks waiting for data.
auto	write_timeout (xtd::int32 value) -> void override
	Sets the amount of time that a write operation blocks waiting for data.
auto	socket () const -> xtd::net::sockets::socket
	Gets the underlying xtd::net::sockets::socket.

Public Methods
auto	flush () -> void override
	Flushes data from the stream. This method is reserved for future use.
auto	read (xtd::array< xtd::byte > &buffer, size offset, size count) -> xtd::size override
	Reads a block of bytes from the current stream and writes the data to a buffer.
auto	set_length (xtd::size value) -> void override
	Sets the length of the current stream to the specified value.
auto	write (const xtd::array< xtd::byte > &buffer, size offset, size count) -> void override
	Writes a block of bytes to the current stream using data read from a buffer.
virtual auto	read (xtd::span< xtd::byte > &buffer) -> xtd::size
	When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
virtual auto	write (xtd::span< const xtd::byte > buffer) -> void

Additional Inherited Members
static xtd::io::null_stream	null_stream
	A Stream with no backing store.
static constexpr xtd::int32	eof
	Represnets an eof value.
virtual auto	is_closed () const noexcept -> bool
	Indicates if the stream is closed.
auto	copy_to (std::ostream &destination) -> void
	Reads the bytes from the current memory stream and writes them to another stream.
auto	copy_to (std::ostream &destination, xtd::size buffer_size) -> void
	Reads the bytes from the current memory stream and writes them to another stream, using a specified buffer size.
auto	read_at_least (xtd::array< xtd::byte > &buffer, xtd::size minimum_bytes, bool throw_on_end_of_stream=true) -> xtd::size
	Reads at least a minimum number of bytes from the current stream and advances the position within the stream by the number of bytes read.
virtual auto	read_byte () -> xtd::int32
auto	read_exactly (xtd::array< xtd::byte > &buffer) -> void
	Reads bytes from the current stream and advances the position within the stream until the buffer is filled.
auto	read_exactly (xtd::array< xtd::byte > &buffer, xtd::size offset, xtd::size count) -> void
	Reads count number of bytes from the current stream and advances the position within the stream.
virtual auto	write_byte (xtd::byte value) -> void
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const
	Returns a xtd::string that represents the current object.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.
	stream ()
	Initializes a new instance of the xtd::io::stream class.
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Constructor & Destructor Documentation

network_stream() [1/4]

xtd::net::sockets::network_stream::network_stream ( const xtd::net::sockets::socket & socket )

explicit

Creates a new instance of the network_stream class for the specified xtd::net::sockets::socket.

Parameters

socket

The xtd::net::sockets::socket that the xtd::net::sockets::network_stream will use to send and receive data.

Remarks

The xtd::net::sockets::network_stream is created with read/write access to the specified xtd::net::sockets::socket. The xtd::net::sockets::network_stream does not own the underlying xtd::net::sockets::socket, so calling the close method does not close the xtd::net::sockets::socket.

network_stream() [2/4]

xtd::net::sockets::network_stream::network_stream	(	const xtd::net::sockets::socket &	socket,
		bool	owns_socket )

Initializes a new instance of the xtd::net::sockets::network_stream class for the specified xtd::net::sockets::socket with the specified xtd::net::sockets::socket ownership.

Parameters

socket	The xtd::net::sockets::socket that the xtd::net::sockets::network_stream will use to send and receive data.
owns_socket	Set to true to indicate that the xtd::net::sockets::network_stream will take ownership of the xtd::net::sockets::socket; otherwise, false.

Remarks

The xtd::net::sockets::network_stream is created with read/write access to the specified xtd::net::sockets::socket. If the value of owns_socket parameter is true, the xtd::net::sockets::network_stream takes ownership of the underlying xtd::net::sockets::socket, and calling the close method also closes the underlying xtd::net::sockets::socket.

network_stream() [3/4]

xtd::net::sockets::network_stream::network_stream	(	const xtd::net::sockets::socket &	socket,
		xtd::io::file_access	access )

Initializes a new instance of the network_stream class for the specified xtd::net::sockets::socket with the specified access rights.

Parameters

socket	The xtd::net::sockets::socket that the xtd::net::sockets::network_stream will use to send and receive data.
access	A bitwise combination of the xtd::io::file_access values that specify the type of access given to the xtd::net::sockets::network_stream over the provided xtd::net::sockets::socket.

network_stream() [4/4]

xtd::net::sockets::network_stream::network_stream	(	const xtd::net::sockets::socket &	socket,
		xtd::io::file_access	access,
		bool	owns_socket )

Initializes a new instance of the network_stream class for the specified xtd::net::sockets::socket with the specified access rights and the specified xtd::net::sockets::socket ownership.

Parameters

socket	The xtd::net::sockets::socket that the xtd::net::sockets::network_stream will use to send and receive data.
access	A bitwise combination of the xtd::io::file_access values that specify the type of access given to the xtd::net::sockets::network_stream over the provided xtd::net::sockets::socket.
owns_socket	Set to true to indicate that the xtd::net::sockets::network_stream will take ownership of the xtd::net::sockets::socket; otherwise, false.

Member Function Documentation

can_read()

auto xtd::net::sockets::network_stream::can_read ( ) const -> bool

nodiscardoverridevirtualnoexcept

Gets a value indicating whether the current stream supports reading.

Returns

true if the stream supports reading; otherwise, false.

Implements xtd::io::stream.

can_seek()

auto xtd::net::sockets::network_stream::can_seek ( ) const -> bool

nodiscardoverridevirtualnoexcept

Gets a value indicating whether the current stream supports seeking.

Returns

true if the stream supports seeking; otherwise, false.

Implements xtd::io::stream.

can_timeout()

auto xtd::net::sockets::network_stream::can_timeout ( ) const -> bool

nodiscardoverridevirtualnoexcept

Indicates whether timeout properties are usable for xtd::net::sockets::network_stream.

Returns

true in all cases.

Reimplemented from xtd::io::stream.

can_write()

auto xtd::net::sockets::network_stream::can_write ( ) const -> bool

nodiscardoverridevirtualnoexcept

Gets a value indicating whether the current stream supports writing.

Returns

true if the stream supports writing; otherwise, false.

Implements xtd::io::stream.

data_available()

virtual auto xtd::net::sockets::network_stream::data_available ( ) const -> bool

nodiscardvirtual

Gets a value that indicates whether data is available on the xtd::net::sockets::network_stream to be read.

Returns

true if data is available on the stream to be read; otherwise, false.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

Use the xtd::net::sockets::network_stream::data_available property to determine if data is ready to be read. If xtd::net::sockets::network_stream::data_available is true, a call to std::iostream::read returns immediately. If the remote host shuts down or closes the connection, xtd::net::sockets::network_stream::data_available may throw a xtd::net::sockets::socket_exception.

length()

auto xtd::net::sockets::network_stream::length ( ) const -> xtd::size

nodiscardoverridevirtual

Gets the length of the stream in bytes.

Returns

The length of the stream in bytes.

Implements xtd::io::stream.

position() [1/2]

auto xtd::net::sockets::network_stream::position ( ) const -> xtd::size

nodiscardoverridevirtual

Gets the current position within the stream.

Returns

The current position within the stream.

Implements xtd::io::stream.

position() [2/2]

auto xtd::net::sockets::network_stream::position ( xtd::size value ) -> void

overridevirtual

Sets the current position within the stream.

Parameters

value

The current position within the stream.

Implements xtd::io::stream.

read_timeout() [1/2]

auto xtd::net::sockets::network_stream::read_timeout ( ) const -> xtd::int32

nodiscardoverridevirtual

Gets the amount of time that a read operation blocks waiting for data.

Returns

A xtd::int32 that specifies the amount of time, in milliseconds, that will elapse before a read operation fails. The default value, xtd::threading::timeout::infinite, specifies that the read operation does not time out.

Reimplemented from xtd::io::stream.

read_timeout() [2/2]

auto xtd::net::sockets::network_stream::read_timeout ( xtd::int32 value ) -> void

overridevirtual

Sets the amount of time that a read operation blocks waiting for data.

Parameters

value

A xtd::int32 that specifies the amount of time, in milliseconds, that will elapse before a read operation fails. The default value, xtd::threading::timeout::infinite, specifies that the read operation does not time out.

Reimplemented from xtd::io::stream.

write_timeout() [1/2]

auto xtd::net::sockets::network_stream::write_timeout ( ) const -> xtd::int32

nodiscardoverridevirtual

Gets the amount of time that a write operation blocks waiting for data.

Returns

A xtd::int32 that specifies the amount of time, in milliseconds, that will elapse before a read operation fails. The default value, xtd::threading::timeout::infinite, specifies that the read operation does not time out.

Reimplemented from xtd::io::stream.

write_timeout() [2/2]

auto xtd::net::sockets::network_stream::write_timeout ( xtd::int32 value ) -> void

overridevirtual

Sets the amount of time that a write operation blocks waiting for data.

Parameters

value

A xtd::int32 that specifies the amount of time, in milliseconds, that will elapse before a read operation fails. The default value, xtd::threading::timeout::infinite, specifies that the read operation does not time out.

Reimplemented from xtd::io::stream.

socket()

auto xtd::net::sockets::network_stream::socket ( ) const -> xtd::net::sockets::socket

nodiscard

Gets the underlying xtd::net::sockets::socket.

Returns

A xtd::net::sockets::socket that represents the underlying network connection.

Remarks

Classes deriving from xtd::net::sockets::network_stream can use this property to get the underlying xtd::net::sockets::socket. Use the underlying xtd::net::sockets::socket returned from the xtd::net::sockets::socket property if you require access beyond that which xtd::net::sockets::network_stream provides.

flush()

auto xtd::net::sockets::network_stream::flush ( ) -> void

overridevirtual

Flushes data from the stream. This method is reserved for future use.

Remarks

The Flush method implements the xtd::io::stream::flush method; however, because xtd::net::sockets::network_stream is not buffered, it has no effect on network streams. Calling the xtd::net::sockets::network_stream::flush method does not throw an exception.

Implements xtd::io::stream.

read() [1/2]

auto xtd::net::sockets::network_stream::read ( xtd::array< xtd::byte > & buffer, size offset, size count ) -> xtd::size

overridevirtual

Reads a block of bytes from the current stream and writes the data to a buffer.

Parameters

buffer	When this method returns, contains the specified byte array with the values between offset and (offset + count - 1) replaced by the characters read from the current stream.
offset	The zero-based byte offset in buffer at which to begin storing data from the current stream.
count	The maximum number of bytes to read.

Returns

The total number of bytes written into the buffer. This can be less than the number of bytes requested if that number of bytes are not currently available, or zero if the end of the stream is reached before any bytes are read.

Remarks

The offset parameter gives the offset of the first byte in buffer to which data from the current stream is written. The count parameter gives the maximum number of bytes to read from the current stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached.

If the read operation is successful, the current position within the stream advances by the number of bytes read. If an exception occurs, the current position within the stream remains unchanged.

The read method will return zero only if the end of the stream is reached. In all other cases, read always reads at least one byte from the stream before returning. By definition, if no data is available from the stream upon a call to read, the read method returns zero (the end of the stream is reached automatically). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached.

Use xtd::io::binary_reader for reading primitive data types.

Implements xtd::io::stream.

set_length()

auto xtd::net::sockets::network_stream::set_length ( xtd::size value ) -> void

overridevirtual

Sets the length of the current stream to the specified value.

Parameters

value

The value at which to set the length.

Remarks

If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the xtd::io::memery_stream::read_byte method returns -1, the xtd::io::memery_stream::read method reads zero bytes into the provided byte array, and xtd::io::memery_stream::write and xtd::io::memery_stream::write_byte methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros.

Implements xtd::io::stream.

write() [1/2]

auto xtd::net::sockets::network_stream::write ( const xtd::array< xtd::byte > & buffer, size offset, size count ) -> void

overridevirtual

Writes a block of bytes to the current stream using data read from a buffer.

Parameters

buffer	The buffer to write data from.
offset	The zero-based byte offset in buffer at which to begin copying bytes to the current stream.
count	The maximum number of bytes to write.

Examples

This code example is part of a larger example provided for the xtd::io::memory_stream class.

// Write the first string to the stream.
mem_stream.write(first_string, 0 , first_string.length());

Remarks

The offset parameter gives the offset of the first byte in buffer to write from, and the count parameter gives the number of bytes to write. If the write operation is successful, the current position within the stream is advanced by the number of bytes written. If an exception occurs, the current position within the stream is unchanged.

Except for a memory_stream constructed with a byte[] parameter, write operations at the end of a memory_stream expand the memory_stream.

Implements xtd::io::stream.

read() [2/2]

virtual auto xtd::io::stream::read ( xtd::span< xtd::byte > & buffer ) -> xtd::size

virtual

When overridden in a derived class, 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 region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source.

Reimplemented from xtd::io::stream.

write() [2/2]

virtual auto xtd::io::stream::write ( xtd::span< const xtd::byte > buffer ) -> void

virtual

Reimplemented from xtd::io::stream.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/net/sockets/network_stream.hpp