Socket UDP/datagram

[Stabile: 2 - Stabile]

Codice sorgente: lib/dgram.js

Il modulo node:dgram fornisce un'implementazione dei socket datagram UDP.

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`errore del server:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`il server ha ricevuto: ${msg} da ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server in ascolto ${address.address}:${address.port}`)
})

server.bind(41234)
// Stampa: server in ascolto 0.0.0.0:41234

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`errore del server:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`il server ha ricevuto: ${msg} da ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server in ascolto ${address.address}:${address.port}`)
})

server.bind(41234)
// Stampa: server in ascolto 0.0.0.0:41234

Classe: `dgram.Socket`

Aggiunto in: v0.1.99

Estende: <EventEmitter>

Incapsula la funzionalità datagram.

Nuove istanze di dgram.Socket vengono create utilizzando dgram.createSocket(). La parola chiave new non deve essere utilizzata per creare istanze dgram.Socket.

Evento: `'close'`

Aggiunto in: v0.1.99

L'evento 'close' viene emesso dopo che un socket viene chiuso con close(). Una volta attivato, nessun nuovo evento 'message' verrà emesso su questo socket.

Evento: `'connect'`

Aggiunto in: v12.0.0

L'evento 'connect' viene emesso dopo che un socket è stato associato a un indirizzo remoto a seguito di una chiamata connect() riuscita.

Evento: `'error'`

Aggiunto in: v0.1.99

exception <Error>

L'evento 'error' viene emesso ogni volta che si verifica un errore. La funzione di gestione dell'evento riceve un singolo oggetto Error.

Evento: `'listening'`

Aggiunto in: v0.1.99

L'evento 'listening' viene emesso una volta che dgram.Socket è indirizzabile e può ricevere dati. Ciò avviene esplicitamente con socket.bind() o implicitamente la prima volta che i dati vengono inviati utilizzando socket.send(). Fino a quando dgram.Socket non è in ascolto, le risorse di sistema sottostanti non esistono e chiamate come socket.address() e socket.setTTL() falliranno.

Evento: `'message'`

[Storia]

Versione	Modifiche
v18.4.0	La proprietà `family` ora restituisce una stringa anziché un numero.
v18.0.0	La proprietà `family` ora restituisce un numero anziché una stringa.
v0.1.99	Aggiunto in: v0.1.99

L'evento 'message' viene emesso quando un nuovo datagramma è disponibile su un socket. La funzione di gestione dell'evento riceve due argomenti: msg e rinfo.

msg <Buffer> Il messaggio.
rinfo <Object> Informazioni sull'indirizzo remoto.
- address <string> L'indirizzo del mittente.
- family <string> La famiglia di indirizzi ('IPv4' o 'IPv6').
- port <number> La porta del mittente.
- size <number> La dimensione del messaggio.

Se l'indirizzo di origine del pacchetto in entrata è un indirizzo IPv6 link-local, il nome dell'interfaccia viene aggiunto all'address. Ad esempio, un pacchetto ricevuto sull'interfaccia en0 potrebbe avere il campo indirizzo impostato su 'fe80::2618:1234:ab11:3b9c%en0', dove '%en0' è il nome dell'interfaccia come suffisso dell'ID di zona.

`socket.addMembership(multicastAddress[, multicastInterface])`

Aggiunto in: v0.6.9

multicastAddress <stringa>
multicastInterface <stringa>

Indica al kernel di unirsi a un gruppo multicast all'indirizzo multicastAddress e all'interfaccia multicastInterface specificati utilizzando l'opzione socket IP_ADD_MEMBERSHIP. Se l'argomento multicastInterface non è specificato, il sistema operativo sceglierà un'interfaccia e vi aggiungerà l'appartenenza. Per aggiungere l'appartenenza a ogni interfaccia disponibile, chiama addMembership più volte, una volta per interfaccia.

Quando viene chiamato su un socket non associato, questo metodo si associa implicitamente a una porta casuale, in ascolto su tutte le interfacce.

Quando si condivide un socket UDP tra più worker di cluster, la funzione socket.addMembership() deve essere chiamata una sola volta, altrimenti si verificherà un errore EADDRINUSE:

ESMCJS

import cluster from 'node:cluster'
import dgram from 'node:dgram'

if (cluster.isPrimary) {
  cluster.fork() // Funziona correttamente.
  cluster.fork() // Fallisce con EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

const cluster = require('node:cluster')
const dgram = require('node:dgram')

if (cluster.isPrimary) {
  cluster.fork() // Funziona correttamente.
  cluster.fork() // Fallisce con EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

`socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

Aggiunto in: v13.1.0, v12.16.0

sourceAddress <stringa>
groupAddress <stringa>
multicastInterface <stringa>

Indica al kernel di unirsi a un canale multicast specifico per l'origine all'indirizzo sourceAddress e all'indirizzo groupAddress specificati, utilizzando l'interfaccia multicastInterface con l'opzione socket IP_ADD_SOURCE_MEMBERSHIP. Se l'argomento multicastInterface non è specificato, il sistema operativo sceglierà un'interfaccia e vi aggiungerà l'appartenenza. Per aggiungere l'appartenenza a ogni interfaccia disponibile, chiama socket.addSourceSpecificMembership() più volte, una volta per interfaccia.

Quando viene chiamato su un socket non associato, questo metodo si associa implicitamente a una porta casuale, in ascolto su tutte le interfacce.

`socket.address()`

Aggiunto in: v0.1.99

Restituisce: <Object>

Restituisce un oggetto contenente le informazioni sull'indirizzo di un socket. Per i socket UDP, questo oggetto conterrà le proprietà address, family e port.

Questo metodo genera EBADF se chiamato su un socket non associato.

`socket.bind([port][, address][, callback])`

[Cronologia]

Versione	Cambiamenti
v0.9.1	Il metodo è stato modificato in un modello di esecuzione asincrono. Il codice legacy dovrebbe essere modificato per passare una funzione di callback alla chiamata del metodo.
v0.1.99	Aggiunto in: v0.1.99

port <integer>
address <string>
callback <Function> senza parametri. Chiamata al termine del binding.

Per i socket UDP, fa sì che dgram.Socket ascolti i messaggi datagram sul port specificato e sull'eventuale address specificato. Se port non è specificato o è 0, il sistema operativo tenterà di eseguire il binding a una porta casuale. Se address non è specificato, il sistema operativo tenterà di ascoltare su tutti gli indirizzi. Una volta completato il binding, viene emesso un evento 'listening' e viene chiamata la funzione callback facoltativa.

Specificare sia un listener di eventi 'listening' sia passare un callback al metodo socket.bind() non è dannoso ma non molto utile.

Un socket datagram associato mantiene in esecuzione il processo Node.js per ricevere messaggi datagram.

Se il binding fallisce, viene generato un evento 'error'. In rari casi (ad esempio, quando si tenta di eseguire il binding con un socket chiuso), potrebbe essere generato un Error.

Esempio di un server UDP in ascolto sulla porta 41234:

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`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

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`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

`socket.bind(options[, callback])`

Aggiunto in: v0.11.14

options <Object> Richiesto. Supporta le seguenti proprietà:
- port <integer>
- address <string>
- exclusive <boolean>
- fd <integer>
callback <Function>

Per i socket UDP, fa sì che il dgram.Socket ascolti i messaggi datagram su una port specificata e un address opzionale che vengono passati come proprietà di un oggetto options passato come primo argomento. Se port non è specificato o è 0, il sistema operativo tenterà di eseguire il binding a una porta casuale. Se address non è specificato, il sistema operativo tenterà di ascoltare su tutti gli indirizzi. Una volta completato il binding, viene emesso un evento 'listening' e viene chiamata la funzione callback opzionale.

L'oggetto options può contenere una proprietà fd. Quando viene impostato un fd maggiore di 0, esso verrà avvolto intorno a un socket esistente con il descrittore di file fornito. In questo caso, le proprietà di port e address verranno ignorate.

Specificare sia un listener per l'evento 'listening' sia passare una callback al metodo socket.bind() non è dannoso ma non molto utile.

L'oggetto options può contenere una proprietà aggiuntiva exclusive che viene utilizzata quando si utilizzano oggetti dgram.Socket con il modulo cluster. Quando exclusive è impostato su false (predefinito), i worker del cluster utilizzeranno lo stesso handle del socket sottostante, consentendo la condivisione delle attività di gestione delle connessioni. Quando exclusive è true, tuttavia, l'handle non viene condiviso e il tentativo di condivisione della porta genera un errore. La creazione di un dgram.Socket con l'opzione reusePort impostata su true fa sì che exclusive sia sempre true quando viene chiamato socket.bind().

Un socket datagram vincolato mantiene in esecuzione il processo Node.js per ricevere i messaggi datagram.

Se il binding non riesce, viene generato un evento 'error'. In rari casi (ad esempio, tentativo di eseguire il binding con un socket chiuso), potrebbe essere generato un Error.

Di seguito è mostrato un esempio di socket in ascolto su una porta esclusiva.

socket.bind({
  address: 'localhost',
  port: 8000,
  exclusive: true,
})

`socket.close([callback])`

Aggiunto in: v0.1.99

callback <Function> Chiamata quando il socket è stato chiuso.

Chiude il socket sottostante e interrompe l'ascolto dei dati su di esso. Se viene fornito un callback, viene aggiunto come listener per l'evento 'close'.

`socket[Symbol.asyncDispose]()`

Aggiunto in: v20.5.0, v18.18.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Chiama socket.close() e restituisce una promise che si risolve quando il socket è stato chiuso.

`socket.connect(port[, address][, callback])`

Aggiunto in: v12.0.0

port <integer>
address <string>
callback <Function> Chiamata quando la connessione è completata o in caso di errore.

Associa il dgram.Socket a un indirizzo e una porta remoti. Ogni messaggio inviato da questo handle viene automaticamente inviato a tale destinazione. Inoltre, il socket riceverà solo messaggi da quel peer remoto. Il tentativo di chiamare connect() su un socket già connesso comporterà un'eccezione ERR_SOCKET_DGRAM_IS_CONNECTED. Se address non viene fornito, verrà utilizzato '127.0.0.1' (per i socket udp4) o '::1' (per i socket udp6) per impostazione predefinita. Una volta completata la connessione, viene emesso un evento 'connect' e viene chiamata la funzione callback opzionale. In caso di errore, viene chiamato il callback o, in mancanza di questo, viene emesso un evento 'error'.

`socket.disconnect()`

Aggiunto in: v12.0.0

Una funzione sincrona che dissocia un dgram.Socket connesso dal suo indirizzo remoto. Il tentativo di chiamare disconnect() su un socket non associato o già disconnesso comporterà un'eccezione ERR_SOCKET_DGRAM_NOT_CONNECTED.

`socket.dropMembership(multicastAddress[, multicastInterface])`

Aggiunto in: v0.6.9

multicastAddress <stringa>
multicastInterface <stringa>

Istruisce il kernel ad abbandonare un gruppo multicast all'indirizzo multicastAddress utilizzando l'opzione socket IP_DROP_MEMBERSHIP. Questo metodo viene chiamato automaticamente dal kernel quando il socket viene chiuso o il processo termina, quindi la maggior parte delle app non avrà mai motivo di chiamarlo.

Se multicastInterface non è specificato, il sistema operativo tenterà di abbandonare l'appartenenza a tutte le interfacce valide.

`socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

Aggiunto in: v13.1.0, v12.16.0

sourceAddress <stringa>
groupAddress <stringa>
multicastInterface <stringa>

Istruisce il kernel ad abbandonare un canale multicast specifico della sorgente all'indirizzo sourceAddress e groupAddress dati utilizzando l'opzione socket IP_DROP_SOURCE_MEMBERSHIP. Questo metodo viene chiamato automaticamente dal kernel quando il socket viene chiuso o il processo termina, quindi la maggior parte delle app non avrà mai motivo di chiamarlo.

Se multicastInterface non è specificato, il sistema operativo tenterà di abbandonare l'appartenenza a tutte le interfacce valide.

`socket.getRecvBufferSize()`

Aggiunto in: v8.7.0

Restituisce: <numero> la dimensione del buffer di ricezione del socket SO_RCVBUF in byte.

Questo metodo genera ERR_SOCKET_BUFFER_SIZE se chiamato su un socket non associato.

`socket.getSendBufferSize()`

Aggiunto in: v8.7.0

Restituisce: <numero> la dimensione del buffer di invio del socket SO_SNDBUF in byte.

Questo metodo genera ERR_SOCKET_BUFFER_SIZE se chiamato su un socket non associato.

`socket.getSendQueueSize()`

Aggiunto in: v18.8.0, v16.19.0

Restituisce: <number> Numero di byte in coda per l'invio.

`socket.getSendQueueCount()`

Aggiunto in: v18.8.0, v16.19.0

Restituisce: <number> Numero di richieste di invio attualmente in coda in attesa di essere elaborate.

`socket.ref()`

Aggiunto in: v0.9.1

Restituisce: <dgram.Socket>

Per impostazione predefinita, l'associazione di un socket farà sì che impedisca al processo Node.js di uscire finché il socket è aperto. Il metodo socket.unref() può essere utilizzato per escludere il socket dal conteggio dei riferimenti che mantiene attivo il processo Node.js. Il metodo socket.ref() aggiunge nuovamente il socket al conteggio dei riferimenti e ripristina il comportamento predefinito.

La chiamata di socket.ref() più volte non avrà alcun effetto aggiuntivo.

Il metodo socket.ref() restituisce un riferimento al socket in modo che le chiamate possano essere concatenate.

`socket.remoteAddress()`

Aggiunto in: v12.0.0

Restituisce: <Object>

Restituisce un oggetto contenente l'indirizzo, la famiglia e la porta dell'endpoint remoto. Questo metodo genera un'eccezione ERR_SOCKET_DGRAM_NOT_CONNECTED se il socket non è connesso.

`socket.send(msg[, offset, length][, port][, address][, callback])`

[Cronologia]

Versione	Cambiamenti
v17.0.0	Il parametro `address` ora accetta solo una `string`, `null` o `undefined`.
v14.5.0, v12.19.0	Il parametro `msg` ora può essere qualsiasi `TypedArray` o `DataView`.
v12.0.0	Aggiunto il supporto per l'invio di dati su socket connessi.
v8.0.0	Il parametro `msg` ora può essere un `Uint8Array`.
v8.0.0	Il parametro `address` ora è sempre facoltativo.
v6.0.0	In caso di successo, `callback` verrà ora chiamato con un argomento `error` di `null` anziché `0`.
v5.7.0	Il parametro `msg` ora può essere un array. Inoltre, i parametri `offset` e `length` ora sono facoltativi.
v0.1.99	Aggiunto in: v0.1.99

msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> Messaggio da inviare.
offset <integer> Offset nel buffer in cui inizia il messaggio.
length <integer> Numero di byte nel messaggio.
port <integer> Porta di destinazione.
address <string> Nome host o indirizzo IP di destinazione.
callback <Function> Chiamato quando il messaggio è stato inviato.

Trasmette un datagramma sul socket. Per i socket senza connessione, è necessario specificare la porta e l'indirizzo di destinazione. I socket connessi, d'altra parte, utilizzeranno il loro endpoint remoto associato, quindi gli argomenti port e address non devono essere impostati.

L'argomento msg contiene il messaggio da inviare. A seconda del suo tipo, è possibile applicare un comportamento diverso. Se msg è un Buffer, qualsiasi TypedArray o un DataView, l'offset e la length specificano l'offset all'interno del Buffer in cui inizia il messaggio e il numero di byte nel messaggio, rispettivamente. Se msg è una String, viene automaticamente convertito in un Buffer con la codifica 'utf8'. Con i messaggi che contengono caratteri multi-byte, offset e length verranno calcolati rispetto alla lunghezza in byte e non alla posizione del carattere. Se msg è un array, offset e length non devono essere specificati.

L'argomento address è una stringa. Se il valore di address è un nome host, verrà utilizzato il DNS per risolvere l'indirizzo dell'host. Se address non viene fornito o è altrimenti nullo, verrà utilizzato per impostazione predefinita '127.0.0.1' (per i socket udp4) o '::1' (per i socket udp6).

Se il socket non è stato precedentemente collegato con una chiamata a bind, al socket viene assegnato un numero di porta casuale ed è associato all'indirizzo "tutte le interfacce" ('0.0.0.0' per i socket udp4, '::0' per i socket udp6).

Una funzione callback opzionale può essere specificata come modo per segnalare errori DNS o per determinare quando è sicuro riutilizzare l'oggetto buf. Le ricerche DNS ritardano il tempo di invio per almeno un tick del ciclo di eventi Node.js.

L'unico modo per essere sicuri che il datagramma sia stato inviato è utilizzare una callback. Se si verifica un errore e viene fornita una callback, l'errore verrà passato come primo argomento alla callback. Se non viene fornita una callback, l'errore viene emesso come evento 'error' sull'oggetto socket.

L'offset e la lunghezza sono facoltativi, ma entrambi devono essere impostati se ne viene utilizzato uno. Sono supportati solo quando il primo argomento è un Buffer, un TypedArray o un DataView.

Questo metodo genera ERR_SOCKET_BAD_PORT se chiamato su un socket non collegato.

Esempio di invio di un pacchetto UDP a una porta su localhost;

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

Esempio di invio di un pacchetto UDP composto da più buffer a una porta su 127.0.0.1;

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

L'invio di più buffer potrebbe essere più veloce o più lento a seconda dell'applicazione e del sistema operativo. Esegui dei benchmark per determinare la strategia ottimale caso per caso. In generale, tuttavia, l'invio di più buffer è più veloce.

Esempio di invio di un pacchetto UDP utilizzando un socket connesso a una porta su localhost:

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

Nota sulla dimensione dei datagrammi UDP

La dimensione massima di un datagramma IPv4/v6 dipende dalla MTU (Maximum Transmission Unit) e dalla dimensione del campo Payload Length.

Il campo Payload Length è largo 16 bit, il che significa che un payload normale non può superare i 64K ottetti inclusi l'intestazione internet e i dati (65.507 byte = 65.535 - 8 byte di intestazione UDP - 20 byte di intestazione IP); questo è generalmente vero per le interfacce di loopback, ma tali messaggi datagrammi lunghi sono impraticabili per la maggior parte degli host e delle reti.
La MTU è la dimensione massima che una data tecnologia del livello di collegamento può supportare per i messaggi datagrammi. Per qualsiasi collegamento, IPv4 impone una MTU minima di 68 ottetti, mentre la MTU raccomandata per IPv4 è 576 (tipicamente raccomandata come MTU per applicazioni di tipo dial-up), sia che arrivino interi o in frammenti. Per IPv6, la MTU minima è di 1280 ottetti. Tuttavia, la dimensione minima obbligatoria del buffer di riassemblaggio dei frammenti è di 1500 ottetti. Il valore di 68 ottetti è molto piccolo, poiché la maggior parte delle tecnologie attuali del livello di collegamento, come Ethernet, hanno una MTU minima di 1500.

È impossibile conoscere in anticipo la MTU di ogni collegamento attraverso il quale un pacchetto potrebbe viaggiare. L'invio di un datagramma maggiore della MTU del ricevitore non funzionerà perché il pacchetto verrà eliminato silenziosamente senza informare la sorgente che i dati non hanno raggiunto il destinatario previsto.

`socket.setBroadcast(flag)`

Aggiunto in: v0.6.9

flag <boolean>

Imposta o cancella l'opzione socket SO_BROADCAST. Quando impostato su true, i pacchetti UDP possono essere inviati all'indirizzo di broadcast di un'interfaccia locale.

Questo metodo genera EBADF se chiamato su un socket non associato.

`socket.setMulticastInterface(multicastInterface)`

Aggiunto in: v8.6.0

multicastInterface <string>

Tutti i riferimenti allo scope in questa sezione si riferiscono a Indici di zona IPv6, che sono definiti da RFC 4007. In forma di stringa, un IP con un indice di scope è scritto come 'IP%scope' dove scope è un nome di interfaccia o un numero di interfaccia.

Imposta l'interfaccia multicast in uscita predefinita del socket su un'interfaccia scelta o torna alla selezione dell'interfaccia di sistema. multicastInterface deve essere una rappresentazione di stringa valida di un IP dalla famiglia del socket.

Per i socket IPv4, questo dovrebbe essere l'IP configurato per l'interfaccia fisica desiderata. Tutti i pacchetti inviati al multicast sul socket verranno inviati sull'interfaccia determinata dall'uso di successo più recente di questa chiamata.

Per i socket IPv6, multicastInterface dovrebbe includere uno scope per indicare l'interfaccia come negli esempi che seguono. In IPv6, le singole chiamate send possono anche utilizzare scope espliciti negli indirizzi, quindi solo i pacchetti inviati a un indirizzo multicast senza specificare uno scope esplicito sono influenzati dall'uso di successo più recente di questa chiamata.

Questo metodo genera EBADF se chiamato su un socket non associato.

Esempio: Interfaccia multicast in uscita IPv6

Sulla maggior parte dei sistemi, dove il formato dello scope utilizza il nome dell'interfaccia:

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%eth1')
})

Su Windows, dove il formato dello scope utilizza un numero di interfaccia:

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%2')
})

Esempio: Interfaccia multicast in uscita IPv4

Tutti i sistemi utilizzano un IP dell'host sull'interfaccia fisica desiderata:

const socket = dgram.createSocket('udp4')

socket.bind(1234, () => {
  socket.setMulticastInterface('10.0.0.2')
})

Risultati della chiamata

Una chiamata su un socket non pronto per l'invio o non più aperto potrebbe generare un errore Non in esecuzione Error.

Se multicastInterface non può essere analizzato in un indirizzo IP, viene generato un System Error EINVAL.

Su IPv4, se multicastInterface è un indirizzo valido ma non corrisponde a nessuna interfaccia, o se l'indirizzo non corrisponde alla famiglia, viene generato un System Error come EADDRNOTAVAIL o EPROTONOSUP.

Su IPv6, la maggior parte degli errori con la specifica o l'omissione dello scope faranno sì che il socket continui a utilizzare (o ritorni a) la selezione predefinita dell'interfaccia del sistema.

L'indirizzo ANY della famiglia di indirizzi di un socket (IPv4 '0.0.0.0' o IPv6 '::') può essere utilizzato per restituire il controllo dell'interfaccia predefinita in uscita dei socket al sistema per i futuri pacchetti multicast.

`socket.setMulticastLoopback(flag)`

Aggiunto in: v0.3.8

flag <boolean>

Imposta o cancella l'opzione socket IP_MULTICAST_LOOP. Quando impostato su true, i pacchetti multicast verranno ricevuti anche sull'interfaccia locale.

Questo metodo genera EBADF se chiamato su un socket non associato.

`socket.setMulticastTTL(ttl)`

Aggiunto in: v0.3.8

ttl <integer>

Imposta l'opzione socket IP_MULTICAST_TTL. Mentre TTL generalmente sta per "Time to Live" (Tempo di vita), in questo contesto specifica il numero di hop IP che un pacchetto è autorizzato ad attraversare, specificamente per il traffico multicast. Ogni router o gateway che inoltra un pacchetto decrementa il TTL. Se il TTL viene decrementato a 0 da un router, non verrà inoltrato.

L'argomento ttl può essere compreso tra 0 e 255. Il valore predefinito sulla maggior parte dei sistemi è 1.

Questo metodo genera EBADF se chiamato su un socket non associato.

`socket.setRecvBufferSize(size)`

Aggiunto in: v8.7.0

size <integer>

Imposta l'opzione socket SO_RCVBUF. Imposta la dimensione massima in byte del buffer di ricezione del socket.

Questo metodo genera ERR_SOCKET_BUFFER_SIZE se chiamato su un socket non associato.

`socket.setSendBufferSize(size)`

Aggiunto in: v8.7.0

size <integer>

Imposta l'opzione socket SO_SNDBUF. Imposta la dimensione massima in byte del buffer di invio del socket.

Questo metodo genera ERR_SOCKET_BUFFER_SIZE se chiamato su un socket non associato.

`socket.setTTL(ttl)`

Aggiunto in: v0.1.101

ttl <integer>

Imposta l'opzione socket IP_TTL. Mentre TTL generalmente sta per "Time to Live", in questo contesto specifica il numero di hop IP che un pacchetto è autorizzato a attraversare. Ogni router o gateway che inoltra un pacchetto decrementa il TTL. Se il TTL viene decrementato a 0 da un router, non verrà inoltrato. La modifica dei valori TTL viene generalmente eseguita per i test di rete o quando si utilizza il multicast.

L'argomento ttl può essere compreso tra 1 e 255. Il valore predefinito sulla maggior parte dei sistemi è 64.

Questo metodo genera EBADF se chiamato su un socket non associato.

`socket.unref()`

Aggiunto in: v0.9.1

Restituisce: <dgram.Socket>

Per impostazione predefinita, l'associazione di un socket farà sì che il processo Node.js si blocchi dall'uscita finché il socket è aperto. Il metodo socket.unref() può essere utilizzato per escludere il socket dal conteggio dei riferimenti che mantiene attivo il processo Node.js, consentendo al processo di uscire anche se il socket è ancora in ascolto.

Chiamare socket.unref() più volte non avrà alcun effetto aggiuntivo.

Il metodo socket.unref() restituisce un riferimento al socket in modo che le chiamate possano essere concatenate.

Funzioni del modulo `node:dgram`

`dgram.createSocket(options[, callback])`

[Cronologia]

Versione	Modifiche
v23.1.0	L'opzione `reusePort` è supportata.
v15.8.0	È stato aggiunto il supporto per AbortSignal.
v11.4.0	L'opzione `ipv6Only` è supportata.
v8.7.0	Le opzioni `recvBufferSize` e `sendBufferSize` sono ora supportate.
v8.6.0	L'opzione `lookup` è supportata.
v0.11.13	Aggiunto in: v0.11.13

options <Object> Le opzioni disponibili sono:
- type <string> La famiglia del socket. Deve essere 'udp4' o 'udp6'. Obbligatorio.
- reuseAddr <boolean> Quando true, socket.bind() riutilizzerà l'indirizzo, anche se un altro processo ha già collegato un socket su di esso, ma solo un socket può ricevere i dati. Predefinito: false.
- reusePort <boolean> Quando true, socket.bind() riutilizzerà la porta, anche se un altro processo ha già collegato un socket su di essa. I datagrammi in entrata vengono distribuiti ai socket in ascolto. L'opzione è disponibile solo su alcune piattaforme, come Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4 e AIX 7.2.5+. Su piattaforme non supportate, questa opzione genera un errore quando il socket è collegato. Predefinito: false.
- ipv6Only <boolean> Impostando ipv6Only su true si disabiliterà il supporto dual-stack, ovvero il binding all'indirizzo :: non farà sì che 0.0.0.0 venga collegato. Predefinito: false.
- recvBufferSize <number> Imposta il valore del socket SO_RCVBUF.
- sendBufferSize <number> Imposta il valore del socket SO_SNDBUF.
- lookup <Function> Funzione di ricerca personalizzata. Predefinito: dns.lookup().
- signal <AbortSignal> Un AbortSignal che può essere utilizzato per chiudere un socket.
- receiveBlockList <net.BlockList> receiveBlockList può essere utilizzato per scartare i datagrammi in entrata verso indirizzi IP, intervalli IP o sottoreti IP specifici. Questo non funziona se il server è dietro un proxy inverso, NAT, ecc. perché l'indirizzo verificato rispetto alla blocklist è l'indirizzo del proxy o quello specificato dal NAT.
- sendBlockList <net.BlockList> sendBlockList può essere utilizzato per disabilitare l'accesso in uscita a indirizzi IP, intervalli IP o sottoreti IP specifici.
callback <Function> Collegata come listener per eventi 'message'. Opzionale.
Restituisce: <dgram.Socket>

Crea un oggetto dgram.Socket. Una volta creato il socket, chiamando socket.bind() si istruirà il socket a iniziare ad ascoltare i messaggi datagramma. Quando address e port non vengono passati a socket.bind() il metodo collegherà il socket all'indirizzo "tutte le interfacce" su una porta casuale (fa la cosa giusta sia per i socket udp4 che udp6). L'indirizzo e la porta collegati possono essere recuperati utilizzando socket.address().address e socket.address().port.

Se l'opzione signal è abilitata, chiamare .abort() sul corrispondente AbortController è simile a chiamare .close() sul socket:

const controller = new AbortController()
const { signal } = controller
const server = dgram.createSocket({ type: 'udp4', signal })
server.on('message', (msg, rinfo) => {
  console.log(`server ha ricevuto: ${msg} da ${rinfo.address}:${rinfo.port}`)
})
// Più tardi, quando vuoi chiudere il server.
controller.abort()

`dgram.createSocket(type[, callback])`

Aggiunto in: v0.1.99

type <stringa> O 'udp4' o 'udp6'.
callback <Funzione> Collegata come listener agli eventi 'message'.
Restituisce: <dgram.Socket>

Crea un oggetto dgram.Socket del type specificato.

Una volta creato il socket, chiamare socket.bind() istruirà il socket ad iniziare l'ascolto di messaggi datagramma. Quando address e port non vengono passati a socket.bind() il metodo collegherà il socket all'indirizzo "tutte le interfacce" su una porta casuale (fa la cosa giusta sia per i socket udp4 che udp6). L'indirizzo e la porta collegati possono essere recuperati usando socket.address().address e socket.address().port.

Socket UDP/datagram ​

Classe: dgram.Socket ​

Evento: 'close' ​

Evento: 'connect' ​

Evento: 'error' ​

Evento: 'listening' ​

Evento: 'message' ​

socket.addMembership(multicastAddress[, multicastInterface]) ​

socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface]) ​

socket.address() ​

socket.bind([port][, address][, callback]) ​

socket.bind(options[, callback]) ​

socket.close([callback]) ​

socket[Symbol.asyncDispose]() ​

socket.connect(port[, address][, callback]) ​

socket.disconnect() ​

socket.dropMembership(multicastAddress[, multicastInterface]) ​

socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface]) ​

socket.getRecvBufferSize() ​

socket.getSendBufferSize() ​

socket.getSendQueueSize() ​

socket.getSendQueueCount() ​

socket.ref() ​

socket.remoteAddress() ​

socket.send(msg[, offset, length][, port][, address][, callback]) ​

Nota sulla dimensione dei datagrammi UDP ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

Esempio: Interfaccia multicast in uscita IPv6 ​

Esempio: Interfaccia multicast in uscita IPv4 ​

Risultati della chiamata ​

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

Funzioni del modulo node:dgram ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

Socket UDP/datagram

Classe: `dgram.Socket`

Evento: `'close'`

Evento: `'connect'`

Evento: `'error'`

Evento: `'listening'`

Evento: `'message'`

`socket.addMembership(multicastAddress[, multicastInterface])`

`socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

`socket.address()`

`socket.bind([port][, address][, callback])`

`socket.bind(options[, callback])`

`socket.close([callback])`

`socket[Symbol.asyncDispose]()`

`socket.connect(port[, address][, callback])`

`socket.disconnect()`

`socket.dropMembership(multicastAddress[, multicastInterface])`

`socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

`socket.getRecvBufferSize()`

`socket.getSendBufferSize()`

`socket.getSendQueueSize()`

`socket.getSendQueueCount()`

`socket.ref()`

`socket.remoteAddress()`

`socket.send(msg[, offset, length][, port][, address][, callback])`

Nota sulla dimensione dei datagrammi UDP

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

Esempio: Interfaccia multicast in uscita IPv6

Esempio: Interfaccia multicast in uscita IPv4

Risultati della chiamata

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

Funzioni del modulo `node:dgram`

`dgram.createSocket(options[, callback])`

`dgram.createSocket(type[, callback])`