diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 3f5664d8fc9090..f2968438b183c6 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -372,6 +372,84 @@ added: v0.6.9 Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP packets may be sent to a local interface's broadcast address. +### socket.setMulticastInterface(multicastInterface) + + +* `multicastInterface` {String} + +*Note: All references to scope in this section are refering to +[IPv6 Zone Indices][], which are defined by [RFC 4007][]. In string form, an IP +with a scope index is written as `'IP%scope'` where scope is an interface name or +interface number.* + +Sets the default outgoing multicast interface of the socket to a chosen +interface or back to system interface selection. The `multicastInterface` must +be a valid string representation of an IP from the socket's family. + +For IPv4 sockets, this should be the IP configured for the desired physical +interface. All packets sent to multicast on the socket will be sent on the +interface determined by the most recent successful use of this call. + +For IPv6 sockets, `multicastInterface` should include a scope to indicate the +interface as in the examples that follow. In IPv6, individual `send` calls can +also use explicit scope in addresses, so only packets sent to a multicast +address without specifying an explicit scope are affected by the most recent +successful use of this call. + +#### Examples: IPv6 Outgoing Multicast Interface + +On most systems, where scope format uses the interface name: + +```js +const socket = dgram.createSocket('udp6'); + +socket.bind(1234, () => { + socket.setMulticastInterface('::%eth1'); +}); +``` + +On Windows, where scope format uses an interface number: + +```js +const socket = dgram.createSocket('udp6'); + +socket.bind(1234, () => { + socket.setMulticastInterface('::%2'); +}); +``` + +#### Example: IPv4 Outgoing Multicast Interface +All systems use an IP of the host on the desired physical interface: +```js +const socket = dgram.createSocket('udp4'); + +socket.bind(1234, () => { + socket.setMulticastInterface('10.0.0.2'); +}); +``` + +#### Call Results + +A call on a socket that is not ready to send or no longer open may throw a *Not +running* [`Error`][]. + +If `multicastInterface` can not be parsed into an IP then an *EINVAL* +[`System Error`][] is thrown. + +On IPv4, if `multicastInterface` is a valid address but does not match any +interface, or if the address does not match the family then +a [`System Error`][] such as `EADDRNOTAVAIL` or `EPROTONOSUP` is thrown. + +On IPv6, most errors with specifying or omiting scope will result in the socket +continuing to use (or returning to) the system's default interface selection. + +A socket's address family's ANY address (IPv4 `'0.0.0.0'` or IPv6 `'::'`) can be +used to return control of the sockets default outgoing interface to the system +for future multicast packets. + + ### socket.setMulticastLoopback(flag)