Socket

class WiFiSocket

A plain socket

This class owns the underlying socket lifetime. It is movable and move assignable but not copyable or copy assignable.

Public Types

enum class Type : uint8_t

Socket type

Semantics equivalent to Unix sockets SOCK_STREAM, SOCK_DGRAM etc.

Values:

enumerator Stream

enumerator DGram

enumerator Raw

enum Protocol

Socket protocol

Semantics equivalent to Unix sockets IPPROTO_TCP etc. Not all values are implemented/supported in firmware

Values:

enumerator IP

enumerator ICMP

enumerator TCP

enumerator UDP

enumerator IPv6

enumerator ICMPv6

enumerator UDPLite

enumerator Raw

enum State

Socket state bitmask

These values can be obtained via poll()

Values:

enumerator Readable

enumerator Writable

enumerator ErroredOut

enum class Error : uint8_t

Custom error codes for lastError()

These represent issues communicating with NINA chip and won’t clash with errno codes returned from socket calls.

Values:

enumerator SpiFailure

Public Functions

WiFiSocket() = default

Creates an invalid socket.

inline WiFiSocket(Type type, Protocol proto)

Creates a socket

This is equivalent to socket() API call. In case of failure the socket is created as invalid which can be tested via operator bool.

inline ~WiFiSocket()

Closes the socket.

void close()

Manually close the socket

This makes this object an invalid socket

inline WiFiSocket(WiFiSocket &&src)

Moving a socket

The source socket is left in an invalid state

inline WiFiSocket &operator=(WiFiSocket &&src)

Move-assigning a socket

The source socket is left in an invalid state

inline explicit operator bool() const

Tests whether the socket is invalid.

A socket is in an invalid state when it represents “no socket”. A valid socket never becomes invalid unless it is moved out or closed. Similarly an invalid socket never becomes valid unless moved-in from a valid socket.

inline bool bind(uint16_t port)

Binds a socket to given port

Returns:

success flag. Check lastError() for more information about failure

inline bool listen(uint8_t backlog)

Starts listening for incoming connections

Returns:

success flag. Check lastError() for more information about failure

inline WiFiSocket accept(arduino::IPAddress &remoteIpAddress, uint16_t &remotePort)

Accepts an incoming connection

Parameters:

• remoteIpAddress – if successful populated by the address of the remote client

• remotePort – if successful populated by the port of the remote client

Returns:

a valid socket, if successful or invalid otherwise. Check lastError() for more information about the failure.

inline bool connect(const arduino::IPAddress &ipAddress, uint16_t port)

Connects a socket to remote endpoint

Parameters:

• ipAddress – host to connect to

• port – port to connect to

Returns:

success flag. Check lastError() for more information about failure

int32_t send(const void *buf, uint16_t size)

Sends data to remote endpoint

Returns:

the amount of data actually sent or -1 on failure. Check lastError() for more information about failure. The type of the return value is int32_t to accommodate -1. When non-negative it will never be bigger than the size parameter.

int32_t recv(void *buf, uint16_t size)

Receives data from remote endpoint

Returns:

the amount of data actually read or -1 on failure. Check lastError() for more information about failure. The type of the return value is int32_t to accommodate -1. When non-negative it will never be bigger than the size parameter.

int32_t sendTo(const void *buf, uint16_t size, const arduino::IPAddress &ipAddress, uint16_t port)

Sends data to remote endpoint

Returns:

the amount of data actually sent or -1 on failure. Check lastError() for more information about failure. The type of the return value is int32_t to accommodate -1. When non-negative it will never be bigger than the size parameter.

int32_t recvFrom(void *buf, uint16_t size, arduino::IPAddress &remoteIpAddress, uint16_t &remotePort)

Receives data from remote endpoint

Returns:

the amount of data actually read or -1 on failure. Check lastError() for more information about failure. The type of the return value is int32_t to accommodate -1. When non-negative it will never be bigger than the size parameter.

bool setNonBlocking(bool val)

Sets the socket into non-blocking or blocking mode

This is equivalent to ioctl(…FIONBIO…)

Returns:

success flag. Check lastError() for more information about failure

int32_t availableToRead() const

Retrieves the number of bytes available for reading.

This is equivalent to ioctl(…FIONREAD…)

Returns:

success flag. Check lastError() for more information about failure

bool poll(State &state) const

Retrieves current socket state bitmask

See State enum for possible flags. This call is similar in semantics to calling select() on the socket.

Returns:

success flag. Check lastError() for more information about failure

template<class Option>
inline bool setOption(const Option &opt)

Sets a socket option

Only a small subset of SO_SOCKET options are supported. These are represented by strongly typed values of types declared in Option struct.

For example here is how to set ReuseAddress option:

if (socket.setOption(WiFiSocket::Option::ReuseAddress(true))) {
    ...
}

Template Parameters:

Option – one of types declared in WiFiSocket::Option

Parameters:

opt – value to set

Returns:

success flag. Check lastError() for more information about failure

template<class Option>
inline bool getOption(Option &opt)

Reads a socket option

Only a small subset of SO_SOCKET options are supported. These are represented by strongly typed values of types declared in Option struct.

For example here is how to read ReuseAddress option:

WiFiSocket::Option::ReuseAddress reuseAddress;
if (socket.getOption(reuseAddress)) {
    ...
}

Template Parameters:

Option – one of types declared in WiFiSocket::Option

Parameters:

opt – value to fill in

Returns:

success flag. Check lastError() for more information about failure

inline uint8_t handle() const

Retrieves underlying socket handle

This is for debugging purposes only.

Public Static Functions

static inline uint8_t lastError()

Retrieves error (if any) of the last method call

Last error is always set, whether the call failed or succeeded.

The returned value is either a standard errno value from the underlying socket call or one of the Error enumeration values Their ranges are guaranteed to be distinct. In case of success the value is 0.

struct Option

Available socket options types.

Public Types

using ReuseAddress = ValueOption<0x0004, bool, uint32_t>

SO_REUSEADDR option.

using KeepAlive = ValueOption<0x0008, bool, uint32_t>

SO_KEEPALIVE option.

using Broadcast = ValueOption<0x0020, bool, uint32_t>

SO_BROADCAST option.

using AcceptsConnections = ValueOption<0x0002, bool, uint32_t>

SO_ACCEPTCONN option.

using RecvBufferSize = ValueOption<0x1002, uint32_t>

SO_RCVBUF option.

using SendTimeout = StructOption<0x1005, TimeVal>

SO_SNDTIMEO option.

using RecvTimeout = StructOption<0x1006, TimeVal>

SO_RCVTIMEO option.

using GetAndClearError = ValueOption<0x1007, uint8_t, uint32_t>

SO_ERROR option.

using SocketType = ValueOption<0x1008, WiFiSocket::Type, uint32_t>

SO_TYPE option.

using NoUdpChecksum = ValueOption<0x100a, bool, uint32_t>

SO_NO_CHECK option.

struct TimeVal

A representation of struct timeval used by NINA.

Public Members

long long tv_sec

seconds

long tv_usec

microseconds