UDP/데이터그램 소켓

[Stable: 2 - Stable]

소스 코드: lib/dgram.js

node:dgram 모듈은 UDP 데이터그램 소켓의 구현을 제공합니다.

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

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

server.on('message', (msg, rinfo) => {
  console.log(`서버 수신: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`서버 수신 대기 중 ${address.address}:${address.port}`)
})

server.bind(41234)
// 출력: server listening 0.0.0.0:41234

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

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

server.on('message', (msg, rinfo) => {
  console.log(`서버 수신: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`서버 수신 대기 중 ${address.address}:${address.port}`)
})

server.bind(41234)
// 출력: server listening 0.0.0.0:41234

클래스: `dgram.Socket`

추가됨: v0.1.99

상속: <EventEmitter>

데이터그램 기능을 캡슐화합니다.

dgram.Socket의 새 인스턴스는 dgram.createSocket()을 사용하여 생성됩니다. new 키워드는 dgram.Socket 인스턴스를 생성하는 데 사용해서는 안 됩니다.

이벤트: `'close'`

추가됨: v0.1.99

'close' 이벤트는 close()를 사용하여 소켓이 닫힌 후에 발생합니다. 이 이벤트가 발생하면 이 소켓에 대한 새 'message' 이벤트는 더 이상 발생하지 않습니다.

이벤트: `'connect'`

추가됨: v12.0.0

'connect' 이벤트는 성공적인 connect() 호출 결과로 소켓이 원격 주소에 연결된 후에 발생합니다.

이벤트: `'error'`

추가됨: v0.1.99

exception <Error>

'error' 이벤트는 오류가 발생할 때마다 방출됩니다. 이벤트 핸들러 함수에는 단일 Error 객체가 전달됩니다.

이벤트: `'listening'`

추가됨: v0.1.99

'listening' 이벤트는 dgram.Socket이 주소 지정 가능하고 데이터를 수신할 수 있게 되면 방출됩니다. 이는 socket.bind()를 사용하여 명시적으로 또는 socket.send()를 사용하여 데이터를 처음 보낼 때 암시적으로 발생합니다. dgram.Socket이 수신 대기 중이 아닐 때까지는 기본 시스템 리소스가 존재하지 않으며 socket.address() 및 socket.setTTL()과 같은 호출은 실패합니다.

이벤트: `'message'`

[이력]

버전	변경 사항
v18.4.0	`family` 속성이 이제 숫자가 아닌 문자열을 반환합니다.
v18.0.0	`family` 속성이 이제 문자열이 아닌 숫자를 반환합니다.
v0.1.99	추가됨: v0.1.99

'message' 이벤트는 소켓에서 새 데이터그램을 사용할 수 있을 때 방출됩니다. 이벤트 핸들러 함수에는 msg와 rinfo라는 두 개의 인수가 전달됩니다.

msg <Buffer> 메시지.
rinfo <Object> 원격 주소 정보.
- address <string> 보낸 사람 주소.
- family <string> 주소 패밀리('IPv4' 또는 'IPv6').
- port <number> 보낸 사람 포트.
- size <number> 메시지 크기.

수신 패킷의 소스 주소가 IPv6 링크 로컬 주소인 경우 인터페이스 이름이 address에 추가됩니다. 예를 들어 en0 인터페이스에서 수신된 패킷의 경우 주소 필드가 'fe80::2618:1234:ab11:3b9c%en0'으로 설정될 수 있으며, 여기서 '%en0'은 영역 ID 접미사로서의 인터페이스 이름입니다.

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

추가됨: v0.6.9

multicastAddress <string>
multicastInterface <string>

IP_ADD_MEMBERSHIP 소켓 옵션을 사용하여 지정된 multicastAddress 및 multicastInterface에서 멀티캐스트 그룹에 가입하도록 커널에 알립니다. multicastInterface 인수가 지정되지 않으면 운영 체제에서 인터페이스 하나를 선택하고 해당 인터페이스에 멤버십을 추가합니다. 사용 가능한 모든 인터페이스에 멤버십을 추가하려면 인터페이스당 한 번씩 addMembership를 여러 번 호출합니다.

바인딩되지 않은 소켓에서 호출하면 이 메서드는 모든 인터페이스에서 수신 대기하는 임의 포트에 암시적으로 바인딩됩니다.

여러 cluster 작업자 간에 UDP 소켓을 공유하는 경우 socket.addMembership() 함수는 한 번만 호출해야 합니다. 그렇지 않으면 EADDRINUSE 오류가 발생합니다.

ESMCJS

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

if (cluster.isPrimary) {
  cluster.fork() // 정상 작동합니다.
  cluster.fork() // 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() // 정상 작동합니다.
  cluster.fork() // EADDRINUSE 오류와 함께 실패합니다.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

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

추가됨: v13.1.0, v12.16.0

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

IP_ADD_SOURCE_MEMBERSHIP 소켓 옵션을 사용하여 지정된 sourceAddress 및 groupAddress에서 소스 특정 멀티캐스트 채널에 가입하도록 커널에 알립니다. multicastInterface 인수가 지정되지 않으면 운영 체제에서 인터페이스 하나를 선택하고 해당 인터페이스에 멤버십을 추가합니다. 사용 가능한 모든 인터페이스에 멤버십을 추가하려면 인터페이스당 한 번씩 socket.addSourceSpecificMembership()를 여러 번 호출합니다.

바인딩되지 않은 소켓에서 호출하면 이 메서드는 모든 인터페이스에서 수신 대기하는 임의 포트에 암시적으로 바인딩됩니다.

`socket.address()`

추가됨: v0.1.99

반환값: <Object>

소켓의 주소 정보가 담긴 객체를 반환합니다. UDP 소켓의 경우 이 객체에는 address, family, port 속성이 포함됩니다.

이 메서드는 바인딩되지 않은 소켓에서 호출하면 EBADF를 throw합니다.

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

[히스토리]

버전	변경 사항
v0.9.1	비동기 실행 모델로 메서드가 변경되었습니다. 레거시 코드는 메서드 호출에 콜백 함수를 전달하도록 변경해야 합니다.
v0.1.99	추가됨: v0.1.99

port <integer>
address <string>
callback 매개변수가 없는 <Function>. 바인딩이 완료되면 호출됩니다.

UDP 소켓의 경우, 지정된 port와 선택적 address에서 데이터그램 메시지를 수신하도록 dgram.Socket을 설정합니다. port가 지정되지 않았거나 0이면 운영 체제에서 임의 포트에 바인딩하려고 시도합니다. address가 지정되지 않으면 운영 체제에서 모든 주소에서 수신하려고 시도합니다. 바인딩이 완료되면 'listening' 이벤트가 발생하고 선택적 callback 함수가 호출됩니다.

'listening' 이벤트 리스너와 callback을 socket.bind() 메서드에 전달하는 것은 해롭지는 않지만 별로 유용하지 않습니다.

바인딩된 데이터그램 소켓은 데이터그램 메시지를 수신하기 위해 Node.js 프로세스를 실행 상태로 유지합니다.

바인딩에 실패하면 'error' 이벤트가 생성됩니다. 드문 경우(예: 닫힌 소켓으로 바인딩 시도) Error가 throw될 수 있습니다.

41234번 포트에서 수신 대기하는 UDP 서버의 예:

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)
// 출력: 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)
// 출력: server listening 0.0.0.0:41234

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

추가됨: v0.11.14

options <Object> 필수. 다음 속성을 지원합니다.
- port <integer>
- address <string>
- exclusive <boolean>
- fd <integer>
callback <Function>

UDP 소켓의 경우, options 객체의 속성으로 전달되는 명명된 port 및 선택적 address에서 데이터그램 메시지를 수신하도록 dgram.Socket을 수신 대기합니다. port가 지정되지 않았거나 0인 경우, 운영 체제는 임의 포트에 바인딩하려고 시도합니다. address가 지정되지 않은 경우, 운영 체제는 모든 주소에서 수신 대기하려고 시도합니다. 바인딩이 완료되면 'listening' 이벤트가 발생하고 선택적 callback 함수가 호출됩니다.

options 객체에는 fd 속성이 포함될 수 있습니다. fd가 0보다 큰 경우, 지정된 파일 디스크립터를 사용하여 기존 소켓을 래핑합니다. 이 경우 port 및 address 속성은 무시됩니다.

'listening' 이벤트 리스너와 socket.bind() 메서드에 callback을 전달하는 것을 모두 지정하는 것은 해롭지는 않지만 매우 유용하지는 않습니다.

options 객체에는 cluster 모듈을 사용하여 dgram.Socket 객체를 사용할 때 사용되는 추가 exclusive 속성이 포함될 수 있습니다. exclusive가 false(기본값)로 설정된 경우, 클러스터 워커는 동일한 기본 소켓 핸들을 사용하여 연결 처리 작업을 공유할 수 있습니다. 그러나 exclusive가 true인 경우, 핸들은 공유되지 않고 포트 공유 시도는 오류를 발생시킵니다. reusePort 옵션을 true로 설정하여 dgram.Socket을 생성하면 socket.bind()가 호출될 때 exclusive가 항상 true가 됩니다.

바인딩된 데이터그램 소켓은 데이터그램 메시지를 수신하기 위해 Node.js 프로세스를 실행 상태로 유지합니다.

바인딩에 실패하면 'error' 이벤트가 생성됩니다. 드문 경우(예: 닫힌 소켓으로 바인딩 시도) Error가 throw될 수 있습니다.

독점 포트에서 수신 대기하는 소켓 예제는 다음과 같습니다.

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

`socket.close([callback])`

추가됨: v0.1.99

callback <Function> 소켓이 닫히면 호출됩니다.

기본 소켓을 닫고 데이터 수신을 중지합니다. 콜백이 제공되면 'close' 이벤트에 대한 리스너로 추가됩니다.

`socket[Symbol.asyncDispose]()`

추가됨: v20.5.0, v18.18.0

[안정적: 1 - 실험적]

안정적: 1 안정성: 1 - 실험적

socket.close()를 호출하고 소켓이 닫히면 fulfilled되는 promise를 반환합니다.

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

추가됨: v12.0.0

port <integer>
address <string>
callback <Function> 연결이 완료되거나 오류 발생 시 호출됩니다.

dgram.Socket을 원격 주소와 포트에 연결합니다. 이 핸들에서 보낸 모든 메시지는 자동으로 해당 대상으로 전송됩니다. 또한, 소켓은 해당 원격 피어로부터만 메시지를 수신합니다. 이미 연결된 소켓에서 connect()를 호출하려고 하면 ERR_SOCKET_DGRAM_IS_CONNECTED 예외가 발생합니다. address가 제공되지 않으면 '127.0.0.1'(udp4 소켓의 경우) 또는 '::1'(udp6 소켓의 경우)이 기본적으로 사용됩니다. 연결이 완료되면 'connect' 이벤트가 발생하고 선택적 callback 함수가 호출됩니다. 실패할 경우 callback이 호출되거나, 이것이 실패하면 'error' 이벤트가 발생합니다.

`socket.disconnect()`

추가됨: v12.0.0

연결된 dgram.Socket을 원격 주소에서 분리하는 동기 함수입니다. 바인딩되지 않은 소켓이나 이미 연결이 끊긴 소켓에서 disconnect()를 호출하려고 하면 ERR_SOCKET_DGRAM_NOT_CONNECTED 예외가 발생합니다.

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

추가됨: v0.6.9

multicastAddress <string>
multicastInterface <string>

IP_DROP_MEMBERSHIP 소켓 옵션을 사용하여 multicastAddress에서 멀티캐스트 그룹을 나가도록 커널에 지시합니다. 이 메서드는 소켓이 닫히거나 프로세스가 종료될 때 커널에 의해 자동으로 호출되므로 대부분의 앱에서는 이 메서드를 호출할 필요가 없습니다.

multicastInterface가 지정되지 않으면 운영 체제는 모든 유효한 인터페이스에서 멤버십을 삭제하려고 시도합니다.

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

추가됨: v13.1.0, v12.16.0

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

IP_DROP_SOURCE_MEMBERSHIP 소켓 옵션을 사용하여 지정된 sourceAddress 및 groupAddress에서 소스 특정 멀티캐스트 채널을 나가도록 커널에 지시합니다. 이 메서드는 소켓이 닫히거나 프로세스가 종료될 때 커널에 의해 자동으로 호출되므로 대부분의 앱에서는 이 메서드를 호출할 필요가 없습니다.

multicastInterface가 지정되지 않으면 운영 체제는 모든 유효한 인터페이스에서 멤버십을 삭제하려고 시도합니다.

`socket.getRecvBufferSize()`

추가됨: v8.7.0

반환값: <number> SO_RCVBUF 소켓 수신 버퍼 크기(바이트).

이 메서드는 바인딩되지 않은 소켓에서 호출되면 ERR_SOCKET_BUFFER_SIZE를 throw합니다.

`socket.getSendBufferSize()`

추가됨: v8.7.0

반환값: <number> SO_SNDBUF 소켓 송신 버퍼 크기(바이트).

이 메서드는 바인딩되지 않은 소켓에서 호출되면 ERR_SOCKET_BUFFER_SIZE를 throw합니다.

`socket.getSendQueueSize()`

추가됨: v18.8.0, v16.19.0

반환값: <number> 전송 대기 중인 바이트 수

`socket.getSendQueueCount()`

추가됨: v18.8.0, v16.19.0

반환값: <number> 현재 처리 대기 중인 전송 요청 수

`socket.ref()`

추가됨: v0.9.1

반환값: <dgram.Socket>

기본적으로 소켓 바인딩은 소켓이 열려 있는 동안 Node.js 프로세스가 종료되는 것을 차단합니다. socket.unref() 메서드는 Node.js 프로세스를 활성 상태로 유지하는 참조 계산에서 소켓을 제외하는 데 사용할 수 있습니다. socket.ref() 메서드는 소켓을 참조 계산에 다시 추가하고 기본 동작을 복원합니다.

socket.ref()를 여러 번 호출해도 추가적인 효과는 없습니다.

socket.ref() 메서드는 소켓에 대한 참조를 반환하므로 호출을 연결할 수 있습니다.

`socket.remoteAddress()`

추가됨: v12.0.0

반환값: <Object>

원격 엔드포인트의 address, family, port를 포함하는 객체를 반환합니다. 소켓이 연결되어 있지 않으면 이 메서드는 ERR_SOCKET_DGRAM_NOT_CONNECTED 예외를 throw합니다.

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

[히스토리]

버전	변경 사항
v17.0.0	`address` 매개변수는 이제 `string`, `null` 또는 `undefined`만 허용합니다.
v14.5.0, v12.19.0	`msg` 매개변수는 이제 모든 `TypedArray` 또는 `DataView`가 될 수 있습니다.
v12.0.0	연결된 소켓에서 데이터 전송 지원 추가
v8.0.0	`msg` 매개변수는 이제 `Uint8Array`가 될 수 있습니다.
v8.0.0	`address` 매개변수는 이제 항상 선택 사항입니다.
v6.0.0	성공 시 `callback`은 이제 `0`이 아닌 `null`인 `error` 인수를 사용하여 호출됩니다.
v5.7.0	`msg` 매개변수는 이제 배열이 될 수 있습니다. 또한 `offset` 및 `length` 매개변수는 이제 선택 사항입니다.
v0.1.99	추가됨: v0.1.99

msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> 전송할 메시지.
offset <integer> 메시지가 시작되는 버퍼의 오프셋.
length <integer> 메시지의 바이트 수.
port <integer> 대상 포트.
address <string> 대상 호스트 이름 또는 IP 주소.
callback <Function> 메시지가 전송되었을 때 호출됨.

소켓에서 데이터그램을 브로드캐스트합니다. 연결되지 않은 소켓의 경우 대상 port 및 address를 지정해야 합니다. 반면 연결된 소켓은 연결된 원격 엔드포인트를 사용하므로 port 및 address 인수를 설정하면 안 됩니다.

msg 인수에는 전송할 메시지가 포함됩니다. 유형에 따라 다른 동작이 적용될 수 있습니다. msg가 Buffer, TypedArray 또는 DataView인 경우 offset 및 length는 메시지가 시작되는 Buffer 내의 오프셋과 메시지의 바이트 수를 각각 지정합니다. msg가 String인 경우 'utf8' 인코딩을 사용하여 자동으로 Buffer로 변환됩니다. 여러 바이트 문자를 포함하는 메시지의 경우 offset 및 length는 바이트 길이를 기준으로 계산되며 문자 위치를 기준으로 계산되지 않습니다. msg가 배열인 경우 offset 및 length를 지정하면 안 됩니다.

address 인수는 문자열입니다. address 값이 호스트 이름인 경우 DNS를 사용하여 호스트의 주소를 확인합니다. address가 제공되지 않거나 nullish인 경우 기본적으로 '127.0.0.1'(udp4 소켓의 경우) 또는 '::1'(udp6 소켓의 경우)이 사용됩니다.

bind를 호출하여 소켓을 이전에 바인딩하지 않은 경우 소켓에는 임의의 포트 번호가 할당되고 "모든 인터페이스" 주소(udp4 소켓의 경우 '0.0.0.0', udp6 소켓의 경우 '::0')에 바인딩됩니다.

DNS 오류를 보고하거나 buf 객체를 다시 사용해도 안전한 시점을 확인하는 방법으로 선택적 callback 함수를 지정할 수 있습니다. DNS 조회는 Node.js 이벤트 루프의 최소 한 티크만큼 전송 시간을 지연시킵니다.

데이터그램이 전송되었는지 확실히 알 수 있는 유일한 방법은 callback을 사용하는 것입니다. 오류가 발생하고 callback이 주어지면 오류가 callback의 첫 번째 인수로 전달됩니다. callback이 주어지지 않으면 오류는 socket 객체에 대한 'error' 이벤트로 방출됩니다.

Offset 및 length는 선택 사항이지만 둘 중 하나라도 사용하는 경우 모두 반드시 설정해야 합니다. 첫 번째 인수가 Buffer, TypedArray 또는 DataView인 경우에만 지원됩니다.

이 메서드는 바인딩되지 않은 소켓에서 호출하면 ERR_SOCKET_BAD_PORT를 throw합니다.

localhost의 포트로 UDP 패킷을 전송하는 예:

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

여러 버퍼로 구성된 UDP 패킷을 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()
})

여러 버퍼를 전송하는 것이 애플리케이션과 운영 체제에 따라 더 빠르거나 느릴 수 있습니다. 케이스별로 최적의 전략을 결정하려면 벤치마크를 실행하십시오. 그러나 일반적으로 여러 버퍼를 전송하는 것이 더 빠릅니다.

localhost의 포트에 연결된 소켓을 사용하여 UDP 패킷을 전송하는 예:

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

UDP 데이터그램 크기에 대한 참고

IPv4/v6 데이터그램의 최대 크기는 MTU(최대 전송 단위)와 Payload Length 필드 크기에 따라 달라집니다.

Payload Length 필드는 16비트 너비이며, 이는 일반적인 페이로드가 인터넷 헤더와 데이터를 포함하여 64K 바이트를 초과할 수 없음을 의미합니다(65,507바이트 = 65,535 - 8바이트 UDP 헤더 - 20바이트 IP 헤더). 이는 일반적으로 루프백 인터페이스에 해당하지만, 이렇게 긴 데이터그램 메시지는 대부분의 호스트와 네트워크에서는 실용적이지 않습니다.
MTU는 특정 링크 계층 기술이 데이터그램 메시지에 대해 지원할 수 있는 최대 크기입니다. 모든 링크에 대해 IPv4는 최소 68옥텟의 MTU를 요구하는 반면, IPv4에 대한 권장 MTU는 576입니다(일반적으로 다이얼업 유형 애플리케이션의 MTU로 권장됨). 이는 데이터그램이 전체적으로 도착하든 조각으로 도착하든 마찬가지입니다. IPv6의 경우 최소 MTU는 1280옥텟입니다. 그러나 필수 최소 조각 재조립 버퍼 크기는 1500옥텟입니다. 이더넷과 같은 대부분의 현재 링크 계층 기술은 최소 1500의 MTU를 가지므로 68옥텟 값은 매우 작습니다.

패킷이 통과할 수 있는 각 링크의 MTU를 미리 알 수 없습니다. 수신기 MTU보다 큰 데이터그램을 보내면 데이터가 예상 수신자에게 도달하지 못했다는 정보 없이 패킷이 자동으로 삭제되므로 작동하지 않습니다.

`socket.setBroadcast(flag)`

추가됨: v0.6.9

flag <boolean>

SO_BROADCAST 소켓 옵션을 설정하거나 해제합니다. true로 설정되면 UDP 패킷을 로컬 인터페이스의 브로드캐스트 주소로 보낼 수 있습니다.

이 메서드는 바인딩되지 않은 소켓에서 호출되면 EBADF를 throw합니다.

`socket.setMulticastInterface(multicastInterface)`

추가됨: v8.6.0

multicastInterface <string>

이 섹션에서 범위에 대한 모든 참조는 IPv6 영역 인덱스를 참조하며, RFC 4007에서 정의됩니다. 문자열 형태로 범위 인덱스가 있는 IP는 'IP%scope'로 작성되며, 여기서 scope는 인터페이스 이름 또는 인터페이스 번호입니다.

소켓의 기본 발신 멀티캐스트 인터페이스를 선택한 인터페이스로 설정하거나 시스템 인터페이스 선택으로 되돌립니다. multicastInterface는 소켓의 패밀리에서 유효한 IP의 문자열 표현이어야 합니다.

IPv4 소켓의 경우, 이것은 원하는 물리적 인터페이스에 대해 구성된 IP여야 합니다. 소켓에서 멀티캐스트로 전송되는 모든 패킷은 이 호출의 가장 최근 성공적인 사용에 의해 결정된 인터페이스에서 전송됩니다.

IPv6 소켓의 경우, multicastInterface는 다음 예와 같이 인터페이스를 나타내는 범위를 포함해야 합니다. IPv6에서 개별 send 호출은 주소에 명시적 범위를 사용할 수도 있으므로, 명시적 범위를 지정하지 않고 멀티캐스트 주소로 전송되는 패킷만 이 호출의 가장 최근 성공적인 사용의 영향을 받습니다.

이 메서드는 바인딩되지 않은 소켓에서 호출되면 EBADF를 throw합니다.

예제: IPv6 송신 멀티캐스트 인터페이스

대부분의 시스템에서 범위 형식이 인터페이스 이름을 사용하는 경우:

const socket = dgram.createSocket('udp6')

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

Windows에서 범위 형식이 인터페이스 번호를 사용하는 경우:

const socket = dgram.createSocket('udp6')

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

예제: IPv4 송신 멀티캐스트 인터페이스

모든 시스템은 원하는 물리적 인터페이스의 호스트 IP를 사용합니다.

const socket = dgram.createSocket('udp4')

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

호출 결과

송신할 준비가 되지 않았거나 더 이상 열려 있지 않은 소켓에서 호출하면 실행되지 않음 Error가 발생할 수 있습니다.

multicastInterface를 IP로 구문 분석할 수 없는 경우 EINVAL 시스템 오류가 발생합니다.

IPv4의 경우 multicastInterface가 유효한 주소이지만 인터페이스와 일치하지 않거나 주소가 패밀리와 일치하지 않는 경우 EADDRNOTAVAIL 또는 EPROTONOSUP과 같은 시스템 오류가 발생합니다.

IPv6의 경우 범위를 지정하거나 생략하는 대부분의 오류는 소켓이 시스템의 기본 인터페이스 선택을 계속 사용하거나(또는 되돌아가도록) 합니다.

소켓의 주소 패밀리의 ANY 주소(IPv4 '0.0.0.0' 또는 IPv6 '::')를 사용하여 향후 멀티캐스트 패킷에 대한 소켓의 기본 송신 인터페이스 제어를 시스템으로 되돌릴 수 있습니다.

`socket.setMulticastLoopback(flag)`

추가됨: v0.3.8

flag <boolean>

IP_MULTICAST_LOOP 소켓 옵션을 설정하거나 지웁니다. true로 설정하면 멀티캐스트 패킷이 로컬 인터페이스에서도 수신됩니다.

이 메서드는 바인딩되지 않은 소켓에서 호출되면 EBADF를 throw합니다.

`socket.setMulticastTTL(ttl)`

추가됨: v0.3.8

ttl <integer>

IP_MULTICAST_TTL 소켓 옵션을 설정합니다. TTL은 일반적으로 "Time to Live"를 의미하지만, 이 컨텍스트에서는 특히 멀티캐스트 트래픽에 대해 패킷이 이동할 수 있는 IP 홉 수를 지정합니다. 패킷을 전달하는 각 라우터 또는 게이트웨이는 TTL을 감소시킵니다. 라우터에서 TTL이 0으로 감소하면 전달되지 않습니다.

ttl 인수는 0과 255 사이일 수 있습니다. 대부분의 시스템에서 기본값은 1입니다.

이 메서드는 바인딩되지 않은 소켓에서 호출되면 EBADF를 throw합니다.

`socket.setRecvBufferSize(size)`

추가됨: v8.7.0

size <정수>

SO_RCVBUF 소켓 옵션을 설정합니다. 바이트 단위의 최대 소켓 수신 버퍼를 설정합니다.

이 메서드는 바인딩되지 않은 소켓에서 호출될 경우 ERR_SOCKET_BUFFER_SIZE를 throw합니다.

`socket.setSendBufferSize(size)`

추가됨: v8.7.0

size <정수>

SO_SNDBUF 소켓 옵션을 설정합니다. 바이트 단위의 최대 소켓 송신 버퍼를 설정합니다.

이 메서드는 바인딩되지 않은 소켓에서 호출될 경우 ERR_SOCKET_BUFFER_SIZE를 throw합니다.

`socket.setTTL(ttl)`

추가됨: v0.1.101

ttl <정수>

IP_TTL 소켓 옵션을 설정합니다. TTL은 일반적으로 "Time to Live"를 의미하지만, 이 컨텍스트에서는 패킷이 통과할 수 있는 IP 홉 수를 지정합니다. 각 라우터 또는 게이트웨이는 패킷을 전달할 때 TTL을 감소시킵니다. 라우터에서 TTL이 0으로 감소되면 전달되지 않습니다. TTL 값을 변경하는 것은 일반적으로 네트워크 프로브 또는 멀티캐스팅 시 수행됩니다.

ttl 인수는 1과 255 사이여야 합니다. 대부분의 시스템에서 기본값은 64입니다.

이 메서드는 바인딩되지 않은 소켓에서 호출될 경우 EBADF를 throw합니다.

`socket.unref()`

추가됨: v0.9.1

반환값: <dgram.Socket>

기본적으로 소켓을 바인딩하면 소켓이 열려 있는 동안 Node.js 프로세스가 종료되는 것을 차단합니다. socket.unref() 메서드는 Node.js 프로세스를 활성 상태로 유지하는 참조 계산에서 소켓을 제외하여 소켓이 계속 수신 중이더라도 프로세스가 종료될 수 있도록 합니다.

socket.unref()를 여러 번 호출해도 추가적인 효과는 없습니다.

socket.unref() 메서드는 소켓에 대한 참조를 반환하므로 호출을 연결할 수 있습니다.

`node:dgram` 모듈 함수

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

[히스토리]

버전	변경 사항
v23.1.0	`reusePort` 옵션 지원
v15.8.0	AbortSignal 지원 추가
v11.4.0	`ipv6Only` 옵션 지원
v8.7.0	`recvBufferSize` 및 `sendBufferSize` 옵션 지원
v8.6.0	`lookup` 옵션 지원
v0.11.13	추가됨: v0.11.13

options <Object> 사용 가능한 옵션은 다음과 같습니다.
- type <string> 소켓의 패밀리. 'udp4' 또는 'udp6' 중 하나여야 합니다. 필수입니다.
- reuseAddr <boolean> true이면 socket.bind()는 다른 프로세스가 이미 소켓에 바인딩한 경우에도 주소를 재사용하지만 하나의 소켓만 데이터를 수신할 수 있습니다. 기본값: false.
- reusePort <boolean> true이면 socket.bind()는 다른 프로세스가 이미 소켓에 바인딩한 경우에도 포트를 재사용합니다. 수신 데이터그램은 수신 대기 중인 소켓에 분산됩니다. 이 옵션은 Linux 3.9 이상, DragonFlyBSD 3.6 이상, FreeBSD 12.0 이상, Solaris 11.4 및 AIX 7.2.5 이상과 같은 일부 플랫폼에서만 사용할 수 있습니다. 지원되지 않는 플랫폼에서는 소켓이 바인딩될 때 이 옵션으로 인해 오류가 발생합니다. 기본값: false.
- ipv6Only <boolean> ipv6Only를 true로 설정하면 이중 스택 지원이 비활성화됩니다. 즉, :: 주소에 바인딩해도 0.0.0.0이 바인딩되지 않습니다. 기본값: false.
- recvBufferSize <number> SO_RCVBUF 소켓 값을 설정합니다.
- sendBufferSize <number> SO_SNDBUF 소켓 값을 설정합니다.
- lookup <Function> 사용자 정의 조회 함수. 기본값: dns.lookup().
- signal <AbortSignal> 소켓을 닫는 데 사용할 수 있는 AbortSignal.
- receiveBlockList <net.BlockList> receiveBlockList는 특정 IP 주소, IP 범위 또는 IP 서브넷으로 들어오는 데이터그램을 삭제하는 데 사용할 수 있습니다. 서버가 리버스 프록시, NAT 등 뒤에 있는 경우 블랙리스트에 대해 확인되는 주소는 프록시의 주소 또는 NAT에 의해 지정된 주소이기 때문에 작동하지 않습니다.
- sendBlockList <net.BlockList> sendBlockList는 특정 IP 주소, IP 범위 또는 IP 서브넷에 대한 아웃바운드 액세스를 비활성화하는 데 사용할 수 있습니다.
callback <Function> 'message' 이벤트에 대한 리스너로 연결됩니다. 선택 사항입니다.
반환값: <dgram.Socket>

dgram.Socket 객체를 만듭니다. 소켓이 생성되면 socket.bind()를 호출하여 소켓이 데이터그램 메시지를 수신 대기하도록 지시합니다. socket.bind()에 address 및 port가 전달되지 않으면 이 메서드는 무작위 포트의 "모든 인터페이스" 주소에 소켓을 바인딩합니다(udp4 및 udp6 소켓 모두에 대해 올바르게 작동합니다). 바인딩된 주소와 포트는 socket.address().address와 socket.address().port를 사용하여 검색할 수 있습니다.

signal 옵션이 활성화된 경우 해당 AbortController에서 .abort()를 호출하는 것은 소켓에서 .close()를 호출하는 것과 유사합니다.

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}`)
})
// 나중에 서버를 닫으려면
controller.abort()

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

추가됨: v0.1.99

type <string> 'udp4' 또는 'udp6' 중 하나입니다.
callback <Function> 'message' 이벤트에 리스너로 연결됩니다.
반환값: <dgram.Socket>

지정된 type의 dgram.Socket 객체를 생성합니다.

소켓이 생성되면 socket.bind()를 호출하여 데이터그램 메시지를 수신 대기하도록 소켓에 지시합니다. socket.bind()에 address와 port가 전달되지 않으면 이 메서드는 임의 포트의 "모든 인터페이스" 주소에 소켓을 바인딩합니다(udp4 및 udp6 소켓 모두에 대해 올바르게 작동합니다). 바인딩된 주소와 포트는 socket.address().address와 socket.address().port를 사용하여 가져올 수 있습니다.

UDP/데이터그램 소켓 ​

클래스: dgram.Socket ​

이벤트: 'close' ​

이벤트: 'connect' ​

이벤트: 'error' ​

이벤트: 'listening' ​

이벤트: '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]) ​

UDP 데이터그램 크기에 대한 참고 ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

예제: IPv6 송신 멀티캐스트 인터페이스 ​

예제: IPv4 송신 멀티캐스트 인터페이스 ​

호출 결과 ​

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

node:dgram 모듈 함수 ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

UDP/데이터그램 소켓

클래스: `dgram.Socket`

이벤트: `'close'`

이벤트: `'connect'`

이벤트: `'error'`

이벤트: `'listening'`

이벤트: `'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])`

UDP 데이터그램 크기에 대한 참고

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

예제: IPv6 송신 멀티캐스트 인터페이스

예제: IPv4 송신 멀티캐스트 인터페이스

호출 결과

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

`node:dgram` 모듈 함수

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

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