dgram.d.ts (27569B)
1 /** 2 * The `dgram` module provides an implementation of UDP datagram sockets. 3 * 4 * ```js 5 * import dgram from 'dgram'; 6 * 7 * const server = dgram.createSocket('udp4'); 8 * 9 * server.on('error', (err) => { 10 * console.log(`server error:\n${err.stack}`); 11 * server.close(); 12 * }); 13 * 14 * server.on('message', (msg, rinfo) => { 15 * console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`); 16 * }); 17 * 18 * server.on('listening', () => { 19 * const address = server.address(); 20 * console.log(`server listening ${address.address}:${address.port}`); 21 * }); 22 * 23 * server.bind(41234); 24 * // Prints: server listening 0.0.0.0:41234 25 * ``` 26 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/dgram.js) 27 */ 28 declare module "dgram" { 29 import { AddressInfo } from "node:net"; 30 import * as dns from "node:dns"; 31 import { Abortable, EventEmitter } from "node:events"; 32 interface RemoteInfo { 33 address: string; 34 family: "IPv4" | "IPv6"; 35 port: number; 36 size: number; 37 } 38 interface BindOptions { 39 port?: number | undefined; 40 address?: string | undefined; 41 exclusive?: boolean | undefined; 42 fd?: number | undefined; 43 } 44 type SocketType = "udp4" | "udp6"; 45 interface SocketOptions extends Abortable { 46 type: SocketType; 47 reuseAddr?: boolean | undefined; 48 /** 49 * @default false 50 */ 51 ipv6Only?: boolean | undefined; 52 recvBufferSize?: number | undefined; 53 sendBufferSize?: number | undefined; 54 lookup?: 55 | (( 56 hostname: string, 57 options: dns.LookupOneOptions, 58 callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, 59 ) => void) 60 | undefined; 61 } 62 /** 63 * Creates a `dgram.Socket` object. Once the socket is created, calling `socket.bind()` will instruct the socket to begin listening for datagram 64 * messages. When `address` and `port` are not passed to `socket.bind()` the 65 * method will bind the socket to the "all interfaces" address on a random port 66 * (it does the right thing for both `udp4` and `udp6` sockets). The bound address 67 * and port can be retrieved using `socket.address().address` and `socket.address().port`. 68 * 69 * If the `signal` option is enabled, calling `.abort()` on the corresponding`AbortController` is similar to calling `.close()` on the socket: 70 * 71 * ```js 72 * const controller = new AbortController(); 73 * const { signal } = controller; 74 * const server = dgram.createSocket({ type: 'udp4', signal }); 75 * server.on('message', (msg, rinfo) => { 76 * console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`); 77 * }); 78 * // Later, when you want to close the server. 79 * controller.abort(); 80 * ``` 81 * @since v0.11.13 82 * @param options Available options are: 83 * @param callback Attached as a listener for `'message'` events. Optional. 84 */ 85 function createSocket(type: SocketType, callback?: (msg: Buffer, rinfo: RemoteInfo) => void): Socket; 86 function createSocket(options: SocketOptions, callback?: (msg: Buffer, rinfo: RemoteInfo) => void): Socket; 87 /** 88 * Encapsulates the datagram functionality. 89 * 90 * New instances of `dgram.Socket` are created using {@link createSocket}. 91 * The `new` keyword is not to be used to create `dgram.Socket` instances. 92 * @since v0.1.99 93 */ 94 class Socket extends EventEmitter { 95 /** 96 * Tells the kernel to join a multicast group at the given `multicastAddress` and `multicastInterface` using the `IP_ADD_MEMBERSHIP` socket option. If the`multicastInterface` argument is not 97 * specified, the operating system will choose 98 * one interface and will add membership to it. To add membership to every 99 * available interface, call `addMembership` multiple times, once per interface. 100 * 101 * When called on an unbound socket, this method will implicitly bind to a random 102 * port, listening on all interfaces. 103 * 104 * When sharing a UDP socket across multiple `cluster` workers, the`socket.addMembership()` function must be called only once or an`EADDRINUSE` error will occur: 105 * 106 * ```js 107 * import cluster from 'cluster'; 108 * import dgram from 'dgram'; 109 * 110 * if (cluster.isPrimary) { 111 * cluster.fork(); // Works ok. 112 * cluster.fork(); // Fails with EADDRINUSE. 113 * } else { 114 * const s = dgram.createSocket('udp4'); 115 * s.bind(1234, () => { 116 * s.addMembership('224.0.0.114'); 117 * }); 118 * } 119 * ``` 120 * @since v0.6.9 121 */ 122 addMembership(multicastAddress: string, multicastInterface?: string): void; 123 /** 124 * Returns an object containing the address information for a socket. 125 * For UDP sockets, this object will contain `address`, `family` and `port` properties. 126 * 127 * This method throws `EBADF` if called on an unbound socket. 128 * @since v0.1.99 129 */ 130 address(): AddressInfo; 131 /** 132 * For UDP sockets, causes the `dgram.Socket` to listen for datagram 133 * messages on a named `port` and optional `address`. If `port` is not 134 * specified or is `0`, the operating system will attempt to bind to a 135 * random port. If `address` is not specified, the operating system will 136 * attempt to listen on all addresses. Once binding is complete, a`'listening'` event is emitted and the optional `callback` function is 137 * called. 138 * 139 * Specifying both a `'listening'` event listener and passing a`callback` to the `socket.bind()` method is not harmful but not very 140 * useful. 141 * 142 * A bound datagram socket keeps the Node.js process running to receive 143 * datagram messages. 144 * 145 * If binding fails, an `'error'` event is generated. In rare case (e.g. 146 * attempting to bind with a closed socket), an `Error` may be thrown. 147 * 148 * Example of a UDP server listening on port 41234: 149 * 150 * ```js 151 * import dgram from 'dgram'; 152 * 153 * const server = dgram.createSocket('udp4'); 154 * 155 * server.on('error', (err) => { 156 * console.log(`server error:\n${err.stack}`); 157 * server.close(); 158 * }); 159 * 160 * server.on('message', (msg, rinfo) => { 161 * console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`); 162 * }); 163 * 164 * server.on('listening', () => { 165 * const address = server.address(); 166 * console.log(`server listening ${address.address}:${address.port}`); 167 * }); 168 * 169 * server.bind(41234); 170 * // Prints: server listening 0.0.0.0:41234 171 * ``` 172 * @since v0.1.99 173 * @param callback with no parameters. Called when binding is complete. 174 */ 175 bind(port?: number, address?: string, callback?: () => void): this; 176 bind(port?: number, callback?: () => void): this; 177 bind(callback?: () => void): this; 178 bind(options: BindOptions, callback?: () => void): this; 179 /** 180 * Close the underlying socket and stop listening for data on it. If a callback is 181 * provided, it is added as a listener for the `'close'` event. 182 * @since v0.1.99 183 * @param callback Called when the socket has been closed. 184 */ 185 close(callback?: () => void): this; 186 /** 187 * Associates the `dgram.Socket` to a remote address and port. Every 188 * message sent by this handle is automatically sent to that destination. Also, 189 * the socket will only receive messages from that remote peer. 190 * Trying to call `connect()` on an already connected socket will result 191 * in an `ERR_SOCKET_DGRAM_IS_CONNECTED` exception. If `address` is not 192 * provided, `'127.0.0.1'` (for `udp4` sockets) or `'::1'` (for `udp6` sockets) 193 * will be used by default. Once the connection is complete, a `'connect'` event 194 * is emitted and the optional `callback` function is called. In case of failure, 195 * the `callback` is called or, failing this, an `'error'` event is emitted. 196 * @since v12.0.0 197 * @param callback Called when the connection is completed or on error. 198 */ 199 connect(port: number, address?: string, callback?: () => void): void; 200 connect(port: number, callback: () => void): void; 201 /** 202 * A synchronous function that disassociates a connected `dgram.Socket` from 203 * its remote address. Trying to call `disconnect()` on an unbound or already 204 * disconnected socket will result in an `ERR_SOCKET_DGRAM_NOT_CONNECTED` exception. 205 * @since v12.0.0 206 */ 207 disconnect(): void; 208 /** 209 * Instructs the kernel to leave a multicast group at `multicastAddress` using the`IP_DROP_MEMBERSHIP` socket option. This method is automatically called by the 210 * kernel when the socket is closed or the process terminates, so most apps will 211 * never have reason to call this. 212 * 213 * If `multicastInterface` is not specified, the operating system will attempt to 214 * drop membership on all valid interfaces. 215 * @since v0.6.9 216 */ 217 dropMembership(multicastAddress: string, multicastInterface?: string): void; 218 /** 219 * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. 220 * @since v8.7.0 221 * @return the `SO_RCVBUF` socket receive buffer size in bytes. 222 */ 223 getRecvBufferSize(): number; 224 /** 225 * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. 226 * @since v8.7.0 227 * @return the `SO_SNDBUF` socket send buffer size in bytes. 228 */ 229 getSendBufferSize(): number; 230 /** 231 * @since v16.19.0 232 * @return the number of bytes queued for sending. 233 */ 234 getSendQueueSize(): number; 235 /** 236 * @since v16.19.0 237 * @return the number of send requests currently in the queue awaiting to be processed. 238 */ 239 getSendQueueCount(): number; 240 /** 241 * By default, binding a socket will cause it to block the Node.js process from 242 * exiting as long as the socket is open. The `socket.unref()` method can be used 243 * to exclude the socket from the reference counting that keeps the Node.js 244 * process active. The `socket.ref()` method adds the socket back to the reference 245 * counting and restores the default behavior. 246 * 247 * Calling `socket.ref()` multiples times will have no additional effect. 248 * 249 * The `socket.ref()` method returns a reference to the socket so calls can be 250 * chained. 251 * @since v0.9.1 252 */ 253 ref(): this; 254 /** 255 * Returns an object containing the `address`, `family`, and `port` of the remote 256 * endpoint. This method throws an `ERR_SOCKET_DGRAM_NOT_CONNECTED` exception 257 * if the socket is not connected. 258 * @since v12.0.0 259 */ 260 remoteAddress(): AddressInfo; 261 /** 262 * Broadcasts a datagram on the socket. 263 * For connectionless sockets, the destination `port` and `address` must be 264 * specified. Connected sockets, on the other hand, will use their associated 265 * remote endpoint, so the `port` and `address` arguments must not be set. 266 * 267 * The `msg` argument contains the message to be sent. 268 * Depending on its type, different behavior can apply. If `msg` is a `Buffer`, 269 * any `TypedArray` or a `DataView`, 270 * the `offset` and `length` specify the offset within the `Buffer` where the 271 * message begins and the number of bytes in the message, respectively. 272 * If `msg` is a `String`, then it is automatically converted to a `Buffer`with `'utf8'` encoding. With messages that 273 * contain multi-byte characters, `offset` and `length` will be calculated with 274 * respect to `byte length` and not the character position. 275 * If `msg` is an array, `offset` and `length` must not be specified. 276 * 277 * The `address` argument is a string. If the value of `address` is a host name, 278 * DNS will be used to resolve the address of the host. If `address` is not 279 * provided or otherwise falsy, `'127.0.0.1'` (for `udp4` sockets) or `'::1'` (for `udp6` sockets) will be used by default. 280 * 281 * If the socket has not been previously bound with a call to `bind`, the socket 282 * is assigned a random port number and is bound to the "all interfaces" address 283 * (`'0.0.0.0'` for `udp4` sockets, `'::0'` for `udp6` sockets.) 284 * 285 * An optional `callback` function may be specified to as a way of reporting 286 * DNS errors or for determining when it is safe to reuse the `buf` object. 287 * DNS lookups delay the time to send for at least one tick of the 288 * Node.js event loop. 289 * 290 * The only way to know for sure that the datagram has been sent is by using a`callback`. If an error occurs and a `callback` is given, the error will be 291 * passed as the first argument to the `callback`. If a `callback` is not given, 292 * the error is emitted as an `'error'` event on the `socket` object. 293 * 294 * Offset and length are optional but both _must_ be set if either are used. 295 * They are supported only when the first argument is a `Buffer`, a `TypedArray`, 296 * or a `DataView`. 297 * 298 * This method throws `ERR_SOCKET_BAD_PORT` if called on an unbound socket. 299 * 300 * Example of sending a UDP packet to a port on `localhost`; 301 * 302 * ```js 303 * import dgram from 'dgram'; 304 * import { Buffer } from 'buffer'; 305 * 306 * const message = Buffer.from('Some bytes'); 307 * const client = dgram.createSocket('udp4'); 308 * client.send(message, 41234, 'localhost', (err) => { 309 * client.close(); 310 * }); 311 * ``` 312 * 313 * Example of sending a UDP packet composed of multiple buffers to a port on`127.0.0.1`; 314 * 315 * ```js 316 * import dgram from 'dgram'; 317 * import { Buffer } from 'buffer'; 318 * 319 * const buf1 = Buffer.from('Some '); 320 * const buf2 = Buffer.from('bytes'); 321 * const client = dgram.createSocket('udp4'); 322 * client.send([buf1, buf2], 41234, (err) => { 323 * client.close(); 324 * }); 325 * ``` 326 * 327 * Sending multiple buffers might be faster or slower depending on the 328 * application and operating system. Run benchmarks to 329 * determine the optimal strategy on a case-by-case basis. Generally speaking, 330 * however, sending multiple buffers is faster. 331 * 332 * Example of sending a UDP packet using a socket connected to a port on`localhost`: 333 * 334 * ```js 335 * import dgram from 'dgram'; 336 * import { Buffer } from 'buffer'; 337 * 338 * const message = Buffer.from('Some bytes'); 339 * const client = dgram.createSocket('udp4'); 340 * client.connect(41234, 'localhost', (err) => { 341 * client.send(message, (err) => { 342 * client.close(); 343 * }); 344 * }); 345 * ``` 346 * @since v0.1.99 347 * @param msg Message to be sent. 348 * @param offset Offset in the buffer where the message starts. 349 * @param length Number of bytes in the message. 350 * @param port Destination port. 351 * @param address Destination host name or IP address. 352 * @param callback Called when the message has been sent. 353 */ 354 send( 355 msg: string | NodeJS.ArrayBufferView | readonly any[], 356 port?: number, 357 address?: string, 358 callback?: (error: Error | null, bytes: number) => void, 359 ): void; 360 send( 361 msg: string | NodeJS.ArrayBufferView | readonly any[], 362 port?: number, 363 callback?: (error: Error | null, bytes: number) => void, 364 ): void; 365 send( 366 msg: string | NodeJS.ArrayBufferView | readonly any[], 367 callback?: (error: Error | null, bytes: number) => void, 368 ): void; 369 send( 370 msg: string | NodeJS.ArrayBufferView, 371 offset: number, 372 length: number, 373 port?: number, 374 address?: string, 375 callback?: (error: Error | null, bytes: number) => void, 376 ): void; 377 send( 378 msg: string | NodeJS.ArrayBufferView, 379 offset: number, 380 length: number, 381 port?: number, 382 callback?: (error: Error | null, bytes: number) => void, 383 ): void; 384 send( 385 msg: string | NodeJS.ArrayBufferView, 386 offset: number, 387 length: number, 388 callback?: (error: Error | null, bytes: number) => void, 389 ): void; 390 /** 391 * Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP 392 * packets may be sent to a local interface's broadcast address. 393 * 394 * This method throws `EBADF` if called on an unbound socket. 395 * @since v0.6.9 396 */ 397 setBroadcast(flag: boolean): void; 398 /** 399 * _All references to scope in this section are referring to [IPv6 Zone Indices](https://en.wikipedia.org/wiki/IPv6_address#Scoped_literal_IPv6_addresses), which are defined by [RFC 400 * 4007](https://tools.ietf.org/html/rfc4007). In string form, an IP_ 401 * _with a scope index is written as `'IP%scope'` where scope is an interface name_ 402 * _or interface number._ 403 * 404 * Sets the default outgoing multicast interface of the socket to a chosen 405 * interface or back to system interface selection. The `multicastInterface` must 406 * be a valid string representation of an IP from the socket's family. 407 * 408 * For IPv4 sockets, this should be the IP configured for the desired physical 409 * interface. All packets sent to multicast on the socket will be sent on the 410 * interface determined by the most recent successful use of this call. 411 * 412 * For IPv6 sockets, `multicastInterface` should include a scope to indicate the 413 * interface as in the examples that follow. In IPv6, individual `send` calls can 414 * also use explicit scope in addresses, so only packets sent to a multicast 415 * address without specifying an explicit scope are affected by the most recent 416 * successful use of this call. 417 * 418 * This method throws `EBADF` if called on an unbound socket. 419 * 420 * #### Example: IPv6 outgoing multicast interface 421 * 422 * On most systems, where scope format uses the interface name: 423 * 424 * ```js 425 * const socket = dgram.createSocket('udp6'); 426 * 427 * socket.bind(1234, () => { 428 * socket.setMulticastInterface('::%eth1'); 429 * }); 430 * ``` 431 * 432 * On Windows, where scope format uses an interface number: 433 * 434 * ```js 435 * const socket = dgram.createSocket('udp6'); 436 * 437 * socket.bind(1234, () => { 438 * socket.setMulticastInterface('::%2'); 439 * }); 440 * ``` 441 * 442 * #### Example: IPv4 outgoing multicast interface 443 * 444 * All systems use an IP of the host on the desired physical interface: 445 * 446 * ```js 447 * const socket = dgram.createSocket('udp4'); 448 * 449 * socket.bind(1234, () => { 450 * socket.setMulticastInterface('10.0.0.2'); 451 * }); 452 * ``` 453 * @since v8.6.0 454 */ 455 setMulticastInterface(multicastInterface: string): void; 456 /** 457 * Sets or clears the `IP_MULTICAST_LOOP` socket option. When set to `true`, 458 * multicast packets will also be received on the local interface. 459 * 460 * This method throws `EBADF` if called on an unbound socket. 461 * @since v0.3.8 462 */ 463 setMulticastLoopback(flag: boolean): boolean; 464 /** 465 * Sets the `IP_MULTICAST_TTL` socket option. While TTL generally stands for 466 * "Time to Live", in this context it specifies the number of IP hops that a 467 * packet is allowed to travel through, specifically for multicast traffic. Each 468 * router or gateway that forwards a packet decrements the TTL. If the TTL is 469 * decremented to 0 by a router, it will not be forwarded. 470 * 471 * The `ttl` argument may be between 0 and 255\. The default on most systems is `1`. 472 * 473 * This method throws `EBADF` if called on an unbound socket. 474 * @since v0.3.8 475 */ 476 setMulticastTTL(ttl: number): number; 477 /** 478 * Sets the `SO_RCVBUF` socket option. Sets the maximum socket receive buffer 479 * in bytes. 480 * 481 * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. 482 * @since v8.7.0 483 */ 484 setRecvBufferSize(size: number): void; 485 /** 486 * Sets the `SO_SNDBUF` socket option. Sets the maximum socket send buffer 487 * in bytes. 488 * 489 * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. 490 * @since v8.7.0 491 */ 492 setSendBufferSize(size: number): void; 493 /** 494 * Sets the `IP_TTL` socket option. While TTL generally stands for "Time to Live", 495 * in this context it specifies the number of IP hops that a packet is allowed to 496 * travel through. Each router or gateway that forwards a packet decrements the 497 * TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. 498 * Changing TTL values is typically done for network probes or when multicasting. 499 * 500 * The `ttl` argument may be between between 1 and 255\. The default on most systems 501 * is 64. 502 * 503 * This method throws `EBADF` if called on an unbound socket. 504 * @since v0.1.101 505 */ 506 setTTL(ttl: number): number; 507 /** 508 * By default, binding a socket will cause it to block the Node.js process from 509 * exiting as long as the socket is open. The `socket.unref()` method can be used 510 * to exclude the socket from the reference counting that keeps the Node.js 511 * process active, allowing the process to exit even if the socket is still 512 * listening. 513 * 514 * Calling `socket.unref()` multiple times will have no addition effect. 515 * 516 * The `socket.unref()` method returns a reference to the socket so calls can be 517 * chained. 518 * @since v0.9.1 519 */ 520 unref(): this; 521 /** 522 * Tells the kernel to join a source-specific multicast channel at the given`sourceAddress` and `groupAddress`, using the `multicastInterface` with the`IP_ADD_SOURCE_MEMBERSHIP` socket 523 * option. If the `multicastInterface` argument 524 * is not specified, the operating system will choose one interface and will add 525 * membership to it. To add membership to every available interface, call`socket.addSourceSpecificMembership()` multiple times, once per interface. 526 * 527 * When called on an unbound socket, this method will implicitly bind to a random 528 * port, listening on all interfaces. 529 * @since v13.1.0, v12.16.0 530 */ 531 addSourceSpecificMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void; 532 /** 533 * Instructs the kernel to leave a source-specific multicast channel at the given`sourceAddress` and `groupAddress` using the `IP_DROP_SOURCE_MEMBERSHIP`socket option. This method is 534 * automatically called by the kernel when the 535 * socket is closed or the process terminates, so most apps will never have 536 * reason to call this. 537 * 538 * If `multicastInterface` is not specified, the operating system will attempt to 539 * drop membership on all valid interfaces. 540 * @since v13.1.0, v12.16.0 541 */ 542 dropSourceSpecificMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void; 543 /** 544 * events.EventEmitter 545 * 1. close 546 * 2. connect 547 * 3. error 548 * 4. listening 549 * 5. message 550 */ 551 addListener(event: string, listener: (...args: any[]) => void): this; 552 addListener(event: "close", listener: () => void): this; 553 addListener(event: "connect", listener: () => void): this; 554 addListener(event: "error", listener: (err: Error) => void): this; 555 addListener(event: "listening", listener: () => void): this; 556 addListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; 557 emit(event: string | symbol, ...args: any[]): boolean; 558 emit(event: "close"): boolean; 559 emit(event: "connect"): boolean; 560 emit(event: "error", err: Error): boolean; 561 emit(event: "listening"): boolean; 562 emit(event: "message", msg: Buffer, rinfo: RemoteInfo): boolean; 563 on(event: string, listener: (...args: any[]) => void): this; 564 on(event: "close", listener: () => void): this; 565 on(event: "connect", listener: () => void): this; 566 on(event: "error", listener: (err: Error) => void): this; 567 on(event: "listening", listener: () => void): this; 568 on(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; 569 once(event: string, listener: (...args: any[]) => void): this; 570 once(event: "close", listener: () => void): this; 571 once(event: "connect", listener: () => void): this; 572 once(event: "error", listener: (err: Error) => void): this; 573 once(event: "listening", listener: () => void): this; 574 once(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; 575 prependListener(event: string, listener: (...args: any[]) => void): this; 576 prependListener(event: "close", listener: () => void): this; 577 prependListener(event: "connect", listener: () => void): this; 578 prependListener(event: "error", listener: (err: Error) => void): this; 579 prependListener(event: "listening", listener: () => void): this; 580 prependListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; 581 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 582 prependOnceListener(event: "close", listener: () => void): this; 583 prependOnceListener(event: "connect", listener: () => void): this; 584 prependOnceListener(event: "error", listener: (err: Error) => void): this; 585 prependOnceListener(event: "listening", listener: () => void): this; 586 prependOnceListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; 587 } 588 } 589 declare module "node:dgram" { 590 export * from "dgram"; 591 }