1 2.. _udp: 3 4:c:type:`uv_udp_t` --- UDP handle 5================================= 6 7UDP handles encapsulate UDP communication for both clients and servers. 8 9 10Data types 11---------- 12 13.. c:type:: uv_udp_t 14 15 UDP handle type. 16 17.. c:type:: uv_udp_send_t 18 19 UDP send request type. 20 21.. c:type:: uv_udp_flags 22 23 Flags used in :c:func:`uv_udp_bind` and :c:type:`uv_udp_recv_cb`.. 24 25 :: 26 27 enum uv_udp_flags { 28 /* Disables dual stack mode. */ 29 UV_UDP_IPV6ONLY = 1, 30 /* 31 * Indicates message was truncated because read buffer was too small. The 32 * remainder was discarded by the OS. Used in uv_udp_recv_cb. 33 */ 34 UV_UDP_PARTIAL = 2, 35 /* 36 * Indicates if SO_REUSEADDR will be set when binding the handle in 37 * uv_udp_bind. 38 * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other 39 * Unix platforms, it sets the SO_REUSEADDR flag. What that means is that 40 * multiple threads or processes can bind to the same address without error 41 * (provided they all set the flag) but only the last one to bind will receive 42 * any traffic, in effect "stealing" the port from the previous listener. 43 */ 44 UV_UDP_REUSEADDR = 4 45 /* 46 * Indicates that the message was received by recvmmsg and that it's not at 47 * the beginning of the buffer allocated by alloc_cb - so the buffer provided 48 * must not be freed by the recv_cb callback. 49 */ 50 UV_UDP_MMSG_CHUNK = 8 51 }; 52 53.. c:type:: void (*uv_udp_send_cb)(uv_udp_send_t* req, int status) 54 55 Type definition for callback passed to :c:func:`uv_udp_send`, which is 56 called after the data was sent. 57 58.. c:type:: void (*uv_udp_recv_cb)(uv_udp_t* handle, ssize_t nread, const uv_buf_t* buf, const struct sockaddr* addr, unsigned flags) 59 60 Type definition for callback passed to :c:func:`uv_udp_recv_start`, which 61 is called when the endpoint receives data. 62 63 * `handle`: UDP handle 64 * `nread`: Number of bytes that have been received. 65 0 if there is no more data to read. Note that 0 may also mean that an 66 empty datagram was received (in this case `addr` is not NULL). < 0 if 67 a transmission error was detected. 68 * `buf`: :c:type:`uv_buf_t` with the received data. 69 * `addr`: ``struct sockaddr*`` containing the address of the sender. 70 Can be NULL. Valid for the duration of the callback only. 71 * `flags`: One or more or'ed UV_UDP_* constants. 72 73 The callee is responsible for freeing the buffer, libuv does not reuse it. 74 The buffer may be a null buffer (where `buf->base` == NULL and `buf->len` == 0) 75 on error. Don't free the buffer when the UV_UDP_MMSG_CHUNK flag is set. 76 The final callback receives the whole buffer (containing the first chunk) 77 with the UV_UDP_MMSG_CHUNK flag cleared. 78 79 .. note:: 80 The receive callback will be called with `nread` == 0 and `addr` == NULL when there is 81 nothing to read, and with `nread` == 0 and `addr` != NULL when an empty UDP packet is 82 received. 83 84.. c:type:: uv_membership 85 86 Membership type for a multicast address. 87 88 :: 89 90 typedef enum { 91 UV_LEAVE_GROUP = 0, 92 UV_JOIN_GROUP 93 } uv_membership; 94 95 96Public members 97^^^^^^^^^^^^^^ 98 99.. c:member:: size_t uv_udp_t.send_queue_size 100 101 Number of bytes queued for sending. This field strictly shows how much 102 information is currently queued. 103 104.. c:member:: size_t uv_udp_t.send_queue_count 105 106 Number of send requests currently in the queue awaiting to be processed. 107 108.. c:member:: uv_udp_t* uv_udp_send_t.handle 109 110 UDP handle where this send request is taking place. 111 112.. seealso:: The :c:type:`uv_handle_t` members also apply. 113 114 115API 116--- 117 118.. c:function:: int uv_udp_init(uv_loop_t* loop, uv_udp_t* handle) 119 120 Initialize a new UDP handle. The actual socket is created lazily. 121 Returns 0 on success. 122 123.. c:function:: int uv_udp_init_ex(uv_loop_t* loop, uv_udp_t* handle, unsigned int flags) 124 125 Initialize the handle with the specified flags. At the moment the lower 8 bits 126 of the `flags` parameter are used as the socket domain. A socket will be created 127 for the given domain. If the specified domain is ``AF_UNSPEC`` no socket is created, 128 just like :c:func:`uv_udp_init`. 129 130 .. versionadded:: 1.7.0 131 132.. c:function:: int uv_udp_open(uv_udp_t* handle, uv_os_sock_t sock) 133 134 Opens an existing file descriptor or Windows SOCKET as a UDP handle. 135 136 Unix only: 137 The only requirement of the `sock` argument is that it follows the datagram 138 contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc). 139 In other words, other datagram-type sockets like raw sockets or netlink 140 sockets can also be passed to this function. 141 142 .. versionchanged:: 1.2.1 the file descriptor is set to non-blocking mode. 143 144 .. note:: 145 The passed file descriptor or SOCKET is not checked for its type, but 146 it's required that it represents a valid datagram socket. 147 148.. c:function:: int uv_udp_bind(uv_udp_t* handle, const struct sockaddr* addr, unsigned int flags) 149 150 Bind the UDP handle to an IP address and port. 151 152 :param handle: UDP handle. Should have been initialized with 153 :c:func:`uv_udp_init`. 154 155 :param addr: `struct sockaddr_in` or `struct sockaddr_in6` 156 with the address and port to bind to. 157 158 :param flags: Indicate how the socket will be bound, 159 ``UV_UDP_IPV6ONLY`` and ``UV_UDP_REUSEADDR`` are supported. 160 161 :returns: 0 on success, or an error code < 0 on failure. 162 163.. c:function:: int uv_udp_connect(uv_udp_t* handle, const struct sockaddr* addr) 164 165 Associate the UDP handle to a remote address and port, so every 166 message sent by this handle is automatically sent to that destination. 167 Calling this function with a `NULL` `addr` disconnects the handle. 168 Trying to call `uv_udp_connect()` on an already connected handle will result 169 in an `UV_EISCONN` error. Trying to disconnect a handle that is not 170 connected will return an `UV_ENOTCONN` error. 171 172 :param handle: UDP handle. Should have been initialized with 173 :c:func:`uv_udp_init`. 174 175 :param addr: `struct sockaddr_in` or `struct sockaddr_in6` 176 with the address and port to associate to. 177 178 :returns: 0 on success, or an error code < 0 on failure. 179 180 .. versionadded:: 1.27.0 181 182.. c:function:: int uv_udp_getpeername(const uv_udp_t* handle, struct sockaddr* name, int* namelen) 183 184 Get the remote IP and port of the UDP handle on connected UDP handles. 185 On unconnected handles, it returns `UV_ENOTCONN`. 186 187 :param handle: UDP handle. Should have been initialized with 188 :c:func:`uv_udp_init` and bound. 189 190 :param name: Pointer to the structure to be filled with the address data. 191 In order to support IPv4 and IPv6 `struct sockaddr_storage` should be 192 used. 193 194 :param namelen: On input it indicates the data of the `name` field. On 195 output it indicates how much of it was filled. 196 197 :returns: 0 on success, or an error code < 0 on failure 198 199 .. versionadded:: 1.27.0 200 201.. c:function:: int uv_udp_getsockname(const uv_udp_t* handle, struct sockaddr* name, int* namelen) 202 203 Get the local IP and port of the UDP handle. 204 205 :param handle: UDP handle. Should have been initialized with 206 :c:func:`uv_udp_init` and bound. 207 208 :param name: Pointer to the structure to be filled with the address data. 209 In order to support IPv4 and IPv6 `struct sockaddr_storage` should be 210 used. 211 212 :param namelen: On input it indicates the data of the `name` field. On 213 output it indicates how much of it was filled. 214 215 :returns: 0 on success, or an error code < 0 on failure. 216 217.. c:function:: int uv_udp_set_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, uv_membership membership) 218 219 Set membership for a multicast address 220 221 :param handle: UDP handle. Should have been initialized with 222 :c:func:`uv_udp_init`. 223 224 :param multicast_addr: Multicast address to set membership for. 225 226 :param interface_addr: Interface address. 227 228 :param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``. 229 230 :returns: 0 on success, or an error code < 0 on failure. 231 232.. c:function:: int uv_udp_set_source_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, const char* source_addr, uv_membership membership) 233 234 Set membership for a source-specific multicast group. 235 236 :param handle: UDP handle. Should have been initialized with 237 :c:func:`uv_udp_init`. 238 239 :param multicast_addr: Multicast address to set membership for. 240 241 :param interface_addr: Interface address. 242 243 :param source_addr: Source address. 244 245 :param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``. 246 247 :returns: 0 on success, or an error code < 0 on failure. 248 249 .. versionadded:: 1.32.0 250 251.. c:function:: int uv_udp_set_multicast_loop(uv_udp_t* handle, int on) 252 253 Set IP multicast loop flag. Makes multicast packets loop back to 254 local sockets. 255 256 :param handle: UDP handle. Should have been initialized with 257 :c:func:`uv_udp_init`. 258 259 :param on: 1 for on, 0 for off. 260 261 :returns: 0 on success, or an error code < 0 on failure. 262 263.. c:function:: int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl) 264 265 Set the multicast ttl. 266 267 :param handle: UDP handle. Should have been initialized with 268 :c:func:`uv_udp_init`. 269 270 :param ttl: 1 through 255. 271 272 :returns: 0 on success, or an error code < 0 on failure. 273 274.. c:function:: int uv_udp_set_multicast_interface(uv_udp_t* handle, const char* interface_addr) 275 276 Set the multicast interface to send or receive data on. 277 278 :param handle: UDP handle. Should have been initialized with 279 :c:func:`uv_udp_init`. 280 281 :param interface_addr: interface address. 282 283 :returns: 0 on success, or an error code < 0 on failure. 284 285.. c:function:: int uv_udp_set_broadcast(uv_udp_t* handle, int on) 286 287 Set broadcast on or off. 288 289 :param handle: UDP handle. Should have been initialized with 290 :c:func:`uv_udp_init`. 291 292 :param on: 1 for on, 0 for off. 293 294 :returns: 0 on success, or an error code < 0 on failure. 295 296.. c:function:: int uv_udp_set_ttl(uv_udp_t* handle, int ttl) 297 298 Set the time to live. 299 300 :param handle: UDP handle. Should have been initialized with 301 :c:func:`uv_udp_init`. 302 303 :param ttl: 1 through 255. 304 305 :returns: 0 on success, or an error code < 0 on failure. 306 307.. c:function:: 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) 308 309 Send data over the UDP socket. If the socket has not previously been bound 310 with :c:func:`uv_udp_bind` it will be bound to 0.0.0.0 311 (the "all interfaces" IPv4 address) and a random port number. 312 313 On Windows if the `addr` is initialized to point to an unspecified address 314 (``0.0.0.0`` or ``::``) it will be changed to point to ``localhost``. 315 This is done to match the behavior of Linux systems. 316 317 For connected UDP handles, `addr` must be set to `NULL`, otherwise it will 318 return `UV_EISCONN` error. 319 320 For connectionless UDP handles, `addr` cannot be `NULL`, otherwise it will 321 return `UV_EDESTADDRREQ` error. 322 323 :param req: UDP request handle. Need not be initialized. 324 325 :param handle: UDP handle. Should have been initialized with 326 :c:func:`uv_udp_init`. 327 328 :param bufs: List of buffers to send. 329 330 :param nbufs: Number of buffers in `bufs`. 331 332 :param addr: `struct sockaddr_in` or `struct sockaddr_in6` with the 333 address and port of the remote peer. 334 335 :param send_cb: Callback to invoke when the data has been sent out. 336 337 :returns: 0 on success, or an error code < 0 on failure. 338 339 .. versionchanged:: 1.19.0 added ``0.0.0.0`` and ``::`` to ``localhost`` 340 mapping 341 342 .. versionchanged:: 1.27.0 added support for connected sockets 343 344.. c:function:: int uv_udp_try_send(uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr) 345 346 Same as :c:func:`uv_udp_send`, but won't queue a send request if it can't 347 be completed immediately. 348 349 For connected UDP handles, `addr` must be set to `NULL`, otherwise it will 350 return `UV_EISCONN` error. 351 352 For connectionless UDP handles, `addr` cannot be `NULL`, otherwise it will 353 return `UV_EDESTADDRREQ` error. 354 355 :returns: >= 0: number of bytes sent (it matches the given buffer size). 356 < 0: negative error code (``UV_EAGAIN`` is returned when the message 357 can't be sent immediately). 358 359 .. versionchanged:: 1.27.0 added support for connected sockets 360 361.. c:function:: int uv_udp_recv_start(uv_udp_t* handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb) 362 363 Prepare for receiving data. If the socket has not previously been bound 364 with :c:func:`uv_udp_bind` it is bound to 0.0.0.0 (the "all interfaces" 365 IPv4 address) and a random port number. 366 367 :param handle: UDP handle. Should have been initialized with 368 :c:func:`uv_udp_init`. 369 370 :param alloc_cb: Callback to invoke when temporary storage is needed. 371 372 :param recv_cb: Callback to invoke with received data. 373 374 :returns: 0 on success, or an error code < 0 on failure. 375 376.. c:function:: int uv_udp_recv_stop(uv_udp_t* handle) 377 378 Stop listening for incoming datagrams. 379 380 :param handle: UDP handle. Should have been initialized with 381 :c:func:`uv_udp_init`. 382 383 :returns: 0 on success, or an error code < 0 on failure. 384 385.. c:function:: size_t uv_udp_get_send_queue_size(const uv_udp_t* handle) 386 387 Returns `handle->send_queue_size`. 388 389 .. versionadded:: 1.19.0 390 391.. c:function:: size_t uv_udp_get_send_queue_count(const uv_udp_t* handle) 392 393 Returns `handle->send_queue_count`. 394 395 .. versionadded:: 1.19.0 396 397.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 398