TCPClient class used to access the isolated Ethernet. More...
#include <IsolatedEthernet.h>
Public Member Functions | |
| TCPClient () | |
| Construct a new TCPClient object. You will do this for each TCP client connection. More... | |
| TCPClient (sock_handle_t sock) | |
| Construct a new TCPClient object. You will not generally use this overload, it's used internally. | |
| virtual | ~TCPClient () |
| Destroy the TCPClient object. This will close the connection if necessary and release its resources. | |
| uint8_t | status () |
| Returns true if the network socket is open and the underlying network is ready. More... | |
| virtual int | connect (IPAddress ip, uint16_t port, network_interface_t=0) |
| Connect to a host by IP address. More... | |
| virtual int | connect (const char *host, uint16_t port, network_interface_t=0) |
| Connect to a host by its DNS hostname. More... | |
| virtual size_t | write (uint8_t b) |
| Writes a single byte to the remote host. More... | |
| virtual size_t | write (const uint8_t *buffer, size_t size) |
| Writes a buffer of data to the remote host. More... | |
| virtual size_t | write (uint8_t b, system_tick_t timeout) |
| Writes a single byte to the remote host. More... | |
| virtual size_t | write (const uint8_t *buffer, size_t size, system_tick_t timeout) |
| Writes a buffer of data to the remote host. More... | |
| virtual int | available () |
| Returns the number of bytes available to read. More... | |
| virtual int | read () |
| Read a single byte from the receive buffer. More... | |
| virtual int | read (uint8_t *buffer, size_t size) |
| Read a buffer of data from the receive buffer. More... | |
| virtual int | peek () |
| Look at the next byte will be read, without removing it from the input buffer. More... | |
| virtual void | flush () |
| Blocks until all data waiting to be sent in the W5500 send buffer has been sent. | |
| void | flush_buffer () |
| Discards data waiting to be read from the internal buffer. More... | |
| virtual void | stop () |
| End this connection, release its resources. More... | |
| virtual uint8_t | connected () |
| Returns true if there is data waiting to be read or if currently connected to the remote host. More... | |
| virtual | operator bool () |
| Equivalent to status() != 0, but as the bool() operator, making it easy to test if there is a connection. More... | |
| virtual IPAddress | remoteIP () |
| Return the IP address of the other side of the connection. More... | |
| virtual size_t | write (uint8_t c)=0 |
| Write a single byte to the stream or file. More... | |
| size_t | write (const char *str) |
| Write a null-terminated c-string the stream or file. More... | |
| virtual size_t | write (const uint8_t *buffer, size_t size) |
| Write a bytes specified by a buffer and length to the stream or file. More... | |
Protected Member Functions | |
| bool | isOpen () |
| Return true of the socket is currently open. Used internally. More... | |
| sock_handle_t | sock_handle () |
| Used internally to access the socket handle for this connection. More... | |
Friends | |
| class | IsolatedEthernet::TCPServer |
Detailed Description
TCPClient class used to access the isolated Ethernet.
Replace TCPClient with IsolatedEthernet::TCPClient to use Ethernet instead of the Particle device's native networking (cellular or Wi-Fi).
Constructor & Destructor Documentation
◆ TCPClient()
| IsolatedEthernet::TCPClient::TCPClient | ( | ) |
Member Function Documentation
◆ available()
|
virtual |
Returns the number of bytes available to read.
- Returns
- int number of bytes
Note that the receive buffer is only 2048 bytes on the W5500. Thus the other side of the connection may be holding more data that has not been received by the W5500 yet.
If you are expecting a fixed-size structure, you should always read out all available bytes on each loop into a separate buffer and process when it has been read completely. Do not wait for available() to be the size of the structure then read.
◆ connect() [1/2]
|
virtual |
Connect to a host by its DNS hostname.
- Parameters
-
host the hostname to connect to port The IP port number to connect to
- Returns
- int true (1) if the connection was made or false (0) if not.
This call will block until the connection is made or times out.
Note that every connection will cause a DNS lookup when connecting by hostname; there is no DNS cache.
◆ connect() [2/2]
|
virtual |
Connect to a host by IP address.
- Parameters
-
ip The IP address to connect to port The IP port number to connect to
- Returns
- int true (1) if the connection was made or false (0) if not.
This call will block until the connection is made or times out.
◆ connected()
|
virtual |
Returns true if there is data waiting to be read or if currently connected to the remote host.
- Returns
- uint8_t If data available or connected
This is different than status() which only checks whether the connection is open, which seems kind of backwards, but that's how the Wiring API works.
◆ flush_buffer()
| void IsolatedEthernet::TCPClient::flush_buffer | ( | ) |
Discards data waiting to be read from the internal buffer.
There may still be data in the W5500 buffers.
◆ isOpen()
|
protected |
Return true of the socket is currently open. Used internally.
- Returns
- true
- false
◆ operator bool()
|
virtual |
Equivalent to status() != 0, but as the bool() operator, making it easy to test if there is a connection.
- Returns
- true
- false
This is particularly useful with TCPServer available().
◆ peek()
|
virtual |
Look at the next byte will be read, without removing it from the input buffer.
- Returns
- int The returned byte (0-255), or -1 if there is no data to be read
◆ read() [1/2]
|
virtual |
Read a single byte from the receive buffer.
- Returns
- int The returned byte (0-255), or -1 if there is no data to be read
It's much more efficient to use the overload that takes a buffer and size than reading bytes one at a time.
◆ read() [2/2]
|
virtual |
Read a buffer of data from the receive buffer.
- Parameters
-
buffer A pointer to a buffer to read data into size Number of bytes to read, must be > 0.
- Returns
- int the number of bytes read, or a negative value on error
This is much more efficient to read data into a buffer using this call instead of reading one byte at a time. The number of bytes read is not guaranteed to be size requested; if any bytes are available they will be copied to buffer and the result will be the number of bytes actually read.
The optimize request size is 2048 bytes, which is the size of the incoming data buffer. Making it larger will have no effect since there will never be more bytes in the buffer.
◆ remoteIP()
|
virtual |
Return the IP address of the other side of the connection.
- Returns
- IPAddress
◆ sock_handle()
|
inlineprotected |
Used internally to access the socket handle for this connection.
- Returns
- sock_handle_t A W5500 socket handle (0 - 7) or -1 if there isn't an open socket.
◆ status()
| uint8_t IsolatedEthernet::TCPClient::status | ( | ) |
Returns true if the network socket is open and the underlying network is ready.
- Returns
- uint8_t 1 if the network socket is open or 0 if not, essentially a boolean.
This is different than connected() which returns true if the socket is closed but there is still unread buffered data, available() is non-zero.
◆ stop()
|
virtual |
End this connection, release its resources.
The Wiring API for streams is not particularly well-suited for TCP as it doesn't have a clear concept of half-closed connections.
◆ write() [1/7]
|
inline |
Write a null-terminated c-string the stream or file.
- Parameters
-
str point to a null-terminated c-string.
◆ write() [2/7]
|
virtual |
Writes a buffer of data to the remote host.
- Parameters
-
buffer Pointer to a buffer of bytes to send (can be binary or ASCII) size Number of bytes to send.
- Returns
- size_t The number of bytes written, typically 1.
Internally, the W5500 can't buffer more than 2048 bytes of data, however this library will break up your send into chunks to fit in the available buffer space.
This overload does not take a timeout and uses the default timeout of 30 seconds. The timeout is for the whole send, not individual chunks. If the timeout is exceeded there is no guarantee of how many bytes were actually sent.
There's a bug in Device OS where the write function can also return a negative error code from write(), however size_t is unsigned, so it tends to return as a very large positive integer instead. Because of this, it's best to ignore the result or test for != 1.
◆ write() [3/7]
| virtual size_t Print::write | ( | const uint8_t * | buffer, |
| size_t | size | ||
| ) |
Write a bytes specified by a buffer and length to the stream or file.
- Parameters
-
buffer pointer to the buffer. The data does not need to be null-terminated. size size in bytes
◆ write() [4/7]
|
virtual |
Writes a buffer of data to the remote host.
- Parameters
-
buffer Pointer to a buffer of bytes to send (can be binary or ASCII) size Number of bytes to send. timeout Timeout in milliseconds, or 0 to wait forever
- Returns
- size_t The number of bytes written, typically 1.
Internally, the W5500 can't buffer more than 2048 bytes of data, however this library will break up your send into chunks to fit in the available buffer space.
The timeout is for the whole send, not individual chunks. If the timeout is exceeded there is no guarantee of how many bytes were actually sent.
There's a bug in Device OS where the write function can also return a negative error code from write(), however size_t is unsigned, so it tends to return as a very large positive integer instead. Because of this, it's best to ignore the result or test for != 1.
◆ write() [5/7]
|
virtual |
Writes a single byte to the remote host.
- Parameters
-
b The byte to write (can be ASCII or binary).
- Returns
- size_t The number of bytes written, typically 1.
This overload does not take a timeout and uses the default timeout of 30 seconds.
It's best to use the overload that takes a buffer and a size. Each byte write is communicated to the W5500 using SPI calls. The W5500 may further buffer the data before assembling it in packets, but using the buffer-based approach is still much faster.
There's a bug in Device OS where the write function can also return a negative error code from write(), however size_t is unsigned, so it tends to return as a very large positive integer instead. Because of this, it's best to ignore the result or test for != 1.
◆ write() [6/7]
|
virtual |
Writes a single byte to the remote host.
- Parameters
-
b The byte to write (can be ASCII or binary). timeout Timeout in milliseconds, or 0 to wait forever
- Returns
- size_t The number of bytes written, typically 1.
It's best to use the overload that takes a buffer and a size. Each byte write is communicated to the W5500 using SPI calls. The W5500 may further buffer the data before assembling it in packets, but using the buffer-based approach is still much faster.
There's a bug in Device OS where the write function can also return a negative error code from write(), however size_t is unsigned, so it tends to return as a very large positive integer instead. Because of this, it's best to ignore the result or test for != 1.
◆ write() [7/7]
| virtual size_t Print::write | ( | uint8_t | c | ) |
Write a single byte to the stream or file.
- Parameters
-
c The byte to write. All values 0 - 255 are allowed.
The documentation for this class was generated from the following file:
