Sockets UDP/datagram

[Estável: 2 - Estável]

Código-fonte: lib/dgram.js

O módulo node:dgram fornece uma implementação de sockets datagram UDP.

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

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

server.on('message', (msg, rinfo) => {
  console.log(`servidor recebeu: ${msg} de ${rinfo.address}:${rinfo.port}`)
})

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

server.bind(41234)
// Imprime: servidor ouvindo 0.0.0.0:41234

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

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

server.on('message', (msg, rinfo) => {
  console.log(`servidor recebeu: ${msg} de ${rinfo.address}:${rinfo.port}`)
})

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

server.bind(41234)
// Imprime: servidor ouvindo 0.0.0.0:41234

Classe: `dgram.Socket`

Adicionado em: v0.1.99

Estende: <EventEmitter>

Encapsula a funcionalidade de datagrama.

Novas instâncias de dgram.Socket são criadas usando dgram.createSocket(). A palavra-chave new não deve ser usada para criar instâncias de dgram.Socket.

Evento: `'close'`

Adicionado em: v0.1.99

O evento 'close' é emitido depois que um socket é fechado com close(). Uma vez acionado, nenhum novo evento 'message' será emitido neste socket.

Evento: `'connect'`

Adicionado em: v12.0.0

O evento 'connect' é emitido depois que um socket é associado a um endereço remoto como resultado de uma chamada bem-sucedida de connect().

Evento: `'error'`

Adicionado em: v0.1.99

exception <Error>

O evento 'error' é emitido sempre que ocorre algum erro. A função do manipulador de eventos recebe um único objeto Error.

Evento: `'listening'`

Adicionado em: v0.1.99

O evento 'listening' é emitido assim que o dgram.Socket é endereçável e pode receber dados. Isso acontece explicitamente com socket.bind() ou implicitamente na primeira vez que os dados são enviados usando socket.send(). Até que o dgram.Socket esteja ouvindo, os recursos do sistema subjacente não existem e chamadas como socket.address() e socket.setTTL() falharão.

Evento: `'message'`

[Histórico]

Versão	Mudanças
v18.4.0	A propriedade `family` agora retorna uma string em vez de um número.
v18.0.0	A propriedade `family` agora retorna um número em vez de uma string.
v0.1.99	Adicionado em: v0.1.99

O evento 'message' é emitido quando um novo datagrama está disponível em um socket. A função do manipulador de eventos recebe dois argumentos: msg e rinfo.

msg <Buffer> A mensagem.
rinfo <Object> Informações de endereço remoto.
- address <string> O endereço do remetente.
- family <string> A família de endereços ('IPv4' ou 'IPv6').
- port <number> A porta do remetente.
- size <number> O tamanho da mensagem.

Se o endereço de origem do pacote de entrada for um endereço IPv6 link-local, o nome da interface será adicionado ao address. Por exemplo, um pacote recebido na interface en0 pode ter o campo de endereço definido como 'fe80::2618:1234:ab11:3b9c%en0', onde '%en0' é o nome da interface como um sufixo de ID de zona.

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

Adicionado em: v0.6.9

multicastAddress <string>
multicastInterface <string>

Informa ao kernel para entrar em um grupo multicast no multicastAddress e multicastInterface fornecidos, usando a opção de socket IP_ADD_MEMBERSHIP. Se o argumento multicastInterface não for especificado, o sistema operacional escolherá uma interface e adicionará a participação a ela. Para adicionar participação a todas as interfaces disponíveis, chame addMembership várias vezes, uma vez por interface.

Quando chamado em um socket não vinculado, este método se vinculará implicitamente a uma porta aleatória, ouvindo em todas as interfaces.

Ao compartilhar um socket UDP entre vários workers do cluster, a função socket.addMembership() deve ser chamada apenas uma vez ou ocorrerá um erro EADDRINUSE:

ESMCJS

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

if (cluster.isPrimary) {
  cluster.fork() // Funciona ok.
  cluster.fork() // Falha com 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() // Funciona ok.
  cluster.fork() // Falha com EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

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

Adicionado em: v13.1.0, v12.16.0

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

Informa ao kernel para entrar em um canal multicast específico de origem no sourceAddress e groupAddress fornecidos, usando o multicastInterface com a opção de socket IP_ADD_SOURCE_MEMBERSHIP. Se o argumento multicastInterface não for especificado, o sistema operacional escolherá uma interface e adicionará a participação a ela. Para adicionar participação a todas as interfaces disponíveis, chame socket.addSourceSpecificMembership() várias vezes, uma vez por interface.

Quando chamado em um socket não vinculado, este método se vinculará implicitamente a uma porta aleatória, ouvindo em todas as interfaces.

`socket.address()`

Adicionado em: v0.1.99

Retorna: <Objeto>

Retorna um objeto contendo as informações de endereço para um socket. Para sockets UDP, este objeto conterá as propriedades address, family e port.

Este método lança EBADF se chamado em um socket não vinculado.

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

[Histórico]

Versão	Mudanças
v0.9.1	O método foi alterado para um modelo de execução assíncrona. O código legado precisaria ser alterado para passar uma função de callback para a chamada do método.
v0.1.99	Adicionado em: v0.1.99

port <integer>
address <string>
callback <Função> sem parâmetros. Chamada quando a vinculação é concluída.

Para sockets UDP, faz com que o dgram.Socket fique à escuta de mensagens de datagrama em uma porta nomeada e um endereço opcional. Se port não for especificado ou for 0, o sistema operacional tentará vincular a uma porta aleatória. Se address não for especificado, o sistema operacional tentará escutar em todos os endereços. Uma vez que a vinculação é concluída, um evento 'listening' é emitido e a função callback opcional é chamada.

Especificar um listener de evento 'listening' e passar um callback para o método socket.bind() não é prejudicial, mas não é muito útil.

Um socket de datagrama vinculado mantém o processo do Node.js em execução para receber mensagens de datagrama.

Se a vinculação falhar, um evento 'error' é gerado. Em casos raros (por exemplo, tentar vincular com um socket fechado), um Error pode ser lançado.

Exemplo de um servidor UDP escutando na porta 41234:

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

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

server.on('message', (msg, rinfo) => {
  console.log(`o servidor recebeu: ${msg} de ${rinfo.address}:${rinfo.port}`)
})

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

server.bind(41234)
// Imprime: servidor escutando 0.0.0.0:41234

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

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

server.on('message', (msg, rinfo) => {
  console.log(`o servidor recebeu: ${msg} de ${rinfo.address}:${rinfo.port}`)
})

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

server.bind(41234)
// Imprime: servidor escutando 0.0.0.0:41234

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

Adicionado em: v0.11.14

options <Objeto> Obrigatório. Suporta as seguintes propriedades:
- port <integer>
- address <string>
- exclusive <boolean>
- fd <integer>
callback <Function>

Para sockets UDP, faz com que o dgram.Socket escute mensagens de datagrama em uma porta nomeada e um endereço opcional que são passados como propriedades de um objeto options passado como o primeiro argumento. Se port não for especificado ou for 0, o sistema operacional tentará vincular a uma porta aleatória. Se address não for especificado, o sistema operacional tentará escutar em todos os endereços. Uma vez que a vinculação é concluída, um evento 'listening' é emitido e a função callback opcional é chamada.

O objeto options pode conter uma propriedade fd. Quando um fd maior que 0 é definido, ele envolverá um socket existente com o descritor de arquivo fornecido. Nesse caso, as propriedades de port e address serão ignoradas.

Especificar um ouvinte de evento 'listening' e passar um callback para o método socket.bind() não é prejudicial, mas não é muito útil.

O objeto options pode conter uma propriedade adicional exclusive que é usada ao usar objetos dgram.Socket com o módulo cluster. Quando exclusive é definido como false (o padrão), os workers do cluster usarão o mesmo manipulador de socket subjacente, permitindo que as tarefas de tratamento de conexão sejam compartilhadas. Quando exclusive é true, no entanto, o manipulador não é compartilhado e a tentativa de compartilhamento de porta resulta em um erro. Criar um dgram.Socket com a opção reusePort definida como true faz com que exclusive seja sempre true quando socket.bind() é chamado.

Um socket de datagrama vinculado mantém o processo Node.js em execução para receber mensagens de datagrama.

Se a vinculação falhar, um evento 'error' é gerado. Em casos raros (por exemplo, tentar vincular com um socket fechado), um Error pode ser lançado.

Um exemplo de socket escutando em uma porta exclusiva é mostrado abaixo.

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

`socket.close([callback])`

Adicionado em: v0.1.99

callback <Function> Chamado quando o socket foi fechado.

Fecha o socket subjacente e para de escutar dados nele. Se um callback for fornecido, ele é adicionado como um listener para o evento 'close'.

`socket[Symbol.asyncDispose]()`

Adicionado em: v20.5.0, v18.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Chama socket.close() e retorna uma promise que é cumprida quando o socket é fechado.

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

Adicionado em: v12.0.0

port <integer>
address <string>
callback <Function> Chamado quando a conexão é concluída ou em erro.

Associa o dgram.Socket a um endereço e porta remotos. Toda mensagem enviada por este manipulador é automaticamente enviada para esse destino. Além disso, o socket só receberá mensagens daquele peer remoto. Tentar chamar connect() em um socket já conectado resultará em uma exceção ERR_SOCKET_DGRAM_IS_CONNECTED. Se address não for fornecido, '127.0.0.1' (para sockets udp4) ou '::1' (para sockets udp6) serão usados por padrão. Uma vez que a conexão seja concluída, um evento 'connect' é emitido e a função callback opcional é chamada. Em caso de falha, o callback é chamado ou, em caso de falha, um evento 'error' é emitido.

`socket.disconnect()`

Adicionado em: v12.0.0

Uma função síncrona que desassocia um dgram.Socket conectado de seu endereço remoto. Tentar chamar disconnect() em um socket não vinculado ou já desconectado resultará em uma exceção ERR_SOCKET_DGRAM_NOT_CONNECTED.

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

Adicionado em: v0.6.9

multicastAddress <string>
multicastInterface <string>

Instrui o kernel a deixar um grupo multicast em multicastAddress usando a opção de socket IP_DROP_MEMBERSHIP. Este método é chamado automaticamente pelo kernel quando o socket é fechado ou o processo termina, portanto, a maioria dos aplicativos nunca terá motivos para chamar isso.

Se multicastInterface não for especificado, o sistema operacional tentará descartar a associação em todas as interfaces válidas.

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

Adicionado em: v13.1.0, v12.16.0

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

Instrui o kernel a deixar um canal multicast específico de origem no sourceAddress e groupAddress fornecidos usando a opção de socket IP_DROP_SOURCE_MEMBERSHIP. Este método é chamado automaticamente pelo kernel quando o socket é fechado ou o processo termina, portanto, a maioria dos aplicativos nunca terá motivos para chamar isso.

Se multicastInterface não for especificado, o sistema operacional tentará descartar a associação em todas as interfaces válidas.

`socket.getRecvBufferSize()`

Adicionado em: v8.7.0

Retorna: <number> o tamanho do buffer de recebimento do socket SO_RCVBUF em bytes.

Este método lança ERR_SOCKET_BUFFER_SIZE se chamado em um socket não vinculado.

`socket.getSendBufferSize()`

Adicionado em: v8.7.0

Retorna: <number> o tamanho do buffer de envio do socket SO_SNDBUF em bytes.

Este método lança ERR_SOCKET_BUFFER_SIZE se chamado em um socket não vinculado.

`socket.getSendQueueSize()`

Adicionado em: v18.8.0, v16.19.0

Retorna: <number> Número de bytes enfileirados para envio.

`socket.getSendQueueCount()`

Adicionado em: v18.8.0, v16.19.0

Retorna: <number> Número de solicitações de envio atualmente na fila aguardando processamento.

`socket.ref()`

Adicionado em: v0.9.1

Retorna: <dgram.Socket>

Por padrão, vincular um socket fará com que ele impeça o processo do Node.js de sair enquanto o socket estiver aberto. O método socket.unref() pode ser usado para excluir o socket da contagem de referência que mantém o processo do Node.js ativo. O método socket.ref() adiciona o socket de volta à contagem de referência e restaura o comportamento padrão.

Chamar socket.ref() várias vezes não terá nenhum efeito adicional.

O método socket.ref() retorna uma referência ao socket para que as chamadas possam ser encadeadas.

`socket.remoteAddress()`

Adicionado em: v12.0.0

Retorna: <Object>

Retorna um objeto contendo o address, family e port do ponto de extremidade remoto. Este método lança uma exceção ERR_SOCKET_DGRAM_NOT_CONNECTED se o socket não estiver conectado.

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

[Histórico]

Versão	Alterações
v17.0.0	O parâmetro `address` agora aceita apenas uma `string`, `null` ou `undefined`.
v14.5.0, v12.19.0	O parâmetro `msg` agora pode ser qualquer `TypedArray` ou `DataView`.
v12.0.0	Adicionado suporte para envio de dados em sockets conectados.
v8.0.0	O parâmetro `msg` agora pode ser um `Uint8Array`.
v8.0.0	O parâmetro `address` agora é sempre opcional.
v6.0.0	Em caso de sucesso, o `callback` agora será chamado com um argumento `error` de `null` em vez de `0`.
v5.7.0	O parâmetro `msg` agora pode ser um array. Além disso, os parâmetros `offset` e `length` agora são opcionais.
v0.1.99	Adicionado em: v0.1.99

msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> Mensagem a ser enviada.
offset <integer> Deslocamento no buffer onde a mensagem começa.
length <integer> Número de bytes na mensagem.
port <integer> Porta de destino.
address <string> Nome do host de destino ou endereço IP.
callback <Function> Chamado quando a mensagem foi enviada.

Transmite um datagrama no socket. Para sockets sem conexão, a port e o address de destino devem ser especificados. Sockets conectados, por outro lado, usarão seu ponto de extremidade remoto associado, portanto, os argumentos port e address não devem ser definidos.

O argumento msg contém a mensagem a ser enviada. Dependendo de seu tipo, comportamentos diferentes podem ser aplicados. Se msg for um Buffer, qualquer TypedArray ou um DataView, o offset e o length especificam o deslocamento dentro do Buffer onde a mensagem começa e o número de bytes na mensagem, respectivamente. Se msg for uma String, ela será convertida automaticamente em um Buffer com codificação 'utf8'. Com mensagens que contêm caracteres multibyte, offset e length serão calculados com relação ao comprimento do byte e não à posição do caractere. Se msg for um array, offset e length não devem ser especificados.

O argumento address é uma string. Se o valor de address for um nome de host, o DNS será usado para resolver o endereço do host. Se address não for fornecido ou for nulo, '127.0.0.1' (para sockets udp4) ou '::1' (para sockets udp6) será usado por padrão.

Se o socket não tiver sido vinculado anteriormente com uma chamada para bind, o socket recebe um número de porta aleatório e é vinculado ao endereço "todas as interfaces" ('0.0.0.0' para sockets udp4, '::0' para sockets udp6.)

Uma função callback opcional pode ser especificada como uma forma de relatar erros de DNS ou para determinar quando é seguro reutilizar o objeto buf. As pesquisas de DNS atrasam o tempo para enviar por pelo menos um tick do loop de eventos do Node.js.

A única maneira de saber com certeza que o datagrama foi enviado é usando um callback. Se ocorrer um erro e um callback for fornecido, o erro será passado como o primeiro argumento para o callback. Se um callback não for fornecido, o erro é emitido como um evento 'error' no objeto socket.

Offset e length são opcionais, mas ambos devem ser definidos se algum for usado. Eles são suportados apenas quando o primeiro argumento é um Buffer, um TypedArray ou um DataView.

Este método lança ERR_SOCKET_BAD_PORT se for chamado em um socket não vinculado.

Exemplo de envio de um pacote UDP para uma porta em 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()
})

Exemplo de envio de um pacote UDP composto por vários buffers para uma porta em 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()
})

O envio de vários buffers pode ser mais rápido ou mais lento dependendo da aplicação e do sistema operacional. Execute benchmarks para determinar a estratégia ideal caso a caso. Em geral, no entanto, o envio de vários buffers é mais rápido.

Exemplo de envio de um pacote UDP usando um socket conectado a uma porta em 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()
  })
})

Observação sobre o tamanho do datagrama UDP

O tamanho máximo de um datagrama IPv4/v6 depende da MTU (Maximum Transmission Unit - Unidade Máxima de Transmissão) e do tamanho do campo Payload Length (Comprimento da Carga Útil).

O campo Payload Length tem 16 bits de largura, o que significa que uma carga útil normal não pode exceder 64K octetos incluindo o cabeçalho da internet e os dados (65.507 bytes = 65.535 − 8 bytes de cabeçalho UDP − 20 bytes de cabeçalho IP); isso geralmente é verdade para interfaces de loopback, mas mensagens de datagramas tão longas são impraticáveis para a maioria dos hosts e redes.
A MTU é o maior tamanho que uma determinada tecnologia de camada de enlace pode suportar para mensagens de datagrama. Para qualquer enlace, o IPv4 exige uma MTU mínima de 68 octetos, enquanto a MTU recomendada para IPv4 é 576 (tipicamente recomendada como a MTU para aplicações do tipo discagem), quer cheguem inteiros ou em fragmentos. Para IPv6, a MTU mínima é de 1280 octetos. No entanto, o tamanho obrigatório mínimo do buffer de remontagem de fragmentos é de 1500 octetos. O valor de 68 octetos é muito pequeno, já que a maioria das tecnologias de camada de enlace atuais, como Ethernet, têm uma MTU mínima de 1500.

É impossível saber com antecedência a MTU de cada enlace pelo qual um pacote pode viajar. O envio de um datagrama maior que a MTU do recetor não funcionará porque o pacote será descartado silenciosamente sem informar a origem de que os dados não chegaram ao destinatário pretendido.

`socket.setBroadcast(flag)`

Adicionado em: v0.6.9

flag <boolean>

Define ou limpa a opção de socket SO_BROADCAST. Quando definido como true, os pacotes UDP podem ser enviados para o endereço de transmissão de uma interface local.

Este método lança EBADF se chamado num socket não associado.

`socket.setMulticastInterface(multicastInterface)`

Adicionado em: v8.6.0

multicastInterface <string>

Todas as referências ao escopo nesta seção referem-se a Índices de Zona IPv6, que são definidos por RFC 4007. Em formato de string, um IP com um índice de escopo é escrito como 'IP%scope' onde scope é um nome de interface ou número de interface.

Define a interface de multicast de saída padrão do socket para uma interface escolhida ou de volta para a seleção de interface do sistema. A multicastInterface deve ser uma representação de string válida de um IP da família do socket.

Para sockets IPv4, este deve ser o IP configurado para a interface física desejada. Todos os pacotes enviados para multicast no socket serão enviados na interface determinada pela utilização bem-sucedida mais recente desta chamada.

Para sockets IPv6, multicastInterface deve incluir um escopo para indicar a interface como nos exemplos que se seguem. Em IPv6, as chamadas send individuais também podem usar escopo explícito em endereços, pelo que apenas os pacotes enviados para um endereço multicast sem especificar um escopo explícito são afetados pela utilização bem-sucedida mais recente desta chamada.

Este método lança EBADF se chamado num socket não associado.

Exemplo: Interface de multicast de saída IPv6

Na maioria dos sistemas, onde o formato do escopo usa o nome da interface:

const socket = dgram.createSocket('udp6')

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

No Windows, onde o formato do escopo usa um número de interface:

const socket = dgram.createSocket('udp6')

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

Exemplo: Interface de multicast de saída IPv4

Todos os sistemas usam um IP do host na interface física desejada:

const socket = dgram.createSocket('udp4')

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

Resultados da chamada

Uma chamada em um socket que não está pronto para enviar ou não está mais aberto pode lançar um Error Not running.

Se multicastInterface não puder ser analisado em um IP, então um System Error EINVAL é lançado.

No IPv4, se multicastInterface for um endereço válido, mas não corresponder a nenhuma interface, ou se o endereço não corresponder à família, um System Error como EADDRNOTAVAIL ou EPROTONOSUP é lançado.

No IPv6, a maioria dos erros ao especificar ou omitir o escopo fará com que o socket continue usando (ou retornando para) a seleção de interface padrão do sistema.

O endereço ANY da família de endereços de um socket (IPv4 '0.0.0.0' ou IPv6 '::') pode ser usado para retornar o controle da interface de saída padrão do socket para o sistema para futuros pacotes de multicast.

`socket.setMulticastLoopback(flag)`

Adicionado em: v0.3.8

flag <boolean>

Define ou limpa a opção de socket IP_MULTICAST_LOOP. Quando definido como true, pacotes de multicast também serão recebidos na interface local.

Este método lança EBADF se chamado em um socket não vinculado.

`socket.setMulticastTTL(ttl)`

Adicionado em: v0.3.8

ttl <integer>

Define a opção de socket IP_MULTICAST_TTL. Embora TTL geralmente signifique "Time to Live" (Tempo de Vida), neste contexto, ele especifica o número de saltos IP que um pacote tem permissão para percorrer, especificamente para tráfego multicast. Cada roteador ou gateway que encaminha um pacote decrementa o TTL. Se o TTL for decrementado para 0 por um roteador, ele não será encaminhado.

O argumento ttl pode estar entre 0 e 255. O padrão na maioria dos sistemas é 1.

Este método lança EBADF se chamado em um socket não vinculado.

`socket.setRecvBufferSize(size)`

Adicionado em: v8.7.0

size <integer>

Define a opção de socket SO_RCVBUF. Define o tamanho máximo do buffer de recebimento do socket em bytes.

Este método lança ERR_SOCKET_BUFFER_SIZE se chamado em um socket não vinculado.

`socket.setSendBufferSize(size)`

Adicionado em: v8.7.0

size <integer>

Define a opção de socket SO_SNDBUF. Define o tamanho máximo do buffer de envio do socket em bytes.

Este método lança ERR_SOCKET_BUFFER_SIZE se chamado em um socket não vinculado.

`socket.setTTL(ttl)`

Adicionado em: v0.1.101

ttl <integer>

Define a opção de socket IP_TTL. Embora TTL geralmente signifique "Tempo de Vida", neste contexto especifica o número de saltos IP que um pacote pode percorrer. Cada roteador ou gateway que encaminha um pacote decrementa o TTL. Se o TTL for decrementado para 0 por um roteador, ele não será encaminhado. A alteração dos valores de TTL é normalmente feita para sondagens de rede ou durante o multicast.

O argumento ttl pode estar entre 1 e 255. O padrão na maioria dos sistemas é 64.

Este método lança EBADF se chamado em um socket não vinculado.

`socket.unref()`

Adicionado em: v0.9.1

Retorna: <dgram.Socket>

Por padrão, vincular um socket fará com que ele impeça o processo do Node.js de sair enquanto o socket estiver aberto. O método socket.unref() pode ser usado para excluir o socket da contagem de referências que mantém o processo do Node.js ativo, permitindo que o processo saia mesmo que o socket ainda esteja escutando.

Chamar socket.unref() várias vezes não terá efeito adicional.

O método socket.unref() retorna uma referência ao socket para que as chamadas possam ser encadeadas.

Funções do módulo `node:dgram`

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

[Histórico]

Versão	Alterações
v23.1.0	A opção `reusePort` é suportada.
v15.8.0	Foi adicionado suporte para AbortSignal.
v11.4.0	A opção `ipv6Only` é suportada.
v8.7.0	As opções `recvBufferSize` e `sendBufferSize` agora são suportadas.
v8.6.0	A opção `lookup` é suportada.
v0.11.13	Adicionado em: v0.11.13

options <Objeto> As opções disponíveis são:
- type <string> A família de socket. Deve ser 'udp4' ou 'udp6'. Obrigatório.
- reuseAddr <boolean> Quando true, socket.bind() reutilizará o endereço, mesmo que outro processo já tenha vinculado um socket a ele, mas apenas um socket pode receber os dados. Padrão: false.
- reusePort <boolean> Quando true, socket.bind() reutilizará a porta, mesmo que outro processo já tenha vinculado um socket a ela. Datagramas de entrada são distribuídos para sockets em escuta. A opção está disponível apenas em algumas plataformas, como Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4 e AIX 7.2.5+. Em plataformas não suportadas, essa opção gera um erro quando o socket é vinculado. Padrão: false.
- ipv6Only <boolean> Definir ipv6Only como true desativará o suporte a pilha dupla, ou seja, vincular ao endereço :: não fará com que 0.0.0.0 seja vinculado. Padrão: false.
- recvBufferSize <number> Define o valor do socket SO_RCVBUF.
- sendBufferSize <number> Define o valor do socket SO_SNDBUF.
- lookup <Função> Função de pesquisa personalizada. Padrão: dns.lookup().
- signal <AbortSignal> Um AbortSignal que pode ser usado para fechar um socket.
- receiveBlockList <net.BlockList> receiveBlockList pode ser usado para descartar datagramas de entrada para endereços IP, intervalos de IP ou sub-redes IP específicos. Isso não funciona se o servidor estiver atrás de um proxy reverso, NAT, etc. porque o endereço verificado em relação à lista de bloqueio é o endereço do proxy ou aquele especificado pelo NAT.
- sendBlockList <net.BlockList> sendBlockList pode ser usado para desabilitar o acesso de saída a endereços IP, intervalos de IP ou sub-redes IP específicos.
callback <Função> Anexado como um ouvinte para eventos 'message'. Opcional.
Retorna: <dgram.Socket>

Cria um objeto dgram.Socket. Depois que o socket é criado, chamar socket.bind() instruirá o socket a começar a escutar mensagens de datagramas. Quando address e port não são passados para socket.bind(), o método vinculará o socket ao endereço "todas as interfaces" em uma porta aleatória (ele faz a coisa certa para sockets udp4 e udp6). O endereço e a porta vinculados podem ser recuperados usando socket.address().address e socket.address().port.

Se a opção signal estiver habilitada, chamar .abort() no AbortController correspondente é semelhante a chamar .close() no socket:

const controller = new AbortController()
const { signal } = controller
const server = dgram.createSocket({ type: 'udp4', signal })
server.on('message', (msg, rinfo) => {
  console.log(`server recebeu: ${msg} de ${rinfo.address}:${rinfo.port}`)
})
// Mais tarde, quando você quiser fechar o servidor.
controller.abort()

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

Adicionado em: v0.1.99

type <string> Ou 'udp4' ou 'udp6'.
callback <Function> Anexado como um ouvinte para eventos 'message'.
Retorna: <dgram.Socket>

Cria um objeto dgram.Socket do type especificado.

Uma vez que o socket é criado, chamar socket.bind() irá instruir o socket a começar a escutar mensagens de datagrama. Quando address e port não são passados para socket.bind(), o método irá vincular o socket ao endereço de "todas as interfaces" em uma porta aleatória (ele faz a coisa certa tanto para sockets udp4 quanto udp6). O endereço e porta vinculados podem ser recuperados usando socket.address().address e socket.address().port.

Sockets 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]) ​

Observação sobre o tamanho do datagrama UDP ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

Exemplo: Interface de multicast de saída IPv6 ​

Exemplo: Interface de multicast de saída IPv4 ​

Resultados da chamada ​

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

Funções do módulo node:dgram ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

Sockets 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])`

Observação sobre o tamanho do datagrama UDP

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

Exemplo: Interface de multicast de saída IPv6

Exemplo: Interface de multicast de saída IPv4

Resultados da chamada

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

Funções do módulo `node:dgram`

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

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