EthernetClient Class Reference

#include <EthernetClient.h>

Inheritance diagram for EthernetClient:

Collaboration diagram for EthernetClient:

Public Member Functions
	EthernetClient ()
	Default constructor. Creates a client with no connection.
	EthernetClient (uint8_t sock)
	Deprecated constructor kept for W5100 sketch compatibility.
	EthernetClient (struct tcp_struct *tcpClient)
	Wraps an existing TCP connection.
uint8_t	status ()
	Returns the state of the TCP connection.
virtual int	connect (IPAddress ip, uint16_t port)
	Connects to a remote host by IP address.
virtual int	connect (const char *host, uint16_t port)
	Connects to a remote host by host name.
virtual size_t	write (uint8_t b)
	Writes one byte to the connection.
virtual size_t	write (const uint8_t *buf, size_t size)
	Writes a buffer to the connection.
virtual int	available ()
	Returns the number of bytes ready to be read.
virtual int	read ()
	Reads one byte from the receive buffer.
virtual int	read (uint8_t *buf, size_t size)
	Reads up to size bytes from the receive buffer.
virtual int	peek ()
	Returns the next byte without removing it from the buffer.
virtual void	flush ()
	Sends any data still queued for transmission.
virtual void	stop ()
	Closes the connection and releases the client structure.
virtual uint8_t	connected ()
	Checks whether the client is connected.
virtual	operator bool ()
	Tests whether the client holds a usable connection.
virtual bool	operator== (const bool value)
	Compares the client's boolean value with a value.
virtual bool	operator!= (const bool value)
	Compares the client's boolean value with a value.
virtual bool	operator== (const EthernetClient &)
	Tests whether two clients refer to the same connection.
virtual bool	operator!= (const EthernetClient &rhs)
	Tests whether two clients refer to different connections.
uint8_t	getSocketNumber ()
	Returns the socket number, for W5100 compatibility.
virtual uint16_t	localPort ()
	Returns the local TCP port of the connection.
virtual IPAddress	remoteIP ()
	Returns the remote IP address of the connection.
virtual uint16_t	remotePort ()
	Returns the remote TCP port of the connection.
void	setConnectionTimeout (uint16_t timeout)
	Sets how long connect() waits for the connection (ms).

Friends
class	EthernetServer

Constructor & Destructor Documentation

EthernetClient() [1/3]

EthernetClient::EthernetClient

(

)

Default constructor. Creates a client with no connection.

EthernetClient() [2/3]

EthernetClient::EthernetClient

(

uint8_t

sock

)

Deprecated constructor kept for W5100 sketch compatibility.

The socket argument is ignored and the client starts with no connection.

Parameters

sock	Socket number, ignored.

EthernetClient() [3/3]

EthernetClient::EthernetClient

(

struct tcp_struct *

tcpClient

)

Wraps an existing TCP connection.

The structure is used directly and is not copied. EthernetServer uses this constructor to return accepted clients.

Parameters

tcpClient

Pointer to the TCP connection structure to wrap.

Member Function Documentation

available()

int EthernetClient::available ( )

virtual

Returns the number of bytes ready to be read.

Runs the network scheduler before checking the receive buffer.

Returns

Number of bytes available, or 0 if there is no connection.

connect() [1/2]

int EthernetClient::connect ( const char *  host, uint16_t  port  )

virtual

Connects to a remote host by host name.

Resolves the name with the DNS server configured in Ethernet, then connects to the resulting address.

Parameters

host	Host name to resolve.
port	Remote TCP port.

Returns

1 if the connection was established, 0 otherwise, including when the name cannot be resolved.

connect() [2/2]

int EthernetClient::connect ( IPAddress  ip, uint16_t  port  )

virtual

Connects to a remote host by IP address.

Blocks until the connection is established, fails, or the timeout set with setConnectionTimeout() expires.

Parameters

ip	Remote IP address.
port	Remote TCP port.

Returns

1 if the connection was established, 0 otherwise.

connected()

uint8_t EthernetClient::connected ( )

virtual

Checks whether the client is connected.

A client whose connection is closing still counts as connected while data remains to be read.

Returns

1 if connected, 0 otherwise.

flush()

void EthernetClient::flush ( )

virtual

Sends any data still queued for transmission.

Does not wait for the remote host to acknowledge the data.

getSocketNumber()

uint8_t EthernetClient::getSocketNumber

(

)

Returns the socket number, for W5100 compatibility.

This function is specific to the W5100 architecture and is not defined by Arduino. It is kept for compatibility and always returns 0 because this implementation has no socket numbers.

Returns

Always 0.

localPort()

virtual uint16_t EthernetClient::localPort ( )

inlinevirtual

Returns the local TCP port of the connection.

Requires an active connection. No NULL check is performed.

Returns

Local port number.

operator bool()

EthernetClient::operator bool ( )

virtual

Tests whether the client holds a usable connection.

Lets the client returned by EthernetServer::available() be used as the condition of an if-statement.

Returns

true if a connection structure exists and is not in TCP_CLOSING state, false otherwise.

operator!=() [1/2]

virtual bool EthernetClient::operator!= ( const bool  value )

inlinevirtual

Compares the client's boolean value with a value.

Parameters

value

Value to compare with operator bool().

Returns

true if the client's boolean value differs from value.

operator!=() [2/2]

virtual bool EthernetClient::operator!= ( const EthernetClient &  rhs )

inlinevirtual

Tests whether two clients refer to different connections.

Parameters

rhs	Client to compare with.

Returns

The negation of operator==(rhs).

operator==() [1/2]

virtual bool EthernetClient::operator== ( const bool  value )

inlinevirtual

Compares the client's boolean value with a value.

Parameters

value

Value to compare with operator bool().

Returns

true if the client's boolean value equals value.

operator==() [2/2]

bool EthernetClient::operator== ( const EthernetClient &  rhs )

virtual

Tests whether two clients refer to the same connection.

Two clients with no connection structure compare equal. A client with no connection never equals a client that has one.

Parameters

rhs	Client to compare with.

Returns

true if both clients use the same connection structure and the same TCP control block, false otherwise.

peek()

int EthernetClient::peek ( )

virtual

Returns the next byte without removing it from the buffer.

Runs the network scheduler through available().

Returns

The next byte (0 to 255), or -1 if no data is available.

read() [1/2]

int EthernetClient::read ( )

virtual

Reads one byte from the receive buffer.

Returns

The byte read (0 to 255), or -1 if no data is buffered.

read() [2/2]

int EthernetClient::read ( uint8_t *  buf, size_t  size  )

virtual

Reads up to size bytes from the receive buffer.

Parameters

buf	Destination buffer.
size	Maximum number of bytes to read.

Returns

Number of bytes copied into buf, or -1 if no data is buffered.

remoteIP()

virtual IPAddress EthernetClient::remoteIP ( )

inlinevirtual

Returns the remote IP address of the connection.

Requires an active connection. No NULL check is performed.

Returns

Remote IP address.

remotePort()

virtual uint16_t EthernetClient::remotePort ( )

inlinevirtual

Returns the remote TCP port of the connection.

Requires an active connection. No NULL check is performed.

Returns

Remote port number.

setConnectionTimeout()

void EthernetClient::setConnectionTimeout ( uint16_t  timeout )

inline

Sets how long connect() waits for the connection (ms).

Parameters

timeout

Timeout in milliseconds.

status()

uint8_t EthernetClient::status

(

)

Returns the state of the TCP connection.

Returns

A tcp_client_states value, or TCP_NONE if there is no connection structure.

stop()

void EthernetClient::stop ( )

virtual

Closes the connection and releases the client structure.

The connection is closed unless it is already in TCP_CLOSING state. The structure is freed only if this client allocated it in connect(). A structure shared with EthernetServer is left for the server to free, and the client is left with no connection.

write() [1/2]

size_t EthernetClient::write ( const uint8_t *  buf, size_t  size  )

virtual

Writes a buffer to the connection.

Sends the data in chunks limited by the free space in the TCP send buffer, and forces each chunk out. Bytes queued before a TCP error are not reported.

Parameters

buf	Data to send.
size	Number of bytes in buf.

Returns

size if all bytes were queued, 0 on failure. Failure includes a client that is not connected or accepted, a NULL buf, size 0, and a TCP error.

write() [2/2]

size_t EthernetClient::write ( uint8_t  b )

virtual

Writes one byte to the connection.

Parameters

b	Byte to send.

Returns

1 if the byte was written, 0 on failure.

Friends And Related Symbol Documentation

EthernetServer

friend class EthernetServer

friend

---

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

• src/EthernetClient.h
• src/EthernetClient.cpp