EthernetUDP Class Reference

#include <EthernetUdp.h>

Inheritance diagram for EthernetUDP:

Collaboration diagram for EthernetUDP:

Public Member Functions
	EthernetUDP ()
	Constructs an EthernetUDP object without opening a socket.
virtual uint8_t	begin (uint16_t)
	Opens a unicast UDP socket on a local port.
virtual uint8_t	begin (IPAddress, uint16_t, bool multicast=false)
	Opens a UDP socket bound to a local address and port.
virtual uint8_t	beginMulticast (IPAddress, uint16_t)
	Opens a UDP socket that joins a multicast group.
virtual void	stop ()
	Closes the UDP socket.
virtual int	beginPacket (IPAddress ip, uint16_t port)
	Sets the destination for the next outgoing packet.
virtual int	beginPacket (const char *host, uint16_t port)
	Sets the destination for the next outgoing packet by host name.
virtual int	endPacket ()
	Sends the data written since beginPacket() as one datagram.
virtual size_t	write (uint8_t)
	Appends one byte to the outgoing packet.
virtual size_t	write (const uint8_t *buffer, size_t size)
	Appends a block of bytes to the outgoing packet.
virtual int	parsePacket ()
	Advances to the next received packet.
virtual int	available ()
	Returns the number of unread bytes in the current packet.
virtual int	read ()
	Reads one byte from the current packet.
virtual int	read (unsigned char *buffer, size_t len)
	Reads up to len bytes from the current packet into buffer.
virtual int	read (char *buffer, size_t len)
	Reads up to len characters from the current packet into buffer.
virtual int	peek ()
	Returns the next byte of the current packet without consuming it.
virtual void	flush ()
	Intended to wait for the transmit buffer to empty.
virtual IPAddress	remoteIP ()
	Returns the IP address of the sender of the current packet.
virtual uint16_t	remotePort ()
	Returns the port of the sender of the current packet.
virtual void	onDataArrival (std::function< void()> onDataArrival_fn)
	Registers a callback invoked when a UDP datagram arrives.

Protected Attributes
uint16_t	_remaining

Constructor & Destructor Documentation

EthernetUDP()

EthernetUDP::EthernetUDP

(

)

Constructs an EthernetUDP object without opening a socket.

Call begin() or beginMulticast() to open a socket.

Member Function Documentation

available()

int EthernetUDP::available ( )

virtual

Returns the number of unread bytes in the current packet.

Returns 0 until parsePacket() has been called.

Returns

Number of bytes remaining in the current packet.

begin() [1/2]

uint8_t EthernetUDP::begin ( IPAddress  ip, uint16_t  port, bool  multicast = false  )

virtual

Opens a UDP socket bound to a local address and port.

Fails if this object already has an open socket. When multicast is true, the socket binds to any address and joins the multicast group ip through IGMP (when LWIP_IGMP is enabled). Otherwise it binds to ip. If the bind fails, the socket is closed. If the IGMP join fails, the socket stays open; call stop() to close it.

Parameters

ip	Local address to bind to, or the multicast group to join.
port	Local port to listen on.
multicast	true to join the multicast group ip, false for a unicast socket bound to ip.

Returns

1 on success. 0 if a socket is already open, if the UDP PCB cannot be created or bound, or if the IGMP join fails.

begin() [2/2]

uint8_t EthernetUDP::begin ( uint16_t  port )

virtual

Opens a unicast UDP socket on a local port.

The socket is bound to the address returned by Ethernet.localIP().

Parameters

port	Local port to listen on.

Returns

1 on success, 0 on failure; see the IPAddress overload.

beginMulticast()

uint8_t EthernetUDP::beginMulticast ( IPAddress  ip, uint16_t  port  )

virtual

Opens a UDP socket that joins a multicast group.

Equivalent to begin(ip, port, true).

Parameters

ip	Multicast group address to join.
port	Local port to listen on.

Returns

1 on success, 0 on failure (same as begin()).

beginPacket() [1/2]

int EthernetUDP::beginPacket ( const char *  host, uint16_t  port  )

virtual

Sets the destination for the next outgoing packet by host name.

Resolves host with a DNS query to the server returned by Ethernet.dnsServerIP(), then calls beginPacket(IPAddress, uint16_t).

Parameters

host	Host name, or a numeric address string.
port	Destination port.

Returns

1 on success. If the lookup does not succeed, the negative DNS error code from DNSClient::getHostByName(). Otherwise the result of beginPacket(IPAddress, uint16_t).

beginPacket() [2/2]

int EthernetUDP::beginPacket ( IPAddress  ip, uint16_t  port  )

virtual

Sets the destination for the next outgoing packet.

The address and port are stored as given and not validated. Call write() and endPacket() afterwards.

Parameters

ip	Destination IP address.
port	Destination port.

Returns

1 on success, 0 if no socket is open.

endPacket()

int EthernetUDP::endPacket ( )

virtual

Sends the data written since beginPacket() as one datagram.

The buffered data is released whether or not the send succeeds.

Returns

1 if the packet was sent, 0 if no socket is open, no data was written, or the send failed.

flush()

void EthernetUDP::flush ( )

virtual

Intended to wait for the transmit buffer to empty.

Currently a no-op. Waiting for the transmit buffer is a TODO.

onDataArrival()

virtual void EthernetUDP::onDataArrival ( std::function< void()>  onDataArrival_fn )

virtual

Registers a callback invoked when a UDP datagram arrives.

Replaces any previously registered callback.

Parameters

onDataArrival_fn

Function to call when a datagram arrives.

parsePacket()

int EthernetUDP::parsePacket ( )

virtual

Advances to the next received packet.

Runs the Ethernet scheduler. If a datagram is queued, records its sender for remoteIP() and remotePort() and its unread size for available() and read().

Returns

Size of the queued packet in bytes, or 0 if none is queued.

peek()

int EthernetUDP::peek ( )

virtual

Returns the next byte of the current packet without consuming it.

Returns

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

read() [1/3]

int EthernetUDP::read ( )

virtual

Reads one byte from the current packet.

Returns

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

read() [2/3]

virtual int EthernetUDP::read ( char *  buffer, size_t  len  )

inlinevirtual

Reads up to len characters from the current packet into buffer.

Forwards to read(unsigned char *, size_t).

Parameters

buffer	Destination buffer; must hold at least len bytes.
len	Maximum number of characters to read.

Returns

Number of characters read, or -1 if no data is available.

read() [3/3]

int EthernetUDP::read ( unsigned char *  buffer, size_t  len  )

virtual

Reads up to len bytes from the current packet into buffer.

Reads at most the number of unread bytes in the packet.

Parameters

buffer	Destination buffer; must hold at least len bytes.
len	Maximum number of bytes to read.

Returns

Number of bytes read, or -1 if no data is available.

remoteIP()

virtual IPAddress EthernetUDP::remoteIP ( )

inlinevirtual

Returns the IP address of the sender of the current packet.

The value is set by parsePacket().

Returns

Remote IP address.

remotePort()

virtual uint16_t EthernetUDP::remotePort ( )

inlinevirtual

Returns the port of the sender of the current packet.

The value is set by parsePacket().

Returns

Remote port number.

stop()

void EthernetUDP::stop ( )

virtual

Closes the UDP socket.

Does nothing if no socket is open.

write() [1/2]

size_t EthernetUDP::write ( const uint8_t *  buffer, size_t  size  )

virtual

Appends a block of bytes to the outgoing packet.

Data accumulates until endPacket() sends it. On failure, the data already buffered for the packet is kept and the new bytes are not added.

Parameters

buffer	Bytes to append.
size	Number of bytes in buffer.

Returns

size on success, 0 on failure.

write() [2/2]

size_t EthernetUDP::write ( uint8_t  byte )

virtual

Appends one byte to the outgoing packet.

Parameters

byte	Byte to append.

Returns

1 if the byte was stored, 0 on allocation failure.

Member Data Documentation

_remaining

uint16_t EthernetUDP::_remaining

protected

---

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

• src/EthernetUdp.h
• src/EthernetUdp.cpp