Sockets UDP/datagramme

[Stable: 2 - Stable]

Code source : lib/dgram.js

Le module node:dgram fournit une implémentation des sockets de datagrammes UDP.

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

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

server.on('message', (msg, rinfo) => {
  console.log(`le serveur a reçu : ${msg} de ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`le serveur écoute ${address.address}:${address.port}`)
})

server.bind(41234)
// Affiche : le serveur écoute 0.0.0.0:41234

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

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

server.on('message', (msg, rinfo) => {
  console.log(`le serveur a reçu : ${msg} de ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`le serveur écoute ${address.address}:${address.port}`)
})

server.bind(41234)
// Affiche : le serveur écoute 0.0.0.0:41234

Classe : `dgram.Socket`

Ajoutée dans : v0.1.99

Hérite de : <EventEmitter>

Encapsule la fonctionnalité des datagrammes.

De nouvelles instances de dgram.Socket sont créées à l'aide de dgram.createSocket(). Le mot-clé new ne doit pas être utilisé pour créer des instances dgram.Socket.

Événement : `'close'`

Ajouté dans : v0.1.99

L'événement 'close' est émis après qu'un socket a été fermé avec close(). Une fois déclenché, aucun nouvel événement 'message' ne sera émis sur ce socket.

Événement : `'connect'`

Ajouté dans : v12.0.0

L'événement 'connect' est émis après qu'un socket est associé à une adresse distante suite à un appel réussi à connect().

Événement : `'error'`

Ajouté dans : v0.1.99

exception <Error>

L’événement 'error' est émis chaque fois qu’une erreur se produit. La fonction du gestionnaire d’événements reçoit un seul objet Error.

Événement : `'listening'`

Ajouté dans : v0.1.99

L’événement 'listening' est émis une fois que le dgram.Socket est adressable et peut recevoir des données. Cela se produit explicitement avec socket.bind() ou implicitement la première fois que des données sont envoyées à l’aide de socket.send(). Tant que le dgram.Socket n’est pas à l’écoute, les ressources système sous-jacentes n’existent pas et les appels tels que socket.address() et socket.setTTL() échoueront.

Événement : `'message'`

[Historique]

Version	Changements
v18.4.0	La propriété `family` renvoie maintenant une chaîne au lieu d’un nombre.
v18.0.0	La propriété `family` renvoie maintenant un nombre au lieu d’une chaîne.
v0.1.99	Ajouté dans : v0.1.99

L’événement 'message' est émis lorsqu’un nouveau datagramme est disponible sur un socket. La fonction du gestionnaire d’événements reçoit deux arguments : msg et rinfo.

msg <Buffer> Le message.
rinfo <Object> Informations sur l’adresse distante.
- address <string> L’adresse de l’expéditeur.
- family <string> La famille d’adresses ('IPv4' ou 'IPv6').
- port <number> Le port de l’expéditeur.
- size <number> La taille du message.

Si l’adresse source du paquet entrant est une adresse locale de liaison IPv6, le nom de l’interface est ajouté à l’address. Par exemple, un paquet reçu sur l’interface en0 peut avoir le champ d’adresse défini sur 'fe80::2618:1234:ab11:3b9c%en0', où '%en0' est le nom de l’interface en tant que suffixe d’ID de zone.

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

Ajouté dans : v0.6.9

multicastAddress <string>
multicastInterface <string>

Indique au noyau de rejoindre un groupe multicast à l'adresse multicastAddress et à l'interface multicastInterface données en utilisant l'option de socket IP_ADD_MEMBERSHIP. Si l'argument multicastInterface n'est pas spécifié, le système d'exploitation choisira une interface et y ajoutera l'abonnement. Pour ajouter l'abonnement à chaque interface disponible, appelez addMembership plusieurs fois, une fois par interface.

Lorsqu'il est appelé sur un socket non lié, cette méthode se lie implicitement à un port aléatoire, écoutant sur toutes les interfaces.

Lors du partage d'un socket UDP entre plusieurs workers cluster, la fonction socket.addMembership() ne doit être appelée qu'une seule fois, sinon une erreur EADDRINUSE se produira :

ESMCJS

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

if (cluster.isPrimary) {
  cluster.fork() // Fonctionne correctement.
  cluster.fork() // Échoue avec 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() // Fonctionne correctement.
  cluster.fork() // Échoue avec EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

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

Ajouté dans : v13.1.0, v12.16.0

sourceAddress <string>
groupAddress <string>
multicastInterface <string>

Indique au noyau de rejoindre un canal multicast spécifique à la source aux adresses sourceAddress et groupAddress données, en utilisant l'interface multicastInterface avec l'option de socket IP_ADD_SOURCE_MEMBERSHIP. Si l'argument multicastInterface n'est pas spécifié, le système d'exploitation choisira une interface et y ajoutera l'abonnement. Pour ajouter l'abonnement à chaque interface disponible, appelez socket.addSourceSpecificMembership() plusieurs fois, une fois par interface.

Lorsqu'il est appelé sur un socket non lié, cette méthode se lie implicitement à un port aléatoire, écoutant sur toutes les interfaces.

`socket.address()`

Ajouté dans : v0.1.99

Retourne : <Object>

Retourne un objet contenant les informations d’adresse d’un socket. Pour les sockets UDP, cet objet contiendra les propriétés address, family et port.

Cette méthode lève EBADF si elle est appelée sur un socket non lié.

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

[Historique]

Version	Modifications
v0.9.1	La méthode a été modifiée pour un modèle d’exécution asynchrone. Le code hérité devrait être modifié pour passer une fonction de rappel à l’appel de la méthode.
v0.1.99	Ajouté dans : v0.1.99

port <integer>
address <string>
callback <Function> sans paramètres. Appelée lorsque la liaison est terminée.

Pour les sockets UDP, provoque l’écoute des messages datagram par le dgram.Socket sur un port nommé et une address facultative. Si port n’est pas spécifié ou vaut 0, le système d’exploitation essaiera de se lier à un port aléatoire. Si address n’est pas spécifié, le système d’exploitation essaiera d’écouter sur toutes les adresses. Une fois la liaison terminée, un événement 'listening' est émis et la fonction de callback facultative est appelée.

Spécifier à la fois un écouteur d’événements 'listening' et passer un callback à la méthode socket.bind() n’est pas nuisible mais peu utile.

Un socket de datagramme lié maintient le processus Node.js en cours d’exécution pour recevoir les messages de datagramme.

Si la liaison échoue, un événement 'error' est généré. Dans de rares cas (par exemple, tentative de liaison avec un socket fermé), une Error peut être levée.

Exemple d’un serveur UDP écoutant sur le port 41234 :

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

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

server.on('message', (msg, rinfo) => {
  console.log(`le serveur a reçu : ${msg} de ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`le serveur écoute ${address.address}:${address.port}`)
})

server.bind(41234)
// Affiche : le serveur écoute 0.0.0.0:41234

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

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

server.on('message', (msg, rinfo) => {
  console.log(`le serveur a reçu : ${msg} de ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`le serveur écoute ${address.address}:${address.port}`)
})

server.bind(41234)
// Affiche : le serveur écoute 0.0.0.0:41234

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

Ajouté dans : v0.11.14

options <Object> Requis. Prend en charge les propriétés suivantes :
- port <integer>
- address <string>
- exclusive <boolean>
- fd <integer>
callback <Function>

Pour les sockets UDP, amène le dgram.Socket à écouter les messages de datagramme sur un port nommé et une adresse optionnelle qui sont passés en tant que propriétés d’un objet options passé comme premier argument. Si port n’est pas spécifié ou vaut 0, le système d’exploitation tentera de se lier à un port aléatoire. Si address n’est pas spécifié, le système d’exploitation tentera d’écouter sur toutes les adresses. Une fois la liaison terminée, un événement 'listening' est émis et la fonction callback facultative est appelée.

L’objet options peut contenir une propriété fd. Lorsqu’un fd supérieur à 0 est défini, il enveloppera un socket existant avec le descripteur de fichier donné. Dans ce cas, les propriétés de port et address seront ignorées.

Spécifier à la fois un écouteur d’événement 'listening' et passer un callback à la méthode socket.bind() n’est pas nuisible mais pas très utile.

L’objet options peut contenir une propriété exclusive supplémentaire qui est utilisée lors de l’utilisation d’objets dgram.Socket avec le module cluster. Lorsque exclusive est défini sur false (la valeur par défaut), les workers du cluster utiliseront le même handle de socket sous-jacent, ce qui permettra de partager les tâches de gestion des connexions. Cependant, lorsque exclusive est true, le handle n’est pas partagé et toute tentative de partage de port entraîne une erreur. La création d’un dgram.Socket avec l’option reusePort définie sur true fait que exclusive est toujours true lorsque socket.bind() est appelé.

Un socket de datagramme lié maintient le processus Node.js en cours d’exécution pour recevoir des messages de datagramme.

Si la liaison échoue, un événement 'error' est généré. Dans de rares cas (par exemple, tentative de liaison avec un socket fermé), une Error peut être levée.

Un exemple de socket écoutant sur un port exclusif est présenté ci-dessous.

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

`socket.close([callback])`

Ajouté dans : v0.1.99

callback <Function> Appelée lorsque le socket a été fermé.

Ferme le socket sous-jacent et arrête l’écoute des données sur celui-ci. Si un callback est fourni, il est ajouté en tant qu’écouteur pour l’événement 'close'.

`socket[Symbol.asyncDispose]()`

Ajouté dans : v20.5.0, v18.18.0

[Stable: 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Appelle socket.close() et retourne une promesse qui est résolue lorsque le socket a été fermé.

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

Ajouté dans : v12.0.0

port <integer>
address <string>
callback <Function> Appelée lorsque la connexion est terminée ou en cas d’erreur.

Associe le dgram.Socket à une adresse et un port distants. Chaque message envoyé par cette poignée est automatiquement envoyé à cette destination. De plus, le socket ne recevra que les messages de ce pair distant. Tenter d’appeler connect() sur un socket déjà connecté entraînera une exception ERR_SOCKET_DGRAM_IS_CONNECTED. Si address n’est pas fourni, '127.0.0.1' (pour les sockets udp4) ou '::1' (pour les sockets udp6) seront utilisés par défaut. Une fois la connexion établie, un événement 'connect' est émis et la fonction callback facultative est appelée. En cas d’échec, le callback est appelé ou, à défaut, un événement 'error' est émis.

`socket.disconnect()`

Ajouté dans : v12.0.0

Une fonction synchrone qui dissocie un dgram.Socket connecté de son adresse distante. Tenter d’appeler disconnect() sur un socket non lié ou déjà déconnecté entraînera une exception ERR_SOCKET_DGRAM_NOT_CONNECTED.

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

Ajouté dans : v0.6.9

multicastAddress <string>
multicastInterface <string>

Demande au noyau de quitter un groupe multidiffusion à multicastAddress en utilisant l’option de socket IP_DROP_MEMBERSHIP. Cette méthode est automatiquement appelée par le noyau lorsque le socket est fermé ou que le processus se termine, donc la plupart des applications n’auront jamais de raison de l’appeler.

Si multicastInterface n’est pas spécifié, le système d’exploitation tentera de supprimer l’abonnement sur toutes les interfaces valides.

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

Ajouté dans : v13.1.0, v12.16.0

sourceAddress <string>
groupAddress <string>
multicastInterface <string>

Demande au noyau de quitter un canal de multidiffusion spécifique à la source à l’adresse sourceAddress et à l’adresse groupAddress données en utilisant l’option de socket IP_DROP_SOURCE_MEMBERSHIP. Cette méthode est automatiquement appelée par le noyau lorsque le socket est fermé ou que le processus se termine, donc la plupart des applications n’auront jamais de raison de l’appeler.

Si multicastInterface n’est pas spécifié, le système d’exploitation tentera de supprimer l’abonnement sur toutes les interfaces valides.

`socket.getRecvBufferSize()`

Ajouté dans : v8.7.0

Retourne : <number> la taille de la mémoire tampon de réception du socket SO_RCVBUF en octets.

Cette méthode lève ERR_SOCKET_BUFFER_SIZE si elle est appelée sur un socket non lié.

`socket.getSendBufferSize()`

Ajouté dans : v8.7.0

Retourne : <number> la taille de la mémoire tampon d’envoi du socket SO_SNDBUF en octets.

Cette méthode lève ERR_SOCKET_BUFFER_SIZE si elle est appelée sur un socket non lié.

`socket.getSendQueueSize()`

Ajouté dans : v18.8.0, v16.19.0

Retourne : <number> Nombre d’octets mis en file d’attente pour l’envoi.

`socket.getSendQueueCount()`

Ajouté dans : v18.8.0, v16.19.0

Retourne : <number> Nombre de demandes d’envoi actuellement dans la file d’attente en attente de traitement.

`socket.ref()`

Ajouté dans : v0.9.1

Retourne : <dgram.Socket>

Par défaut, la liaison d’un socket empêchera le processus Node.js de se fermer tant que le socket est ouvert. La méthode socket.unref() peut être utilisée pour exclure le socket du comptage des références qui maintient le processus Node.js actif. La méthode socket.ref() ajoute à nouveau le socket au comptage des références et rétablit le comportement par défaut.

L’appel de socket.ref() plusieurs fois n’aura aucun effet supplémentaire.

La méthode socket.ref() retourne une référence au socket afin que les appels puissent être chaînés.

`socket.remoteAddress()`

Ajouté dans : v12.0.0

Retourne : <Object>

Retourne un objet contenant l’address, la family et le port du point de terminaison distant. Cette méthode lève une exception ERR_SOCKET_DGRAM_NOT_CONNECTED si le socket n’est pas connecté.

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

[Historique]

Version	Modifications
v17.0.0	Le paramètre `address` accepte désormais uniquement une `string`, `null` ou `undefined`.
v14.5.0, v12.19.0	Le paramètre `msg` peut désormais être n’importe quel `TypedArray` ou `DataView`.
v12.0.0	Ajout de la prise en charge de l’envoi de données sur les sockets connectés.
v8.0.0	Le paramètre `msg` peut désormais être un `Uint8Array`.
v8.0.0	Le paramètre `address` est toujours facultatif désormais.
v6.0.0	En cas de succès, `callback` sera désormais appelé avec un argument `error` de `null` au lieu de `0`.
v5.7.0	Le paramètre `msg` peut désormais être un tableau. De plus, les paramètres `offset` et `length` sont désormais facultatifs.
v0.1.99	Ajouté dans : v0.1.99

msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> Message à envoyer.
offset <integer> Décalage dans la mémoire tampon où le message commence.
length <integer> Nombre d’octets dans le message.
port <integer> Port de destination.
address <string> Nom d’hôte ou adresse IP de destination.
callback <Function> Appelée lorsque le message a été envoyé.

Diffuse un datagramme sur le socket. Pour les sockets sans connexion, le port et l’address de destination doivent être spécifiés. Les sockets connectés, par contre, utiliseront leur point de terminaison distant associé, de sorte que les arguments port et address ne doivent pas être définis.

L’argument msg contient le message à envoyer. En fonction de son type, un comportement différent peut s’appliquer. Si msg est un Buffer, un TypedArray ou un DataView, l’offset et la length spécifient respectivement le décalage dans le Buffer où le message commence et le nombre d’octets dans le message. Si msg est une String, elle est automatiquement convertie en Buffer avec un encodage 'utf8'. Avec les messages qui contiennent des caractères multi-octets, offset et length seront calculés par rapport à la longueur en octets et non à la position du caractère. Si msg est un tableau, offset et length ne doivent pas être spécifiés.

L’argument address est une chaîne de caractères. Si la valeur de address est un nom d’hôte, le DNS sera utilisé pour résoudre l’adresse de l’hôte. Si address n’est pas fourni ou est nul, '127.0.0.1' (pour les sockets udp4) ou '::1' (pour les sockets udp6) seront utilisés par défaut.

Si le socket n’a pas été précédemment lié avec un appel à bind, le socket se voit attribuer un numéro de port aléatoire et est lié à l’adresse « toutes les interfaces » ('0.0.0.0' pour les sockets udp4, '::0' pour les sockets udp6).

Une fonction callback facultative peut être spécifiée comme moyen de signaler les erreurs DNS ou pour déterminer quand il est sûr de réutiliser l’objet buf. Les recherches DNS retardent le temps d’envoi d’au moins un tick de la boucle d’événements Node.js.

La seule façon de savoir avec certitude que le datagramme a été envoyé est d’utiliser une callback. Si une erreur se produit et qu’une callback est fournie, l’erreur sera transmise comme premier argument à la callback. Si une callback n’est pas fournie, l’erreur est émise comme un événement 'error' sur l’objet socket.

Le décalage et la longueur sont facultatifs, mais les deux doivent être définis si l’un ou l’autre est utilisé. Ils ne sont pris en charge que lorsque le premier argument est un Buffer, un TypedArray ou un DataView.

Cette méthode lève ERR_SOCKET_BAD_PORT si elle est appelée sur un socket non lié.

Exemple d’envoi d’un paquet UDP vers un port sur 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()
})

Exemple d’envoi d’un paquet UDP composé de plusieurs mémoires tampons vers un port sur 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’envoi de plusieurs mémoires tampons peut être plus rapide ou plus lent selon l’application et le système d’exploitation. Exécutez des benchmarks pour déterminer la stratégie optimale au cas par cas. Généralement, cependant, l’envoi de plusieurs mémoires tampons est plus rapide.

Exemple d’envoi d’un paquet UDP à l’aide d’un socket connecté à un port sur 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()
  })
})

Note concernant la taille des datagrammes UDP

La taille maximale d'un datagramme IPv4/v6 dépend de la MTU (Maximum Transmission Unit) et de la taille du champ Payload Length.

Le champ Payload Length a une largeur de 16 bits, ce qui signifie qu'une charge utile normale ne peut pas dépasser 64K octets, y compris l'en-tête Internet et les données (65 507 octets = 65 535 - 8 octets d'en-tête UDP - 20 octets d'en-tête IP) ; cela est généralement vrai pour les interfaces de bouclage, mais ces longs messages de datagrammes ne sont pas pratiques pour la plupart des hôtes et des réseaux.
La MTU est la plus grande taille qu'une technologie de couche de liaison donnée peut prendre en charge pour les messages de datagrammes. Pour toute liaison, IPv4 impose une MTU minimale de 68 octets, tandis que la MTU recommandée pour IPv4 est de 576 (généralement recommandée comme MTU pour les applications de type accès commuté), qu'elles arrivent entières ou en fragments. Pour IPv6, la MTU minimale est de 1280 octets. Cependant, la taille minimale obligatoire du tampon de réassemblage des fragments est de 1500 octets. La valeur de 68 octets est très petite, car la plupart des technologies de couche de liaison actuelles, comme Ethernet, ont une MTU minimale de 1500.

Il est impossible de connaître à l'avance la MTU de chaque liaison par laquelle un paquet pourrait transiter. L'envoi d'un datagramme supérieur à la MTU du destinataire ne fonctionnera pas, car le paquet sera silencieusement abandonné sans informer la source que les données n'ont pas atteint leur destinataire prévu.

`socket.setBroadcast(flag)`

Ajouté dans : v0.6.9

flag <boolean>

Définit ou efface l'option de socket SO_BROADCAST. Lorsque la valeur est définie sur true, les paquets UDP peuvent être envoyés à l'adresse de diffusion d'une interface locale.

Cette méthode lève EBADF si elle est appelée sur un socket non lié.

`socket.setMulticastInterface(multicastInterface)`

Ajouté dans : v8.6.0

multicastInterface <string>

Toutes les références à la portée dans cette section font référence aux Indexes de zone IPv6, qui sont définis par RFC 4007. Sous forme de chaîne, une adresse IP avec un index de portée est écrite comme 'IP%scope' où scope est un nom d'interface ou un numéro d'interface.

Définit l'interface de multidiffusion sortante par défaut du socket sur une interface choisie ou rétablit la sélection d'interface système. La multicastInterface doit être une représentation de chaîne valide d'une adresse IP de la famille du socket.

Pour les sockets IPv4, il doit s'agir de l'adresse IP configurée pour l'interface physique souhaitée. Tous les paquets envoyés en multidiffusion sur le socket seront envoyés sur l'interface déterminée par la dernière utilisation réussie de cet appel.

Pour les sockets IPv6, multicastInterface doit inclure une portée pour indiquer l'interface, comme dans les exemples qui suivent. Dans IPv6, les appels send individuels peuvent également utiliser une portée explicite dans les adresses, de sorte que seuls les paquets envoyés à une adresse de multidiffusion sans spécifier de portée explicite sont affectés par la dernière utilisation réussie de cet appel.

Cette méthode lève EBADF si elle est appelée sur un socket non lié.

Exemple : interface de multidiffusion IPv6 sortante

Sur la plupart des systèmes, où le format de la portée utilise le nom de l’interface :

const socket = dgram.createSocket('udp6')

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

Sur Windows, où le format de la portée utilise un numéro d’interface :

const socket = dgram.createSocket('udp6')

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

Exemple : interface de multidiffusion IPv4 sortante

Tous les systèmes utilisent une adresse IP de l’hôte sur l’interface physique souhaitée :

const socket = dgram.createSocket('udp4')

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

Résultats de l’appel

Un appel sur un socket qui n’est pas prêt à envoyer ou qui n’est plus ouvert peut générer une Error Not running (Non en cours d’exécution).

Si multicastInterface ne peut pas être analysé en une adresse IP, une System Error EINVAL est générée.

Sur IPv4, si multicastInterface est une adresse valide mais qu’elle ne correspond à aucune interface, ou si l’adresse ne correspond pas à la famille, une System Error telle que EADDRNOTAVAIL ou EPROTONOSUP est générée.

Sur IPv6, la plupart des erreurs liées à la spécification ou à l’omission de la portée feront en sorte que le socket continue d’utiliser (ou de revenir à) la sélection d’interface par défaut du système.

L’adresse ANY de la famille d’adresses d’un socket (IPv4 '0.0.0.0' ou IPv6 '::') peut être utilisée pour rétrocéder au système le contrôle de l’interface sortante par défaut des sockets pour les futurs paquets de multidiffusion.

`socket.setMulticastLoopback(flag)`

Ajouté dans : v0.3.8

flag <boolean>

Définit ou efface l’option de socket IP_MULTICAST_LOOP. Lorsque la valeur est définie sur true, les paquets de multidiffusion sont également reçus sur l’interface locale.

Cette méthode génère EBADF si elle est appelée sur un socket non lié.

`socket.setMulticastTTL(ttl)`

Ajouté dans : v0.3.8

ttl <integer>

Définit l’option de socket IP_MULTICAST_TTL. Bien que TTL signifie généralement « temps de vie », dans ce contexte, il spécifie le nombre de sauts IP qu’un paquet est autorisé à traverser, spécifiquement pour le trafic de multidiffusion. Chaque routeur ou passerelle qui transfère un paquet décrémente le TTL. Si le TTL est décrémenté à 0 par un routeur, il ne sera pas transféré.

L’argument ttl peut être compris entre 0 et 255. La valeur par défaut sur la plupart des systèmes est 1.

Cette méthode génère EBADF si elle est appelée sur un socket non lié.

`socket.setRecvBufferSize(size)`

Ajouté dans : v8.7.0

size <entier>

Définit l’option de socket SO_RCVBUF. Définit la taille maximale de la mémoire tampon de réception du socket en octets.

Cette méthode lève une exception ERR_SOCKET_BUFFER_SIZE si elle est appelée sur un socket non lié.

`socket.setSendBufferSize(size)`

Ajouté dans : v8.7.0

size <entier>

Définit l’option de socket SO_SNDBUF. Définit la taille maximale de la mémoire tampon d’envoi du socket en octets.

Cette méthode lève une exception ERR_SOCKET_BUFFER_SIZE si elle est appelée sur un socket non lié.

`socket.setTTL(ttl)`

Ajouté dans : v0.1.101

ttl <entier>

Définit l’option de socket IP_TTL. Bien que TTL signifie généralement "Time to Live" (durée de vie), dans ce contexte, il spécifie le nombre de sauts IP qu’un paquet est autorisé à traverser. Chaque routeur ou passerelle qui transmet un paquet décrémente le TTL. Si le TTL est décrémenté à 0 par un routeur, il ne sera pas transmis. La modification des valeurs TTL est généralement effectuée pour les sondes de réseau ou lors de la multidiffusion.

L’argument ttl peut être compris entre 1 et 255. La valeur par défaut sur la plupart des systèmes est 64.

Cette méthode lève une exception EBADF si elle est appelée sur un socket non lié.

`socket.unref()`

Ajouté dans : v0.9.1

Retourne : <dgram.Socket>

Par défaut, la liaison d’un socket empêchera le processus Node.js de se terminer tant que le socket est ouvert. La méthode socket.unref() peut être utilisée pour exclure le socket du comptage de références qui maintient le processus Node.js actif, ce qui permet au processus de se terminer même si le socket est toujours à l’écoute.

L’appel de socket.unref() plusieurs fois n’aura aucun effet supplémentaire.

La méthode socket.unref() renvoie une référence au socket afin que les appels puissent être chaînés.

Fonctions du module `node:dgram`

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

[Historique]

Version	Modifications
v23.1.0	L'option `reusePort` est prise en charge.
v15.8.0	Ajout de la prise en charge d'AbortSignal.
v11.4.0	L'option `ipv6Only` est prise en charge.
v8.7.0	Les options `recvBufferSize` et `sendBufferSize` sont maintenant prises en charge.
v8.6.0	L'option `lookup` est prise en charge.
v0.11.13	Ajouté dans : v0.11.13

options <Object> Les options disponibles sont les suivantes :
- type <string> La famille de socket. Doit être 'udp4' ou 'udp6'. Requis.
- reuseAddr <boolean> Lorsque la valeur est true, socket.bind() réutilisera l’adresse, même si un autre processus a déjà lié un socket dessus, mais un seul socket peut recevoir les données. Par défaut : false.
- reusePort <boolean> Lorsque la valeur est true, socket.bind() réutilisera le port, même si un autre processus a déjà lié un socket dessus. Les datagrammes entrants sont distribués aux sockets en écoute. L’option est uniquement disponible sur certaines plateformes, comme Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4 et AIX 7.2.5+. Sur les plateformes non prises en charge, cette option génère une erreur lorsque le socket est lié. Par défaut : false.
- ipv6Only <boolean> Définir ipv6Only à true désactivera la prise en charge de la double pile, c’est-à-dire que la liaison à l’adresse :: ne fera pas que 0.0.0.0 soit lié. Par défaut : false.
- recvBufferSize <number> Définit la valeur de socket SO_RCVBUF.
- sendBufferSize <number> Définit la valeur de socket SO_SNDBUF.
- lookup <Function> Fonction de recherche personnalisée. Par défaut : dns.lookup().
- signal <AbortSignal> Un AbortSignal qui peut être utilisé pour fermer un socket.
- receiveBlockList <net.BlockList> receiveBlockList peut être utilisé pour ignorer les datagrammes entrants vers des adresses IP, des plages IP ou des sous-réseaux IP spécifiques. Cela ne fonctionne pas si le serveur se trouve derrière un proxy inverse, un NAT, etc., car l’adresse vérifiée par rapport à la liste de blocage est l’adresse du proxy ou celle spécifiée par le NAT.
- sendBlockList <net.BlockList> sendBlockList peut être utilisé pour désactiver l’accès sortant à des adresses IP, des plages IP ou des sous-réseaux IP spécifiques.
callback <Function> Attaché en tant qu’écouteur pour les événements 'message'. Optionnel.
Retourne : <dgram.Socket>

Crée un objet dgram.Socket. Une fois le socket créé, l’appel de socket.bind() indiquera au socket de commencer à écouter les messages datagrammes. Lorsque address et port ne sont pas transmis à socket.bind(), la méthode liera le socket à l’adresse « toutes les interfaces » sur un port aléatoire (il fait ce qu’il faut pour les sockets udp4 et udp6). L’adresse et le port liés peuvent être récupérés à l’aide de socket.address().address et socket.address().port.

Si l’option signal est activée, l’appel de .abort() sur le AbortController correspondant est similaire à l’appel de .close() sur le socket :

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}`)
})
// Plus tard, lorsque vous voulez fermer le serveur.
controller.abort()

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

Ajouté dans : v0.1.99

type <string> Soit 'udp4', soit 'udp6'.
callback <Function> Attachée en tant qu'écouteur aux événements 'message'.
Retourne : <dgram.Socket>

Crée un objet dgram.Socket du type spécifié.

Une fois le socket créé, l'appel de socket.bind() demandera au socket de commencer à écouter les messages de datagramme. Lorsque address et port ne sont pas transmis à socket.bind(), la méthode liera le socket à l'adresse « toutes interfaces » sur un port aléatoire (elle fait ce qu'il faut pour les sockets udp4 et udp6). L'adresse et le port liés peuvent être récupérés à l'aide de socket.address().address et de socket.address().port.

Sockets UDP/datagramme ​

Classe : dgram.Socket ​

Événement : 'close' ​

Événement : 'connect' ​

Événement : 'error' ​

Événement : 'listening' ​

Événement : '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]) ​

Note concernant la taille des datagrammes UDP ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

Exemple : interface de multidiffusion IPv6 sortante ​

Exemple : interface de multidiffusion IPv4 sortante ​

Résultats de l’appel ​

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

Fonctions du module node:dgram ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

Sockets UDP/datagramme

Classe : `dgram.Socket`

Événement : `'close'`

Événement : `'connect'`

Événement : `'error'`

Événement : `'listening'`

Événement : `'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])`

Note concernant la taille des datagrammes UDP

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

Exemple : interface de multidiffusion IPv6 sortante

Exemple : interface de multidiffusion IPv4 sortante

Résultats de l’appel

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

Fonctions du module `node:dgram`

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

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