Class MulticastSocket

Readonlyaddresses

Readonlyinterfaces

Readonlyoptions

addressInfo

• get addressInfo(): AddressInfo[]

  Returns the address information for all underlying sockets (the multicast socket plus each per-interface unicast socket).

  Each entry contains address, family, and port properties.

  Returns AddressInfo[]

close

• close(): Promise<void>

  Closes all underlying sockets and stops listening for data. Drops multicast group membership on each interface before closing the multicast socket.

  Prefer destroy for full cleanup, which also removes all event listeners.

  Returns Promise<void>

destroy

• destroy(): Promise<void>

  Closes all underlying sockets and removes all event listeners from both the internal dgram sockets and this MulticastSocket instance. This is the recommended way to fully tear down a socket.

  Returns Promise<void>

off

• off(event: "close", listener: (local: AddressInfo) => void): this

  Removes a previously registered listener for the given event.

  Parameters

  • event: "close"

    the event name

  • listener: (local: AddressInfo) => void

    the callback to remove

  Returns this

• off(event: "connect", listener: (local: AddressInfo) => void): this

  Removes a previously registered listener for the given event.

  Parameters

  • event: "connect"

    the event name

  • listener: (local: AddressInfo) => void

    the callback to remove

  Returns this

• off(event: "error", listener: (error: Error, local?: AddressInfo) => void): this

  Removes a previously registered listener for the given event.

  Parameters

  • event: "error"

    the event name

  • listener: (error: Error, local?: AddressInfo) => void

    the callback to remove

  Returns this

• off(
      event: "message",
      listener: (
          message: Buffer,
          local: AddressInfo,
          remote: RemoteInfo,
          fromSelf: boolean,
      ) => void,
  ): this

  Removes a previously registered listener for the given event.

  Parameters

  • event: "message"

    the event name

  • listener: (
        message: Buffer,
        local: AddressInfo,
        remote: RemoteInfo,
        fromSelf: boolean,
    ) => void

    the callback to remove

  Returns this

• off(
      event: "drop",
      listener: (
          message: Buffer,
          local: AddressInfo,
          remote: RemoteInfo,
          reason: "off-link",
      ) => void,
  ): this

  Removes a previously registered listener for the given event.

  Parameters

  • event: "drop"

    the event name

  • listener: (
        message: Buffer,
        local: AddressInfo,
        remote: RemoteInfo,
        reason: "off-link",
    ) => void

    the callback to remove

  Returns this

on

• on(event: "close", listener: (local: AddressInfo) => void): this

  Registers a listener for the given event.

  Events:

  • 'message': emitted when a UDP message is received and passes all inbound filters. The listener receives the raw message buffer, the local AddressInfo of the receiving socket, the RemoteInfo of the sender, and a fromSelf boolean indicating whether the message originated from this instance.
  • 'drop': emitted when an inbound message is rejected by a filter. Currently the only reason is 'off-link' (RFC 6762 §11 link-local origin check failed while options.linkLocalOnly was true). The listener receives the message, the local address, the remote address, and the reason string.
  • 'close': emitted when an underlying socket is closed.
  • 'connect': emitted when an underlying socket connects.
  • 'error': emitted when an underlying socket encounters an error.

  Parameters

  • event: "close"

    the event name

  • listener: (local: AddressInfo) => void

    the callback to invoke when the event is emitted

  Returns this

• on(event: "connect", listener: (local: AddressInfo) => void): this

  Registers a listener for the given event.

  Events:

  • 'message': emitted when a UDP message is received and passes all inbound filters. The listener receives the raw message buffer, the local AddressInfo of the receiving socket, the RemoteInfo of the sender, and a fromSelf boolean indicating whether the message originated from this instance.
  • 'drop': emitted when an inbound message is rejected by a filter. Currently the only reason is 'off-link' (RFC 6762 §11 link-local origin check failed while options.linkLocalOnly was true). The listener receives the message, the local address, the remote address, and the reason string.
  • 'close': emitted when an underlying socket is closed.
  • 'connect': emitted when an underlying socket connects.
  • 'error': emitted when an underlying socket encounters an error.

  Parameters

  • event: "connect"

    the event name

  • listener: (local: AddressInfo) => void

    the callback to invoke when the event is emitted

  Returns this

• on(event: "error", listener: (error: Error, local?: AddressInfo) => void): this

  Registers a listener for the given event.

  Events:

  • 'message': emitted when a UDP message is received and passes all inbound filters. The listener receives the raw message buffer, the local AddressInfo of the receiving socket, the RemoteInfo of the sender, and a fromSelf boolean indicating whether the message originated from this instance.
  • 'drop': emitted when an inbound message is rejected by a filter. Currently the only reason is 'off-link' (RFC 6762 §11 link-local origin check failed while options.linkLocalOnly was true). The listener receives the message, the local address, the remote address, and the reason string.
  • 'close': emitted when an underlying socket is closed.
  • 'connect': emitted when an underlying socket connects.
  • 'error': emitted when an underlying socket encounters an error.

  Parameters

  • event: "error"

    the event name

  • listener: (error: Error, local?: AddressInfo) => void

    the callback to invoke when the event is emitted

  Returns this

• on(
      event: "message",
      listener: (
          message: Buffer,
          local: AddressInfo,
          remote: RemoteInfo,
          fromSelf: boolean,
      ) => void,
  ): this

  Registers a listener for the given event.

  Events:

  • 'message': emitted when a UDP message is received and passes all inbound filters. The listener receives the raw message buffer, the local AddressInfo of the receiving socket, the RemoteInfo of the sender, and a fromSelf boolean indicating whether the message originated from this instance.
  • 'drop': emitted when an inbound message is rejected by a filter. Currently the only reason is 'off-link' (RFC 6762 §11 link-local origin check failed while options.linkLocalOnly was true). The listener receives the message, the local address, the remote address, and the reason string.
  • 'close': emitted when an underlying socket is closed.
  • 'connect': emitted when an underlying socket connects.
  • 'error': emitted when an underlying socket encounters an error.

  Parameters

  • event: "message"

    the event name

  • listener: (
        message: Buffer,
        local: AddressInfo,
        remote: RemoteInfo,
        fromSelf: boolean,
    ) => void

    the callback to invoke when the event is emitted

  Returns this

• on(
      event: "drop",
      listener: (
          message: Buffer,
          local: AddressInfo,
          remote: RemoteInfo,
          reason: "off-link",
      ) => void,
  ): this

  Registers a listener for the given event.

  Events:

  • 'message': emitted when a UDP message is received and passes all inbound filters. The listener receives the raw message buffer, the local AddressInfo of the receiving socket, the RemoteInfo of the sender, and a fromSelf boolean indicating whether the message originated from this instance.
  • 'drop': emitted when an inbound message is rejected by a filter. Currently the only reason is 'off-link' (RFC 6762 §11 link-local origin check failed while options.linkLocalOnly was true). The listener receives the message, the local address, the remote address, and the reason string.
  • 'close': emitted when an underlying socket is closed.
  • 'connect': emitted when an underlying socket connects.
  • 'error': emitted when an underlying socket encounters an error.

  Parameters

  • event: "drop"

    the event name

  • listener: (
        message: Buffer,
        local: AddressInfo,
        remote: RemoteInfo,
        reason: "off-link",
    ) => void

    the callback to invoke when the event is emitted

  Returns this

once

• once(event: "close", listener: (local: AddressInfo) => void): this

  Registers a one-time listener for the given event. The listener is automatically removed after it fires once.

  Parameters

  • event: "close"

    the event name

  • listener: (local: AddressInfo) => void

    the callback to invoke when the event is emitted

  Returns this

• once(event: "connect", listener: (local: AddressInfo) => void): this

  Registers a one-time listener for the given event. The listener is automatically removed after it fires once.

  Parameters

  • event: "connect"

    the event name

  • listener: (local: AddressInfo) => void

    the callback to invoke when the event is emitted

  Returns this

• once(
      event: "error",
      listener: (error: Error, local?: AddressInfo) => void,
  ): this

  Registers a one-time listener for the given event. The listener is automatically removed after it fires once.

  Parameters

  • event: "error"

    the event name

  • listener: (error: Error, local?: AddressInfo) => void

    the callback to invoke when the event is emitted

  Returns this

• once(
      event: "message",
      listener: (
          message: Buffer,
          local: AddressInfo,
          remote: RemoteInfo,
          fromSelf: boolean,
      ) => void,
  ): this

  Registers a one-time listener for the given event. The listener is automatically removed after it fires once.

  Parameters

  • event: "message"

    the event name

  • listener: (
        message: Buffer,
        local: AddressInfo,
        remote: RemoteInfo,
        fromSelf: boolean,
    ) => void

    the callback to invoke when the event is emitted

  Returns this

• once(
      event: "drop",
      listener: (
          message: Buffer,
          local: AddressInfo,
          remote: RemoteInfo,
          reason: "off-link",
      ) => void,
  ): this

  Registers a one-time listener for the given event. The listener is automatically removed after it fires once.

  Parameters

  • event: "drop"

    the event name

  • listener: (
        message: Buffer,
        local: AddressInfo,
        remote: RemoteInfo,
        reason: "off-link",
    ) => void

    the callback to invoke when the event is emitted

  Returns this

ref

• ref(): void

  Adds all underlying sockets back to the Node.js event loop reference count, restoring the default behavior where the process will not exit while the sockets are open.

  Call this to undo a previous unref call.

  Returns void

send

• send(
      message: string | readonly any[] | ArrayBufferView<ArrayBufferLike>,
      options?: MulticastSocket.Send.Options,
  ): Promise<Error[]>

  Sends a message to the multicast group (or a unicast destination).

  Socket selection:

  • By default, the message is sent from all underlying unicast sockets, ensuring it goes out on every bound interface.
  • If options.srcAddress is set, only the unicast socket for that address is used.
  • If options.useMulticastSocket is set, the shared multicast socket is used instead. When combined with options.srcAddress, the multicast interface is set accordingly; without it, the OS chooses the outgoing interface, which may not cover all interfaces.

  Destination:

  • Defaults to the multicast group address and port from the constructor options.
  • Override with options.dstAddress and/or options.dstPort to send via unicast or to a different port.

  Partial failures are collected rather than thrown. Use Promise.allSettled semantics internally so that a failure on one interface does not prevent sending on others.

  Concurrency note: combining useMulticastSocket: true with srcAddress mutates per-socket interface state on the shared multicast socket via setMulticastInterface. Two such calls issued without awaiting the first to complete will race and may send on the wrong interface. Serialize them in the caller, or omit useMulticastSocket (the default per-interface unicast path is race-free because each interface has its own socket).

  Parameters

  • message: string | readonly any[] | ArrayBufferView<ArrayBufferLike>

    the payload to send

  • options: MulticastSocket.Send.Options = {}

    optional send configuration

  Returns Promise<Error[]>

  an array of errors for any interfaces that failed to send (empty on full success)

  Throws

  Error if options.srcAddress is specified but no matching socket exists

setMulticastLoopback

• setMulticastLoopback(loopback: boolean): void

  Sets or clears the IP_MULTICAST_LOOP socket option on the shared multicast socket. When set to true, multicast packets sent by this instance will also be delivered to its own 'message' event listeners (with fromSelf set to true).

  Implementation note: this only mutates IP_MULTICAST_LOOP on the shared multicast socket; the per-interface unicast sockets retain their OS-default loopback. The authoritative gate for whether the caller sees its own packets is the loopback check inside dispatch_message, which reads options.loopback that this method updates. The user-visible contract is therefore honored regardless of the kernel-level state on the unicast sockets.

  Parameters

  • loopback: boolean

    whether to enable multicast loopback

  Returns void

unref

• unref(): void

  Excludes all underlying sockets from the Node.js event loop reference count, allowing the process to exit even if the sockets are still open.

  Call ref to restore the default behavior.

  Returns void

Staticcreate

• create(options: MulticastSocket.Options): Promise<MulticastSocket>

  Async factory that creates, binds, and returns a new MulticastSocket.

  Internally this creates one multicast dgram socket bound to 0.0.0.0 (or :: for IPv6) for group traffic, plus one unicast dgram socket per network interface for reliable multi-interface sending and receiving.

  The socket type (udp4 or udp6) is automatically detected from the multicastGroup address provided in options.

  The host option controls which interfaces are used:

  • If omitted, all available interfaces are used (similar to binding to 0.0.0.0 / ::)
  • If an IP address string, only that interface is used
  • If a network interface name, all addresses assigned to that interface are used

  Parameters

  • options: MulticastSocket.Options

    the configuration for the new socket

  Returns Promise<MulticastSocket>

  a fully initialized MulticastSocket ready to send and receive

  Throws

  Error if no usable interfaces are found, or if the specified host address does not exist on this system or does not match the multicast group address family