| /** |
| * The `dgram` module provides an implementation of UDP datagram sockets. |
| * |
| * ```js |
| * import dgram from 'dgram'; |
| * |
| * const server = dgram.createSocket('udp4'); |
| * |
| * server.on('error', (err) => { |
| * console.log(`server error:\n${err.stack}`); |
| * server.close(); |
| * }); |
| * |
| * server.on('message', (msg, rinfo) => { |
| * console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`); |
| * }); |
| * |
| * server.on('listening', () => { |
| * const address = server.address(); |
| * console.log(`server listening ${address.address}:${address.port}`); |
| * }); |
| * |
| * server.bind(41234); |
| * // Prints: server listening 0.0.0.0:41234 |
| * ``` |
| * @see [source](https://github.com/nodejs/node/blob/v17.0.0/lib/dgram.js) |
| */ |
| declare module 'dgram' { |
| import { AddressInfo } from 'node:net'; |
| import * as dns from 'node:dns'; |
| import { EventEmitter, Abortable } from 'node:events'; |
| interface RemoteInfo { |
| address: string; |
| family: 'IPv4' | 'IPv6'; |
| port: number; |
| size: number; |
| } |
| interface BindOptions { |
| port?: number | undefined; |
| address?: string | undefined; |
| exclusive?: boolean | undefined; |
| fd?: number | undefined; |
| } |
| type SocketType = 'udp4' | 'udp6'; |
| interface SocketOptions extends Abortable { |
| type: SocketType; |
| reuseAddr?: boolean | undefined; |
| /** |
| * @default false |
| */ |
| ipv6Only?: boolean | undefined; |
| recvBufferSize?: number | undefined; |
| sendBufferSize?: number | undefined; |
| lookup?: ((hostname: string, options: dns.LookupOneOptions, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void) => void) | undefined; |
| } |
| /** |
| * Creates a `dgram.Socket` object. Once the socket is created, calling `socket.bind()` will instruct the socket to begin listening for datagram |
| * messages. When `address` and `port` are not passed to `socket.bind()` the |
| * method will bind the socket to the "all interfaces" address on a random port |
| * (it does the right thing for both `udp4` and `udp6` sockets). The bound address |
| * and port can be retrieved using `socket.address().address` and `socket.address().port`. |
| * |
| * If the `signal` option is enabled, calling `.abort()` on the corresponding`AbortController` is similar to calling `.close()` on the socket: |
| * |
| * ```js |
| * const controller = new AbortController(); |
| * const { signal } = controller; |
| * const server = dgram.createSocket({ type: 'udp4', signal }); |
| * server.on('message', (msg, rinfo) => { |
| * console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`); |
| * }); |
| * // Later, when you want to close the server. |
| * controller.abort(); |
| * ``` |
| * @since v0.11.13 |
| * @param options Available options are: |
| * @param callback Attached as a listener for `'message'` events. Optional. |
| */ |
| function createSocket(type: SocketType, callback?: (msg: Buffer, rinfo: RemoteInfo) => void): Socket; |
| function createSocket(options: SocketOptions, callback?: (msg: Buffer, rinfo: RemoteInfo) => void): Socket; |
| /** |
| * Encapsulates the datagram functionality. |
| * |
| * New instances of `dgram.Socket` are created using {@link createSocket}. |
| * The `new` keyword is not to be used to create `dgram.Socket` instances. |
| * @since v0.1.99 |
| */ |
| class Socket extends EventEmitter { |
| /** |
| * 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 |
| * specified, the operating system will choose |
| * one interface and will add membership to it. To add membership to every |
| * available interface, call `addMembership` multiple times, once per interface. |
| * |
| * When called on an unbound socket, this method will implicitly bind to a random |
| * port, listening on all interfaces. |
| * |
| * When sharing a UDP socket across multiple `cluster` workers, the`socket.addMembership()` function must be called only once or an`EADDRINUSE` error will occur: |
| * |
| * ```js |
| * import cluster from 'cluster'; |
| * import dgram from 'dgram'; |
| * |
| * if (cluster.isPrimary) { |
| * cluster.fork(); // Works ok. |
| * cluster.fork(); // Fails with EADDRINUSE. |
| * } else { |
| * const s = dgram.createSocket('udp4'); |
| * s.bind(1234, () => { |
| * s.addMembership('224.0.0.114'); |
| * }); |
| * } |
| * ``` |
| * @since v0.6.9 |
| */ |
| addMembership(multicastAddress: string, multicastInterface?: string): void; |
| /** |
| * Returns an object containing the address information for a socket. |
| * For UDP sockets, this object will contain `address`, `family` and `port`properties. |
| * |
| * This method throws `EBADF` if called on an unbound socket. |
| * @since v0.1.99 |
| */ |
| address(): AddressInfo; |
| /** |
| * For UDP sockets, causes the `dgram.Socket` to listen for datagram |
| * messages on a named `port` and optional `address`. If `port` is not |
| * specified or is `0`, the operating system will attempt to bind to a |
| * random port. If `address` is not specified, the operating system will |
| * attempt to listen on all addresses. Once binding is complete, a`'listening'` event is emitted and the optional `callback` function is |
| * called. |
| * |
| * Specifying both a `'listening'` event listener and passing a`callback` to the `socket.bind()` method is not harmful but not very |
| * useful. |
| * |
| * A bound datagram socket keeps the Node.js process running to receive |
| * datagram messages. |
| * |
| * If binding fails, an `'error'` event is generated. In rare case (e.g. |
| * attempting to bind with a closed socket), an `Error` may be thrown. |
| * |
| * Example of a UDP server listening on port 41234: |
| * |
| * ```js |
| * import dgram from 'dgram'; |
| * |
| * const server = dgram.createSocket('udp4'); |
| * |
| * server.on('error', (err) => { |
| * console.log(`server error:\n${err.stack}`); |
| * server.close(); |
| * }); |
| * |
| * server.on('message', (msg, rinfo) => { |
| * console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`); |
| * }); |
| * |
| * server.on('listening', () => { |
| * const address = server.address(); |
| * console.log(`server listening ${address.address}:${address.port}`); |
| * }); |
| * |
| * server.bind(41234); |
| * // Prints: server listening 0.0.0.0:41234 |
| * ``` |
| * @since v0.1.99 |
| * @param callback with no parameters. Called when binding is complete. |
| */ |
| bind(port?: number, address?: string, callback?: () => void): this; |
| bind(port?: number, callback?: () => void): this; |
| bind(callback?: () => void): this; |
| bind(options: BindOptions, callback?: () => void): this; |
| /** |
| * Close the underlying socket and stop listening for data on it. If a callback is |
| * provided, it is added as a listener for the `'close'` event. |
| * @since v0.1.99 |
| * @param callback Called when the socket has been closed. |
| */ |
| close(callback?: () => void): this; |
| /** |
| * Associates the `dgram.Socket` to a remote address and port. Every |
| * message sent by this handle is automatically sent to that destination. Also, |
| * the socket will only receive messages from that remote peer. |
| * Trying to call `connect()` on an already connected socket will result |
| * in an `ERR_SOCKET_DGRAM_IS_CONNECTED` exception. If `address` is not |
| * provided, `'127.0.0.1'` (for `udp4` sockets) or `'::1'` (for `udp6` sockets) |
| * will be used by default. Once the connection is complete, a `'connect'` event |
| * is emitted and the optional `callback` function is called. In case of failure, |
| * the `callback` is called or, failing this, an `'error'` event is emitted. |
| * @since v12.0.0 |
| * @param callback Called when the connection is completed or on error. |
| */ |
| connect(port: number, address?: string, callback?: () => void): void; |
| connect(port: number, callback: () => void): void; |
| /** |
| * A synchronous function that disassociates a connected `dgram.Socket` from |
| * its remote address. Trying to call `disconnect()` on an unbound or already |
| * disconnected socket will result in an `ERR_SOCKET_DGRAM_NOT_CONNECTED` exception. |
| * @since v12.0.0 |
| */ |
| disconnect(): void; |
| /** |
| * Instructs the kernel to leave a multicast group at `multicastAddress` using the`IP_DROP_MEMBERSHIP` socket option. This method is automatically called by the |
| * kernel when the socket is closed or the process terminates, so most apps will |
| * never have reason to call this. |
| * |
| * If `multicastInterface` is not specified, the operating system will attempt to |
| * drop membership on all valid interfaces. |
| * @since v0.6.9 |
| */ |
| dropMembership(multicastAddress: string, multicastInterface?: string): void; |
| /** |
| * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. |
| * @since v8.7.0 |
| * @return the `SO_RCVBUF` socket receive buffer size in bytes. |
| */ |
| getRecvBufferSize(): number; |
| /** |
| * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. |
| * @since v8.7.0 |
| * @return the `SO_SNDBUF` socket send buffer size in bytes. |
| */ |
| getSendBufferSize(): number; |
| /** |
| * By default, binding a socket will cause it to block the Node.js process from |
| * exiting as long as the socket is open. The `socket.unref()` method can be used |
| * to exclude the socket from the reference counting that keeps the Node.js |
| * process active. The `socket.ref()` method adds the socket back to the reference |
| * counting and restores the default behavior. |
| * |
| * Calling `socket.ref()` multiples times will have no additional effect. |
| * |
| * The `socket.ref()` method returns a reference to the socket so calls can be |
| * chained. |
| * @since v0.9.1 |
| */ |
| ref(): this; |
| /** |
| * Returns an object containing the `address`, `family`, and `port` of the remote |
| * endpoint. This method throws an `ERR_SOCKET_DGRAM_NOT_CONNECTED` exception |
| * if the socket is not connected. |
| * @since v12.0.0 |
| */ |
| remoteAddress(): AddressInfo; |
| /** |
| * Broadcasts a datagram on the socket. |
| * For connectionless sockets, the destination `port` and `address` must be |
| * specified. Connected sockets, on the other hand, will use their associated |
| * remote endpoint, so the `port` and `address` arguments must not be set. |
| * |
| * The `msg` argument contains the message to be sent. |
| * Depending on its type, different behavior can apply. If `msg` is a `Buffer`, |
| * any `TypedArray` or a `DataView`, |
| * the `offset` and `length` specify the offset within the `Buffer` where the |
| * message begins and the number of bytes in the message, respectively. |
| * If `msg` is a `String`, then it is automatically converted to a `Buffer`with `'utf8'` encoding. With messages that |
| * contain multi-byte characters, `offset` and `length` will be calculated with |
| * respect to `byte length` and not the character position. |
| * If `msg` is an array, `offset` and `length` must not be specified. |
| * |
| * The `address` argument is a string. If the value of `address` is a host name, |
| * DNS will be used to resolve the address of the host. If `address` is not |
| * provided or otherwise nullish, `'127.0.0.1'` (for `udp4` sockets) or `'::1'`(for `udp6` sockets) will be used by default. |
| * |
| * If the socket has not been previously bound with a call to `bind`, the socket |
| * is assigned a random port number and is bound to the "all interfaces" address |
| * (`'0.0.0.0'` for `udp4` sockets, `'::0'` for `udp6` sockets.) |
| * |
| * An optional `callback` function may be specified to as a way of reporting |
| * DNS errors or for determining when it is safe to reuse the `buf` object. |
| * DNS lookups delay the time to send for at least one tick of the |
| * Node.js event loop. |
| * |
| * 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 |
| * passed as the first argument to the `callback`. If a `callback` is not given, |
| * the error is emitted as an `'error'` event on the `socket` object. |
| * |
| * Offset and length are optional but both _must_ be set if either are used. |
| * They are supported only when the first argument is a `Buffer`, a `TypedArray`, |
| * or a `DataView`. |
| * |
| * This method throws `ERR_SOCKET_BAD_PORT` if called on an unbound socket. |
| * |
| * Example of sending a UDP packet to a port on `localhost`; |
| * |
| * ```js |
| * import dgram from 'dgram'; |
| * import { Buffer } from 'buffer'; |
| * |
| * const message = Buffer.from('Some bytes'); |
| * const client = dgram.createSocket('udp4'); |
| * client.send(message, 41234, 'localhost', (err) => { |
| * client.close(); |
| * }); |
| * ``` |
| * |
| * Example of sending a UDP packet composed of multiple buffers to a port on`127.0.0.1`; |
| * |
| * ```js |
| * import dgram from 'dgram'; |
| * import { Buffer } from 'buffer'; |
| * |
| * const buf1 = Buffer.from('Some '); |
| * const buf2 = Buffer.from('bytes'); |
| * const client = dgram.createSocket('udp4'); |
| * client.send([buf1, buf2], 41234, (err) => { |
| * client.close(); |
| * }); |
| * ``` |
| * |
| * Sending multiple buffers might be faster or slower depending on the |
| * application and operating system. Run benchmarks to |
| * determine the optimal strategy on a case-by-case basis. Generally speaking, |
| * however, sending multiple buffers is faster. |
| * |
| * Example of sending a UDP packet using a socket connected to a port on`localhost`: |
| * |
| * ```js |
| * import dgram from 'dgram'; |
| * import { Buffer } from 'buffer'; |
| * |
| * const message = Buffer.from('Some bytes'); |
| * const client = dgram.createSocket('udp4'); |
| * client.connect(41234, 'localhost', (err) => { |
| * client.send(message, (err) => { |
| * client.close(); |
| * }); |
| * }); |
| * ``` |
| * @since v0.1.99 |
| * @param msg Message to be sent. |
| * @param offset Offset in the buffer where the message starts. |
| * @param length Number of bytes in the message. |
| * @param port Destination port. |
| * @param address Destination host name or IP address. |
| * @param callback Called when the message has been sent. |
| */ |
| send(msg: string | Uint8Array | ReadonlyArray<any>, port?: number, address?: string, callback?: (error: Error | null, bytes: number) => void): void; |
| send(msg: string | Uint8Array | ReadonlyArray<any>, port?: number, callback?: (error: Error | null, bytes: number) => void): void; |
| send(msg: string | Uint8Array | ReadonlyArray<any>, callback?: (error: Error | null, bytes: number) => void): void; |
| send(msg: string | Uint8Array, offset: number, length: number, port?: number, address?: string, callback?: (error: Error | null, bytes: number) => void): void; |
| send(msg: string | Uint8Array, offset: number, length: number, port?: number, callback?: (error: Error | null, bytes: number) => void): void; |
| send(msg: string | Uint8Array, offset: number, length: number, callback?: (error: Error | null, bytes: number) => void): void; |
| /** |
| * Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP |
| * packets may be sent to a local interface's broadcast address. |
| * |
| * This method throws `EBADF` if called on an unbound socket. |
| * @since v0.6.9 |
| */ |
| setBroadcast(flag: boolean): void; |
| /** |
| * _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 |
| * 4007](https://tools.ietf.org/html/rfc4007). In string form, an IP_ |
| * _with a scope index is written as `'IP%scope'` where scope is an interface name_ |
| * _or interface number._ |
| * |
| * Sets the default outgoing multicast interface of the socket to a chosen |
| * interface or back to system interface selection. The `multicastInterface` must |
| * be a valid string representation of an IP from the socket's family. |
| * |
| * For IPv4 sockets, this should be the IP configured for the desired physical |
| * interface. All packets sent to multicast on the socket will be sent on the |
| * interface determined by the most recent successful use of this call. |
| * |
| * For IPv6 sockets, `multicastInterface` should include a scope to indicate the |
| * interface as in the examples that follow. In IPv6, individual `send` calls can |
| * also use explicit scope in addresses, so only packets sent to a multicast |
| * address without specifying an explicit scope are affected by the most recent |
| * successful use of this call. |
| * |
| * This method throws `EBADF` if called on an unbound socket. |
| * |
| * #### Example: IPv6 outgoing multicast interface |
| * |
| * On most systems, where scope format uses the interface name: |
| * |
| * ```js |
| * const socket = dgram.createSocket('udp6'); |
| * |
| * socket.bind(1234, () => { |
| * socket.setMulticastInterface('::%eth1'); |
| * }); |
| * ``` |
| * |
| * On Windows, where scope format uses an interface number: |
| * |
| * ```js |
| * const socket = dgram.createSocket('udp6'); |
| * |
| * socket.bind(1234, () => { |
| * socket.setMulticastInterface('::%2'); |
| * }); |
| * ``` |
| * |
| * #### Example: IPv4 outgoing multicast interface |
| * |
| * All systems use an IP of the host on the desired physical interface: |
| * |
| * ```js |
| * const socket = dgram.createSocket('udp4'); |
| * |
| * socket.bind(1234, () => { |
| * socket.setMulticastInterface('10.0.0.2'); |
| * }); |
| * ``` |
| * @since v8.6.0 |
| */ |
| setMulticastInterface(multicastInterface: string): void; |
| /** |
| * Sets or clears the `IP_MULTICAST_LOOP` socket option. When set to `true`, |
| * multicast packets will also be received on the local interface. |
| * |
| * This method throws `EBADF` if called on an unbound socket. |
| * @since v0.3.8 |
| */ |
| setMulticastLoopback(flag: boolean): boolean; |
| /** |
| * Sets the `IP_MULTICAST_TTL` socket option. While TTL generally stands for |
| * "Time to Live", in this context it specifies the number of IP hops that a |
| * packet is allowed to travel through, specifically for multicast traffic. Each |
| * router or gateway that forwards a packet decrements the TTL. If the TTL is |
| * decremented to 0 by a router, it will not be forwarded. |
| * |
| * The `ttl` argument may be between 0 and 255\. The default on most systems is `1`. |
| * |
| * This method throws `EBADF` if called on an unbound socket. |
| * @since v0.3.8 |
| */ |
| setMulticastTTL(ttl: number): number; |
| /** |
| * Sets the `SO_RCVBUF` socket option. Sets the maximum socket receive buffer |
| * in bytes. |
| * |
| * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. |
| * @since v8.7.0 |
| */ |
| setRecvBufferSize(size: number): void; |
| /** |
| * Sets the `SO_SNDBUF` socket option. Sets the maximum socket send buffer |
| * in bytes. |
| * |
| * This method throws `ERR_SOCKET_BUFFER_SIZE` if called on an unbound socket. |
| * @since v8.7.0 |
| */ |
| setSendBufferSize(size: number): void; |
| /** |
| * Sets the `IP_TTL` socket option. While TTL generally stands for "Time to Live", |
| * in this context it specifies the number of IP hops that a packet is allowed to |
| * travel through. Each router or gateway that forwards a packet decrements the |
| * TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. |
| * Changing TTL values is typically done for network probes or when multicasting. |
| * |
| * The `ttl` argument may be between between 1 and 255\. The default on most systems |
| * is 64. |
| * |
| * This method throws `EBADF` if called on an unbound socket. |
| * @since v0.1.101 |
| */ |
| setTTL(ttl: number): number; |
| /** |
| * By default, binding a socket will cause it to block the Node.js process from |
| * exiting as long as the socket is open. The `socket.unref()` method can be used |
| * to exclude the socket from the reference counting that keeps the Node.js |
| * process active, allowing the process to exit even if the socket is still |
| * listening. |
| * |
| * Calling `socket.unref()` multiple times will have no addition effect. |
| * |
| * The `socket.unref()` method returns a reference to the socket so calls can be |
| * chained. |
| * @since v0.9.1 |
| */ |
| unref(): this; |
| /** |
| * 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 |
| * option. If the `multicastInterface` argument |
| * is not specified, the operating system will choose one interface and will add |
| * membership to it. To add membership to every available interface, call`socket.addSourceSpecificMembership()` multiple times, once per interface. |
| * |
| * When called on an unbound socket, this method will implicitly bind to a random |
| * port, listening on all interfaces. |
| * @since v13.1.0, v12.16.0 |
| */ |
| addSourceSpecificMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void; |
| /** |
| * 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 |
| * automatically called by the kernel when the |
| * socket is closed or the process terminates, so most apps will never have |
| * reason to call this. |
| * |
| * If `multicastInterface` is not specified, the operating system will attempt to |
| * drop membership on all valid interfaces. |
| * @since v13.1.0, v12.16.0 |
| */ |
| dropSourceSpecificMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void; |
| /** |
| * events.EventEmitter |
| * 1. close |
| * 2. connect |
| * 3. error |
| * 4. listening |
| * 5. message |
| */ |
| addListener(event: string, listener: (...args: any[]) => void): this; |
| addListener(event: 'close', listener: () => void): this; |
| addListener(event: 'connect', listener: () => void): this; |
| addListener(event: 'error', listener: (err: Error) => void): this; |
| addListener(event: 'listening', listener: () => void): this; |
| addListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; |
| emit(event: string | symbol, ...args: any[]): boolean; |
| emit(event: 'close'): boolean; |
| emit(event: 'connect'): boolean; |
| emit(event: 'error', err: Error): boolean; |
| emit(event: 'listening'): boolean; |
| emit(event: 'message', msg: Buffer, rinfo: RemoteInfo): boolean; |
| on(event: string, listener: (...args: any[]) => void): this; |
| on(event: 'close', listener: () => void): this; |
| on(event: 'connect', listener: () => void): this; |
| on(event: 'error', listener: (err: Error) => void): this; |
| on(event: 'listening', listener: () => void): this; |
| on(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; |
| once(event: string, listener: (...args: any[]) => void): this; |
| once(event: 'close', listener: () => void): this; |
| once(event: 'connect', listener: () => void): this; |
| once(event: 'error', listener: (err: Error) => void): this; |
| once(event: 'listening', listener: () => void): this; |
| once(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; |
| prependListener(event: string, listener: (...args: any[]) => void): this; |
| prependListener(event: 'close', listener: () => void): this; |
| prependListener(event: 'connect', listener: () => void): this; |
| prependListener(event: 'error', listener: (err: Error) => void): this; |
| prependListener(event: 'listening', listener: () => void): this; |
| prependListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; |
| prependOnceListener(event: string, listener: (...args: any[]) => void): this; |
| prependOnceListener(event: 'close', listener: () => void): this; |
| prependOnceListener(event: 'connect', listener: () => void): this; |
| prependOnceListener(event: 'error', listener: (err: Error) => void): this; |
| prependOnceListener(event: 'listening', listener: () => void): this; |
| prependOnceListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; |
| } |
| } |
| declare module 'node:dgram' { |
| export * from 'dgram'; |
| } |