UDP/Datagram-Sockets

[Stabil: 2 - Stabil]

Das Modul node:dgram bietet eine Implementierung von UDP-Datagram-Sockets.

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

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

server.on('message', (msg, rinfo) => {
  console.log(`Server empfangen: ${msg} von ${rinfo.address}:${rinfo.port}`)
})

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

server.bind(41234)
// Ausgabe: Server lauscht auf 0.0.0.0:41234

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

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

server.on('message', (msg, rinfo) => {
  console.log(`Server empfangen: ${msg} von ${rinfo.address}:${rinfo.port}`)
})

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

server.bind(41234)
// Ausgabe: Server lauscht auf 0.0.0.0:41234

Klasse: `dgram.Socket`

Hinzugefügt in: v0.1.99

Erweitert: <EventEmitter>

Kapselt die Datagrammfunktionalität.

Neue Instanzen von dgram.Socket werden mit dgram.createSocket() erstellt. Der new-Operator darf nicht verwendet werden, um dgram.Socket-Instanzen zu erstellen.

Ereignis: `'close'`

Hinzugefügt in: v0.1.99

Das Ereignis 'close' wird ausgelöst, nachdem ein Socket mit close() geschlossen wurde. Nach dem Auslösen werden keine neuen 'message'-Ereignisse mehr für diesen Socket emittiert.

Ereignis: `'connect'`

Hinzugefügt in: v12.0.0

Das Ereignis 'connect' wird ausgelöst, nachdem ein Socket aufgrund eines erfolgreichen connect()-Aufrufs einer Remote-Adresse zugeordnet wurde.

Ereignis: `'error'`

Hinzugefügt in: v0.1.99

exception <Error>

Das Ereignis 'error' wird immer dann ausgelöst, wenn ein Fehler auftritt. Die Ereignisbehandlungsfunktion erhält ein einzelnes Error-Objekt übergeben.

Ereignis: `'listening'`

Hinzugefügt in: v0.1.99

Das Ereignis 'listening' wird ausgelöst, sobald der dgram.Socket adressierbar ist und Daten empfangen kann. Dies geschieht entweder explizit mit socket.bind() oder implizit beim ersten Senden von Daten mit socket.send(). Solange der dgram.Socket nicht lauscht, existieren die zugrundeliegenden Systemressourcen nicht und Aufrufe wie socket.address() und socket.setTTL() schlagen fehl.

Ereignis: `'message'`

[Verlauf]

Version	Änderungen
v18.4.0	Die Eigenschaft `family` gibt jetzt einen String anstelle einer Zahl zurück.
v18.0.0	Die Eigenschaft `family` gibt jetzt eine Zahl anstelle eines Strings zurück.
v0.1.99	Hinzugefügt in: v0.1.99

Das Ereignis 'message' wird ausgelöst, wenn ein neues Datagramm auf einem Socket verfügbar ist. Die Ereignisbehandlungsfunktion erhält zwei Argumente: msg und rinfo.

msg <Buffer> Die Nachricht.
rinfo <Object> Informationen zur Remote-Adresse.
- address <string> Die Absenderadresse.
- family <string> Die Adressfamilie ('IPv4' oder 'IPv6').
- port <number> Der Absenderport.
- size <number> Die Nachrichtengröße.

Wenn die Quelladresse des eingehenden Pakets eine IPv6-Link-lokale Adresse ist, wird der Interface-Name der Adresse hinzugefügt. Beispielsweise könnte ein auf dem Interface en0 empfangenes Paket das Adressfeld auf 'fe80::2618:1234:ab11:3b9c%en0' gesetzt haben, wobei '%en0' der Interface-Name als Zonen-ID-Suffix ist.

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

Hinzugefügt in: v0.6.9

multicastAddress <string>
multicastInterface <string>

Teilt dem Kernel mit, einer Multicast-Gruppe an der angegebenen multicastAddress und multicastInterface mit der Socket-Option IP_ADD_MEMBERSHIP beizutreten. Wenn das Argument multicastInterface nicht angegeben ist, wählt das Betriebssystem eine Schnittstelle aus und fügt die Mitgliedschaft hinzu. Um die Mitgliedschaft zu jeder verfügbaren Schnittstelle hinzuzufügen, rufen Sie addMembership mehrmals auf, einmal pro Schnittstelle.

Wenn diese Methode auf einem ungebundenen Socket aufgerufen wird, bindet sie implizit an einen zufälligen Port und hört auf allen Schnittstellen zu.

Bei der gemeinsamen Nutzung eines UDP-Sockets über mehrere cluster-Worker muss die Funktion socket.addMembership() nur einmal aufgerufen werden, da sonst ein EADDRINUSE-Fehler auftritt:

ESMCJS

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

if (cluster.isPrimary) {
  cluster.fork() // Funktioniert korrekt.
  cluster.fork() // Schlägt mit EADDRINUSE fehl.
} 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() // Funktioniert korrekt.
  cluster.fork() // Schlägt mit EADDRINUSE fehl.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

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

Hinzugefügt in: v13.1.0, v12.16.0

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

Teilt dem Kernel mit, einem quellenspezifischen Multicast-Kanal an der angegebenen sourceAddress und groupAddress mit der multicastInterface und der Socket-Option IP_ADD_SOURCE_MEMBERSHIP beizutreten. Wenn das Argument multicastInterface nicht angegeben ist, wählt das Betriebssystem eine Schnittstelle aus und fügt die Mitgliedschaft hinzu. Um die Mitgliedschaft zu jeder verfügbaren Schnittstelle hinzuzufügen, rufen Sie socket.addSourceSpecificMembership() mehrmals auf, einmal pro Schnittstelle.

Wenn diese Methode auf einem ungebundenen Socket aufgerufen wird, bindet sie implizit an einen zufälligen Port und hört auf allen Schnittstellen zu.

`socket.address()`

Hinzugefügt in: v0.1.99

Gibt zurück: <Objekt>

Gibt ein Objekt zurück, das die Adressinformationen für einen Socket enthält. Für UDP-Sockets enthält dieses Objekt die Eigenschaften address, family und port.

Diese Methode löst EBADF aus, wenn sie für einen ungebundenen Socket aufgerufen wird.

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

[Verlauf]

Version	Änderungen
v0.9.1	Die Methode wurde auf ein asynchrones Ausführungsmodell geändert. Legacy-Code muss geändert werden, um eine Callback-Funktion an den Methodenaufruf zu übergeben.
v0.1.99	Hinzugefügt in: v0.1.99

port <Integer>
address <String>
callback <Funktion> ohne Parameter. Wird aufgerufen, wenn die Bindung abgeschlossen ist.

Für UDP-Sockets bewirkt dies, dass der dgram.Socket auf Datagrammnachrichten an einem benannten port und einer optionalen address lauscht. Wenn port nicht angegeben ist oder 0 ist, versucht das Betriebssystem, an einen zufälligen Port zu binden. Wenn address nicht angegeben ist, versucht das Betriebssystem, auf allen Adressen zu lauschen. Sobald die Bindung abgeschlossen ist, wird ein 'listening'-Ereignis emittiert und die optionale callback-Funktion wird aufgerufen.

Das Angeben eines 'listening'-Ereignislisteners und das Übergeben eines callback an die socket.bind()-Methode ist nicht schädlich, aber nicht sehr nützlich.

Ein gebundener Datagramm-Socket hält den Node.js-Prozess am Laufen, um Datagrammnachrichten zu empfangen.

Wenn die Bindung fehlschlägt, wird ein 'error'-Ereignis generiert. In seltenen Fällen (z. B. beim Versuch, mit einem geschlossenen Socket zu binden) kann ein Error ausgelöst werden.

Beispiel für einen UDP-Server, der an Port 41234 lauscht:

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)
// Gibt aus: 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)
// Gibt aus: server listening 0.0.0.0:41234

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

Hinzugefügt in: v0.11.14

options <Objekt> Erforderlich. Unterstützt die folgenden Eigenschaften:
- port <Ganzzahl>
- address <Zeichenkette>
- exclusive <Boolescher Wert>
- fd <Ganzzahl>
callback <Funktion>

Für UDP-Sockets veranlasst dies den dgram.Socket, auf Datagrammnachrichten an einem benannten port und einer optionalen address zu lauschen, die als Eigenschaften eines options-Objekts übergeben werden, das als erstes Argument übergeben wird. Wenn port nicht angegeben ist oder 0 ist, versucht das Betriebssystem, an einen zufälligen Port zu binden. Wenn address nicht angegeben ist, versucht das Betriebssystem, auf allen Adressen zu lauschen. Sobald die Bindung abgeschlossen ist, wird ein 'listening'-Ereignis emittiert und die optionale callback-Funktion wird aufgerufen.

Das options-Objekt kann eine fd-Eigenschaft enthalten. Wenn ein fd größer als 0 gesetzt ist, wird es einen vorhandenen Socket mit dem angegebenen File Descriptor umschließen. In diesem Fall werden die Eigenschaften von port und address ignoriert.

Die gleichzeitige Angabe eines 'listening'-Ereignislisteners und die Übergabe eines callback an die socket.bind()-Methode ist nicht schädlich, aber nicht sehr nützlich.

Das options-Objekt kann eine zusätzliche exclusive-Eigenschaft enthalten, die bei der Verwendung von dgram.Socket-Objekten mit dem Modul cluster verwendet wird. Wenn exclusive auf false (Standardwert) gesetzt ist, verwenden Cluster-Worker denselben zugrunde liegenden Socket-Handle, sodass die Aufgaben der Verbindungsbehandlung gemeinsam genutzt werden können. Wenn exclusive jedoch true ist, wird der Handle nicht gemeinsam genutzt und der Versuch, den Port gemeinsam zu nutzen, führt zu einem Fehler. Das Erstellen eines dgram.Socket mit der auf true gesetzten Option reusePort bewirkt, dass exclusive immer true ist, wenn socket.bind() aufgerufen wird.

Ein gebundener Datagram Socket hält den Node.js-Prozess am Laufen, um Datagrammnachrichten zu empfangen.

Wenn die Bindung fehlschlägt, wird ein 'error'-Ereignis generiert. In seltenen Fällen (z. B. beim Versuch, mit einem geschlossenen Socket zu binden) kann ein Error ausgelöst werden.

Ein Beispiel für einen Socket, der auf einem exklusiven Port lauscht, ist unten dargestellt.

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

`socket.close([callback])`

Hinzugefügt in: v0.1.99

callback <Function> Wird aufgerufen, wenn der Socket geschlossen wurde.

Schließt den zugrunde liegenden Socket und hört auf, auf Daten zu lauschen. Wenn ein Callback bereitgestellt wird, wird er als Listener für das 'close' Ereignis hinzugefügt.

`socket[Symbol.asyncDispose]()`

Hinzugefügt in: v20.5.0, v18.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Ruft socket.close() auf und gibt ein Promise zurück, das erfüllt wird, wenn der Socket geschlossen wurde.

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

Hinzugefügt in: v12.0.0

port <integer>
address <string>
callback <Function> Wird aufgerufen, wenn die Verbindung abgeschlossen ist oder bei einem Fehler.

Ordnet das dgram.Socket einer Remote-Adresse und einem Remote-Port zu. Jede über dieses Handle gesendete Nachricht wird automatisch an dieses Ziel gesendet. Außerdem empfängt der Socket nur Nachrichten von diesem Remote-Peer. Der Versuch, connect() auf einem bereits verbundenen Socket aufzurufen, führt zu einer ERR_SOCKET_DGRAM_IS_CONNECTED Ausnahme. Wenn address nicht angegeben wird, wird standardmäßig '127.0.0.1' (für udp4-Sockets) oder '::1' (für udp6-Sockets) verwendet. Sobald die Verbindung hergestellt ist, wird ein 'connect'-Ereignis emittiert und die optionale callback-Funktion wird aufgerufen. Im Fehlerfall wird der callback aufgerufen oder, falls dies fehlschlägt, ein 'error'-Ereignis emittiert.

`socket.disconnect()`

Hinzugefügt in: v12.0.0

Eine synchrone Funktion, die ein verbundenes dgram.Socket von seiner Remote-Adresse trennt. Der Versuch, disconnect() auf einem ungebundenen oder bereits getrennten Socket aufzurufen, führt zu einer ERR_SOCKET_DGRAM_NOT_CONNECTED Ausnahme.

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

Hinzugefügt in: v0.6.9

multicastAddress <string>
multicastInterface <string>

Weist den Kernel an, eine Multicast-Gruppe unter multicastAddress mithilfe der Socket-Option IP_DROP_MEMBERSHIP zu verlassen. Diese Methode wird vom Kernel automatisch aufgerufen, wenn die Socket geschlossen wird oder der Prozess beendet wird, daher müssen die meisten Anwendungen diese niemals aufrufen.

Wenn multicastInterface nicht angegeben ist, versucht das Betriebssystem, die Mitgliedschaft auf allen gültigen Schnittstellen aufzuheben.

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

Hinzugefügt in: v13.1.0, v12.16.0

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

Weist den Kernel an, einen quellenspezifischen Multicast-Kanal unter der angegebenen sourceAddress und groupAddress mithilfe der Socket-Option IP_DROP_SOURCE_MEMBERSHIP zu verlassen. Diese Methode wird vom Kernel automatisch aufgerufen, wenn die Socket geschlossen wird oder der Prozess beendet wird, daher müssen die meisten Anwendungen diese niemals aufrufen.

Wenn multicastInterface nicht angegeben ist, versucht das Betriebssystem, die Mitgliedschaft auf allen gültigen Schnittstellen aufzuheben.

`socket.getRecvBufferSize()`

Hinzugefügt in: v8.7.0

Gibt zurück: <number> die Größe des Socket-Empfangs-Puffers SO_RCVBUF in Bytes.

Diese Methode löst ERR_SOCKET_BUFFER_SIZE aus, wenn sie für eine ungebundene Socket aufgerufen wird.

`socket.getSendBufferSize()`

Hinzugefügt in: v8.7.0

Gibt zurück: <number> die Größe des Socket-Sende-Puffers SO_SNDBUF in Bytes.

Diese Methode löst ERR_SOCKET_BUFFER_SIZE aus, wenn sie für eine ungebundene Socket aufgerufen wird.

`socket.getSendQueueSize()`

Hinzugefügt in: v18.8.0, v16.19.0

Rückgabewert: <number> Anzahl der Bytes, die zum Senden bereitgestellt wurden.

`socket.getSendQueueCount()`

Hinzugefügt in: v18.8.0, v16.19.0

Rückgabewert: <number> Anzahl der Sendeanforderungen, die sich derzeit in der Warteschlange befinden und auf die Verarbeitung warten.

`socket.ref()`

Hinzugefügt in: v0.9.1

Rückgabewert: <dgram.Socket>

Standardmäßig führt das Binden eines Sockets dazu, dass der Node.js-Prozess solange blockiert wird, wie der Socket geöffnet ist. Die Methode socket.unref() kann verwendet werden, um den Socket von der Referenzzählung auszuschließen, die den Node.js-Prozess aktiv hält. Die Methode socket.ref() fügt den Socket wieder zur Referenzzählung hinzu und stellt das Standardverhalten wieder her.

Mehrfaches Aufrufen von socket.ref() hat keine zusätzliche Wirkung.

Die Methode socket.ref() gibt eine Referenz auf den Socket zurück, sodass Aufrufe verkettet werden können.

`socket.remoteAddress()`

Hinzugefügt in: v12.0.0

Rückgabewert: <Object>

Gibt ein Objekt zurück, das die address, family und port des entfernten Endpunkts enthält. Diese Methode löst eine ERR_SOCKET_DGRAM_NOT_CONNECTED-Ausnahme aus, wenn der Socket nicht verbunden ist.

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

[Verlauf]

Version	Änderungen
v17.0.0	Der Parameter `address` akzeptiert jetzt nur noch einen `string`, `null` oder `undefined`.
v14.5.0, v12.19.0	Der Parameter `msg` kann jetzt ein beliebiges `TypedArray` oder `DataView` sein.
v12.0.0	Unterstützung für das Senden von Daten über verbundene Sockets hinzugefügt.
v8.0.0	Der Parameter `msg` kann jetzt ein `Uint8Array` sein.
v8.0.0	Der Parameter `address` ist jetzt immer optional.
v6.0.0	Bei Erfolg wird `callback` jetzt mit einem `error`-Argument von `null` anstatt `0` aufgerufen.
v5.7.0	Der Parameter `msg` kann jetzt ein Array sein. Außerdem sind die Parameter `offset` und `length` jetzt optional.
v0.1.99	Hinzugefügt in: v0.1.99

msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> Zu sendende Nachricht.
offset <integer> Offset im Puffer, an dem die Nachricht beginnt.
length <integer> Anzahl der Bytes in der Nachricht.
port <integer> Zielport.
address <string> Ziel-Hostname oder IP-Adresse.
callback <Function> Wird aufgerufen, wenn die Nachricht gesendet wurde.

Sendet ein Datagramm auf dem Socket. Bei verbindungslosen Sockets müssen der Ziel-port und die address angegeben werden. Verbundene Sockets verwenden hingegen ihren zugehörigen entfernten Endpunkt, daher dürfen die Argumente port und address nicht gesetzt werden.

Das Argument msg enthält die zu sendende Nachricht. Abhängig vom Typ kann sich ein anderes Verhalten ergeben. Wenn msg ein Buffer, ein TypedArray oder ein DataView ist, geben offset und length den Offset innerhalb des Buffer an, an dem die Nachricht beginnt, und die Anzahl der Bytes in der Nachricht. Wenn msg ein String ist, wird er automatisch mit der Codierung 'utf8' in einen Buffer konvertiert. Bei Nachrichten, die mehrbyte Zeichen enthalten, werden offset und length in Bezug auf die Bytelänge und nicht die Zeichenposition berechnet. Wenn msg ein Array ist, dürfen offset und length nicht angegeben werden.

Das Argument address ist eine Zeichenkette. Wenn der Wert von address ein Hostname ist, wird DNS verwendet, um die Adresse des Hosts aufzulösen. Wenn address nicht angegeben oder anderweitig nullish ist, wird standardmäßig '127.0.0.1' (für udp4-Sockets) oder '::1' (für udp6-Sockets) verwendet.

Wenn der Socket nicht zuvor mit einem Aufruf von bind gebunden wurde, wird dem Socket eine zufällige Portnummer zugewiesen und er wird an die Adresse "alle Schnittstellen" gebunden ('0.0.0.0' für udp4-Sockets, '::0' für udp6-Sockets).

Eine optionale callback-Funktion kann angegeben werden, um DNS-Fehler zu melden oder um zu bestimmen, wann das buf-Objekt sicher wiederverwendet werden kann. DNS-Lookups verzögern die Sendezeit um mindestens einen Tick des Node.js-Ereignislaufs.

Die einzige Möglichkeit, sicher zu wissen, dass das Datagramm gesendet wurde, ist die Verwendung eines callback. Wenn ein Fehler auftritt und ein callback angegeben ist, wird der Fehler als erstes Argument an den callback übergeben. Wenn kein callback angegeben ist, wird der Fehler als 'error'-Ereignis für das socket-Objekt emittiert.

Offset und Länge sind optional, aber beide müssen gesetzt werden, wenn einer von beiden verwendet wird. Sie werden nur unterstützt, wenn das erste Argument ein Buffer, ein TypedArray oder ein DataView ist.

Diese Methode löst ERR_SOCKET_BAD_PORT aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

Beispiel für das Senden eines UDP-Pakets an einen Port auf 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()
})

Beispiel für das Senden eines UDP-Pakets, das aus mehreren Puffern besteht, an einen Port auf 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()
})

Das Senden mehrerer Puffer kann je nach Anwendung und Betriebssystem schneller oder langsamer sein. Führen Sie Benchmarks durch, um die optimale Strategie von Fall zu Fall zu bestimmen. Im Allgemeinen ist das Senden mehrerer Puffer jedoch schneller.

Beispiel für das Senden eines UDP-Pakets mit einem an einen Port auf localhost verbundenen Socket:

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()
  })
})

Hinweis zur Größe von UDP-Datagrammen

Die maximale Größe eines IPv4/v6-Datagrams hängt von der MTU (Maximum Transmission Unit) und der Größe des Felds Payload Length ab.

Das Feld Payload Length ist 16 Bit breit, d. h., eine normale Nutzlast darf 64 K Octets einschließlich des Internet-Headers und der Daten nicht überschreiten (65.507 Bytes = 65.535 − 8 Bytes UDP-Header − 20 Bytes IP-Header); dies gilt im Allgemeinen für Loopback-Schnittstellen, aber so lange Datagrammbotschaften sind für die meisten Hosts und Netzwerke unpraktisch.
Die MTU ist die größte Größe, die eine gegebene Link-Layer-Technologie für Datagrammbotschaften unterstützen kann. Für jede Verbindung schreibt IPv4 eine minimale MTU von 68 Octets vor, während die empfohlene MTU für IPv4 576 beträgt (typischerweise als MTU für Dial-up-Anwendungen empfohlen), unabhängig davon, ob sie vollständig oder in Fragmenten ankommen. Für IPv6 beträgt die minimale MTU 1280 Octets. Die obligatorische minimale Größe des Puffers für die Fragmentreassembly beträgt jedoch 1500 Octets. Der Wert von 68 Octets ist sehr klein, da die meisten aktuellen Link-Layer-Technologien wie Ethernet eine minimale MTU von 1500 haben.

Es ist unmöglich, im Voraus die MTU jeder Verbindung zu kennen, über die ein Paket möglicherweise übertragen wird. Das Senden eines Datagramms, das größer als die Empfänger-MTU ist, funktioniert nicht, da das Paket stillschweigend verworfen wird, ohne die Quelle darüber zu informieren, dass die Daten ihren beabsichtigten Empfänger nicht erreicht haben.

`socket.setBroadcast(flag)`

Hinzugefügt in: v0.6.9

flag <boolean>

Setzt oder löscht die Socket-Option SO_BROADCAST. Wenn auf true gesetzt, können UDP-Pakete an die Broadcast-Adresse einer lokalen Schnittstelle gesendet werden.

Diese Methode löst EBADF aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

`socket.setMulticastInterface(multicastInterface)`

Hinzugefügt in: v8.6.0

multicastInterface <string>

Alle Verweise auf den Gültigkeitsbereich in diesem Abschnitt beziehen sich auf IPv6-Zonenindizes, die durch RFC 4007 definiert sind. In Stringform wird eine IP mit einem Gültigkeitsbereichsindex als 'IP%scope' geschrieben, wobei scope ein Schnittstellenname oder eine Schnittstellennummer ist.

Legt die standardmäßige ausgehende Multicast-Schnittstelle des Sockets auf eine gewählte Schnittstelle oder zurück auf die Auswahl der Systemschnittstelle fest. multicastInterface muss eine gültige String-Darstellung einer IP aus der Socket-Familie sein.

Bei IPv4-Sockets sollte dies die IP sein, die für die gewünschte physische Schnittstelle konfiguriert ist. Alle Pakete, die an Multicast auf dem Socket gesendet werden, werden auf der Schnittstelle gesendet, die durch die letzte erfolgreiche Verwendung dieses Aufrufs bestimmt wird.

Bei IPv6-Sockets sollte multicastInterface einen Gültigkeitsbereich enthalten, um die Schnittstelle wie in den folgenden Beispielen anzugeben. In IPv6 können einzelne send-Aufrufe auch explizite Gültigkeitsbereiche in Adressen verwenden, daher sind nur Pakete, die an eine Multicast-Adresse gesendet werden, ohne einen expliziten Gültigkeitsbereich anzugeben, von der letzten erfolgreichen Verwendung dieses Aufrufs betroffen.

Diese Methode löst EBADF aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

Beispiel: Ausgehendes IPv6-Multicast-Interface

Auf den meisten Systemen, wo das Scope-Format den Interface-Namen verwendet:

const socket = dgram.createSocket('udp6')

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

Unter Windows, wo das Scope-Format eine Interface-Nummer verwendet:

const socket = dgram.createSocket('udp6')

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

Beispiel: Ausgehendes IPv4-Multicast-Interface

Alle Systeme verwenden eine IP des Hosts auf dem gewünschten physikalischen Interface:

const socket = dgram.createSocket('udp4')

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

Aufrufergebnisse

Ein Aufruf auf einem Socket, der nicht sendefähig ist oder nicht mehr geöffnet ist, kann einen Not running Error auslösen.

Wenn multicastInterface nicht als IP geparst werden kann, wird ein EINVAL System Error ausgelöst.

Bei IPv4, wenn multicastInterface eine gültige Adresse ist, aber mit keinem Interface übereinstimmt, oder wenn die Adresse nicht mit der Familie übereinstimmt, wird ein System Error wie EADDRNOTAVAIL oder EPROTONOSUP ausgelöst.

Bei IPv6 führen die meisten Fehler bei der Angabe oder Auslassung des Scopes dazu, dass der Socket weiterhin die Standard-Interface-Auswahl des Systems verwendet (oder dorthin zurückkehrt).

Die ANY-Adresse der Socket-Adressfamilie (IPv4 '0.0.0.0' oder IPv6 '::') kann verwendet werden, um die Kontrolle über das standardmäßige ausgehende Interface des Sockets für zukünftige Multicast-Pakete an das System zurückzugeben.

`socket.setMulticastLoopback(flag)`

Hinzugefügt in: v0.3.8

flag <boolean>

Setzt oder löscht die Socket-Option IP_MULTICAST_LOOP. Wenn auf true gesetzt, werden Multicast-Pakete auch auf dem lokalen Interface empfangen.

Diese Methode löst EBADF aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

`socket.setMulticastTTL(ttl)`

Hinzugefügt in: v0.3.8

ttl <integer>

Setzt die Socket-Option IP_MULTICAST_TTL. Während TTL im Allgemeinen für "Time to Live" steht, gibt es in diesem Kontext die Anzahl der IP-Hops an, die ein Paket durchlaufen darf, speziell für Multicast-Traffic. Jeder Router oder Gateway, der ein Paket weiterleitet, dekrementiert die TTL. Wenn die TTL von einem Router auf 0 dekrementiert wird, wird sie nicht weitergeleitet.

Das Argument ttl darf zwischen 0 und 255 liegen. Der Standardwert auf den meisten Systemen ist 1.

Diese Methode löst EBADF aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

`socket.setRecvBufferSize(size)`

Hinzugefügt in: v8.7.0

size <integer>

Setzt die Socket-Option SO_RCVBUF. Legt den maximalen Socket-Empfangspuffer in Bytes fest.

Diese Methode löst ERR_SOCKET_BUFFER_SIZE aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

`socket.setSendBufferSize(size)`

Hinzugefügt in: v8.7.0

size <integer>

Setzt die Socket-Option SO_SNDBUF. Legt den maximalen Socket-Sendepuffer in Bytes fest.

Diese Methode löst ERR_SOCKET_BUFFER_SIZE aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

`socket.setTTL(ttl)`

Hinzugefügt in: v0.1.101

ttl <integer>

Setzt die Socket-Option IP_TTL. Obwohl TTL im Allgemeinen für "Time to Live" steht, gibt es in diesem Kontext die Anzahl der IP-Hops an, die ein Paket durchlaufen darf. Jeder Router oder Gateway, der ein Paket weiterleitet, dekrementiert den TTL-Wert. Wenn der TTL-Wert von einem Router auf 0 dekrementiert wird, wird er nicht weitergeleitet. Das Ändern von TTL-Werten erfolgt in der Regel für Netzwerktests oder beim Multicasting.

Das Argument ttl kann zwischen 1 und 255 liegen. Der Standardwert auf den meisten Systemen ist 64.

Diese Methode löst EBADF aus, wenn sie auf einem ungebundenen Socket aufgerufen wird.

`socket.unref()`

Hinzugefügt in: v0.9.1

Rückgabewert: <dgram.Socket>

Standardmäßig führt das Binden eines Sockets dazu, dass der Node.js-Prozess blockiert wird, solange der Socket geöffnet ist. Die Methode socket.unref() kann verwendet werden, um den Socket von der Referenzzählung auszuschließen, die den Node.js-Prozess aktiv hält, sodass der Prozess auch dann beendet werden kann, wenn der Socket noch lauscht.

Mehrfaches Aufrufen von socket.unref() hat keine zusätzliche Wirkung.

Die Methode socket.unref() gibt eine Referenz auf den Socket zurück, sodass Aufrufe verkettet werden können.

`node:dgram` Modulfunktionen

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

[Verlauf]

Version	Änderungen
v23.1.0	Die Option `reusePort` wird unterstützt.
v15.8.0	Unterstützung für AbortSignal wurde hinzugefügt.
v11.4.0	Die Option `ipv6Only` wird unterstützt.
v8.7.0	Die Optionen `recvBufferSize` und `sendBufferSize` werden jetzt unterstützt.
v8.6.0	Die Option `lookup` wird unterstützt.
v0.11.13	Hinzugefügt in: v0.11.13

options <Objekt> Verfügbare Optionen sind:
- type <string> Die Familie des Sockets. Muss entweder 'udp4' oder 'udp6' sein. Erforderlich.
- reuseAddr <boolean> Wenn true, wird socket.bind() die Adresse wiederverwenden, selbst wenn ein anderer Prozess bereits einen Socket darauf gebunden hat, aber nur ein Socket kann die Daten empfangen. Standardwert: false.
- reusePort <boolean> Wenn true, wird socket.bind() den Port wiederverwenden, selbst wenn ein anderer Prozess bereits einen Socket darauf gebunden hat. Eingehende Datagramme werden an die wartenden Sockets verteilt. Die Option ist nur auf einigen Plattformen verfügbar, wie z. B. Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4 und AIX 7.2.5+. Auf nicht unterstützten Plattformen löst diese Option einen Fehler aus, wenn der Socket gebunden wird. Standardwert: false.
- ipv6Only <boolean> Durch Setzen von ipv6Only auf true wird die Dual-Stack-Unterstützung deaktiviert, d. h. die Bindung an die Adresse :: führt nicht dazu, dass 0.0.0.0 gebunden wird. Standardwert: false.
- recvBufferSize <number> Legt den SO_RCVBUF-Socketwert fest.
- sendBufferSize <number> Legt den SO_SNDBUF-Socketwert fest.
- lookup <Funktion> Benutzerdefinierte Lookup-Funktion. Standardwert: dns.lookup().
- signal <AbortSignal> Ein AbortSignal, das verwendet werden kann, um einen Socket zu schließen.
- receiveBlockList <net.BlockList> receiveBlockList kann verwendet werden, um eingehende Datagramme an bestimmte IP-Adressen, IP-Bereiche oder IP-Subnetze zu verwerfen. Dies funktioniert nicht, wenn der Server hinter einem Reverse-Proxy, NAT usw. steht, da die gegen die Blockliste überprüfte Adresse die Adresse des Proxys oder die vom NAT angegebene Adresse ist.
- sendBlockList <net.BlockList> sendBlockList kann verwendet werden, um den ausgehenden Zugriff auf bestimmte IP-Adressen, IP-Bereiche oder IP-Subnetze zu deaktivieren.
callback <Funktion> Als Listener für 'message'-Ereignisse angehängt. Optional.
Rückgabewert: <dgram.Socket>

Erstellt ein dgram.Socket-Objekt. Nachdem der Socket erstellt wurde, weist der Aufruf von socket.bind() den Socket an, mit dem Lauschen auf Datagrammnachrichten zu beginnen. Wenn address und port nicht an socket.bind() übergeben werden, bindet die Methode den Socket an die Adresse "alle Schnittstellen" an einem zufälligen Port (sie macht das Richtige für sowohl udp4 als auch udp6-Sockets). Die gebundene Adresse und der Port können mit socket.address().address und socket.address().port abgerufen werden.

Wenn die Option signal aktiviert ist, ist der Aufruf von .abort() auf dem entsprechenden AbortController ähnlich dem Aufruf von .close() auf dem 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}`)
})
// Später, wenn Sie den Server schließen möchten.
controller.abort()

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

Hinzugefügt in: v0.1.99

type <string> Entweder 'udp4' oder 'udp6'.
callback <Function> Angehängt als Listener für 'message'-Ereignisse.
Gibt zurück: <dgram.Socket>

Erstellt ein dgram.Socket-Objekt des angegebenen Typs.

Sobald der Socket erstellt wurde, bewirkt ein Aufruf von socket.bind(), dass der Socket beginnt, auf Datagramm-Nachrichten zu lauschen. Wenn address und port nicht an socket.bind() übergeben werden, bindet die Methode den Socket an die Adresse "alle Schnittstellen" an einem zufälligen Port (es funktioniert korrekt für sowohl udp4 als auch udp6 Sockets). Die gebundene Adresse und der Port können mit socket.address().address und socket.address().port abgerufen werden.

UDP/Datagram-Sockets ​

Klasse: dgram.Socket ​

Ereignis: 'close' ​

Ereignis: 'connect' ​

Ereignis: 'error' ​

Ereignis: 'listening' ​

Ereignis: '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]) ​

Hinweis zur Größe von UDP-Datagrammen ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

Beispiel: Ausgehendes IPv6-Multicast-Interface ​

Beispiel: Ausgehendes IPv4-Multicast-Interface ​

Aufrufergebnisse ​

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

node:dgram Modulfunktionen ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

UDP/Datagram-Sockets

Klasse: `dgram.Socket`

Ereignis: `'close'`

Ereignis: `'connect'`

Ereignis: `'error'`

Ereignis: `'listening'`

Ereignis: `'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])`

Hinweis zur Größe von UDP-Datagrammen

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

Beispiel: Ausgehendes IPv6-Multicast-Interface

Beispiel: Ausgehendes IPv4-Multicast-Interface

Aufrufergebnisse

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

`node:dgram` Modulfunktionen

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

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