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