udp: add support for UDP connected sockets

Add two new methods:

`uv_udp_connect()` to connect / disconnect an UDP handle.
`uv_udp_getpeername()` to get the remote peer address of a connected UDP
handle.

Modify `uv_udp_send()` and `uv_udp_try_send()` to accept a `NULL` `addr`
to send messages over an "UDP connection".

Refs: https://github.com/libuv/leps/pull/10
PR-URL: https://github.com/libuv/libuv/pull/1872
Backport-PR-URL: https://github.com/libuv/libuv/pull/2217
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

1 files changed, 54 insertions, 0 deletions

diff --git a/docs/src/udp.rst b/docs/src/udp.rst
index 81488285..f3de53fb 100644
--- a/docs/src/udp.rst
+++ b/docs/src/udp.rst
@@ -150,6 +150,44 @@ API
 
     :returns: 0 on success, or an error code < 0 on failure.
 
+.. c:function:: int uv_udp_connect(uv_udp_t* handle, const struct sockaddr* addr)
+
+    Associate the UDP handle to a remote address and port, so every
+    message sent by this handle is automatically sent to that destination.
+    Calling this function with a `NULL` `addr` disconnects the handle.
+    Trying to call `uv_udp_connect()` on an already connected handle will result
+    in an `UV_EISCONN` error. Trying to disconnect a handle that is not
+    connected will return an `UV_ENOTCONN` error.
+
+    :param handle: UDP handle. Should have been initialized with
+        :c:func:`uv_udp_init`.
+
+    :param addr: `struct sockaddr_in` or `struct sockaddr_in6`
+        with the address and port to associate to.
+
+    :returns: 0 on success, or an error code < 0 on failure.
+
+    .. versionadded:: 1.27.0
+
+.. c:function:: int uv_udp_getpeername(const uv_udp_t* handle, struct sockaddr* name, int* namelen)
+
+    Get the remote IP and port of the UDP handle on connected UDP handles.
+    On unconnected handles, it returns `UV_ENOTCONN`.
+
+    :param handle: UDP handle. Should have been initialized with
+        :c:func:`uv_udp_init` and bound.
+
+    :param 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.
+
+    :param 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
+
+    .. versionadded:: 1.27.0
+
 .. c:function:: int uv_udp_getsockname(const uv_udp_t* handle, struct sockaddr* name, int* namelen)
 
     Get the local IP and port of the UDP handle.
@@ -247,6 +285,12 @@ API
     (``0.0.0.0`` or ``::``) it will be changed to point to ``localhost``.
     This is done to match the behavior of Linux systems.
 
+    For connected UDP handles, `addr` must be set to `NULL`, otherwise it will
+    return `UV_EISCONN` error.
+
+    For connectionless UDP handles, `addr` cannot be `NULL`, otherwise it will
+    return `UV_EDESTADDRREQ` error.
+
     :param req: UDP request handle. Need not be initialized.
 
     :param handle: UDP handle. Should have been initialized with
@@ -266,15 +310,25 @@ API
     .. versionchanged:: 1.19.0 added ``0.0.0.0`` and ``::`` to ``localhost``
         mapping
 
+    .. versionchanged:: 1.27.0 added support for connected sockets
+
 .. c:function:: int uv_udp_try_send(uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr)
 
     Same as :c:func:`uv_udp_send`, but won't queue a send request if it can't
     be completed immediately.
 
+    For connected UDP handles, `addr` must be set to `NULL`, otherwise it will
+    return `UV_EISCONN` error.
+
+    For connectionless UDP handles, `addr` cannot be `NULL`, otherwise it will
+    return `UV_EDESTADDRREQ` error.
+
     :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).
 
+    .. versionchanged:: 1.27.0 added support for connected sockets
+
 .. c:function:: 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