uv_udp_t — UDP handle

UDP handles encapsulate UDP communication for both clients and servers.

Data types

uv_udp_t

UDP handle type.

uv_udp_send_t

UDP send request type.

uv_udp_flags

Flags used in uv_udp_bind() and uv_udp_recv_cb..

enum uv_udp_flags {
    /* Disables dual stack mode. */
    UV_UDP_IPV6ONLY = 1,
    /*
    * Indicates message was truncated because read buffer was too small. The
    * remainder was discarded by the OS. Used in uv_udp_recv_cb.
    */
    UV_UDP_PARTIAL = 2,
    /*
    * Indicates if SO_REUSEADDR will be set when binding the handle in
    * uv_udp_bind.
    * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other
    * Unix platforms, it sets the SO_REUSEADDR flag. What that means is that
    * multiple threads or processes can bind to the same address without error
    * (provided they all set the flag) but only the last one to bind will receive
    * any traffic, in effect "stealing" the port from the previous listener.
    */
    UV_UDP_REUSEADDR = 4
};
void (*uv_udp_send_cb)(uv_udp_send_t* req, int status)

Type definition for callback passed to uv_udp_send(), which is called after the data was sent.

void (*uv_udp_recv_cb)(uv_udp_t* handle, ssize_t nread, const uv_buf_t* buf, const struct sockaddr* addr, unsigned flags)

Type definition for callback passed to uv_udp_recv_start(), which is called when the endpoint receives data.

  • handle: UDP handle
  • nread: Number of bytes that have been received. 0 if there is no more data to read. You may discard or repurpose the read buffer. Note that 0 may also mean that an empty datagram was received (in this case addr is not NULL). < 0 if a transmission error was detected.
  • buf: uv_buf_t with the received data.
  • addr: struct sockaddr* containing the address of the sender. Can be NULL. Valid for the duration of the callback only.
  • flags: One or more or’ed UV_UDP_* constants. Right now only UV_UDP_PARTIAL is used.

Note

The receive callback will be called with nread == 0 and addr == NULL when there is nothing to read, and with nread == 0 and addr != NULL when an empty UDP packet is received.

uv_membership

Membership type for a multicast address.

typedef enum {
    UV_LEAVE_GROUP = 0,
    UV_JOIN_GROUP
} uv_membership;

Public members

size_t uv_udp_t.send_queue_size

Number of bytes queued for sending. This field strictly shows how much information is currently queued.

size_t uv_udp_t.send_queue_count

Number of send requests currently in the queue awaiting to be processed.

uv_udp_t* uv_udp_send_t.handle

UDP handle where this send request is taking place.

See also

The uv_handle_t members also apply.

API

int uv_udp_init(uv_loop_t* loop, uv_udp_t* handle)

Initialize a new UDP handle. The actual socket is created lazily. Returns 0 on success.

int uv_udp_init_ex(uv_loop_t* loop, uv_udp_t* handle, unsigned int flags)

Initialize the handle with the specified flags. At the moment the lower 8 bits of the flags parameter are used as the socket domain. A socket will be created for the given domain. If the specified domain is AF_UNSPEC no socket is created, just like uv_udp_init().

New in version 1.7.0.

int uv_udp_open(uv_udp_t* handle, uv_os_sock_t sock)

Opens an existing file descriptor or Windows SOCKET as a UDP handle.

Unix only: The only requirement of the sock argument is that it follows the datagram contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc). In other words, other datagram-type sockets like raw sockets or netlink sockets can also be passed to this function.

Changed in version 1.2.1: the file descriptor is set to non-blocking mode.

Note

The passed file descriptor or SOCKET is not checked for its type, but it’s required that it represents a valid datagram socket.

int uv_udp_bind(uv_udp_t* handle, const struct sockaddr* addr, unsigned int flags)

Bind the UDP handle to an IP address and port.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • addr – struct sockaddr_in or struct sockaddr_in6 with the address and port to bind to.
  • flags – Indicate how the socket will be bound, UV_UDP_IPV6ONLY and UV_UDP_REUSEADDR are supported.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_getsockname(const uv_udp_t* handle, struct sockaddr* name, int* namelen)

Get the local IP and port of the UDP handle.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init() and bound.
  • name – Pointer to the structure to be filled with the address data. In order to support IPv4 and IPv6 struct sockaddr_storage should be used.
  • namelen – On input it indicates the data of the name field. On output it indicates how much of it was filled.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_set_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, uv_membership membership)

Set membership for a multicast address

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • multicast_addr – Multicast address to set membership for.
  • interface_addr – Interface address.
  • membership – Should be UV_JOIN_GROUP or UV_LEAVE_GROUP.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_set_multicast_loop(uv_udp_t* handle, int on)

Set IP multicast loop flag. Makes multicast packets loop back to local sockets.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • on – 1 for on, 0 for off.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl)

Set the multicast ttl.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • ttl – 1 through 255.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_set_multicast_interface(uv_udp_t* handle, const char* interface_addr)

Set the multicast interface to send or receive data on.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • interface_addr – interface address.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_set_broadcast(uv_udp_t* handle, int on)

Set broadcast on or off.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • on – 1 for on, 0 for off.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_set_ttl(uv_udp_t* handle, int ttl)

Set the time to live.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • ttl – 1 through 255.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_send(uv_udp_send_t* req, uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr, uv_udp_send_cb send_cb)

Send data over the UDP socket. If the socket has not previously been bound with uv_udp_bind() it will be bound to 0.0.0.0 (the “all interfaces” IPv4 address) and a random port number.

Parameters:
  • req – UDP request handle. Need not be initialized.
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • bufs – List of buffers to send.
  • nbufs – Number of buffers in bufs.
  • addr – struct sockaddr_in or struct sockaddr_in6 with the address and port of the remote peer.
  • send_cb – Callback to invoke when the data has been sent out.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_try_send(uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr)

Same as uv_udp_send(), but won’t queue a send request if it can’t be completed immediately.

Returns:>= 0: number of bytes sent (it matches the given buffer size). < 0: negative error code (UV_EAGAIN is returned when the message can’t be sent immediately).
int uv_udp_recv_start(uv_udp_t* handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb)

Prepare for receiving data. If the socket has not previously been bound with uv_udp_bind() it is bound to 0.0.0.0 (the “all interfaces” IPv4 address) and a random port number.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
  • alloc_cb – Callback to invoke when temporary storage is needed.
  • recv_cb – Callback to invoke with received data.
Returns:

0 on success, or an error code < 0 on failure.
int uv_udp_recv_stop(uv_udp_t* handle)

Stop listening for incoming datagrams.

Parameters:
  • handle – UDP handle. Should have been initialized with uv_udp_init().
Returns:

0 on success, or an error code < 0 on failure.

See also

The uv_handle_t API functions also apply.