@@ -372,6 +372,84 @@ added: v0.6.9
372
372
Sets or clears the ` SO_BROADCAST ` socket option. When set to ` true ` , UDP
373
373
packets may be sent to a local interface's broadcast address.
374
374
375
+ ### socket.setMulticastInterface(multicastInterface)
376
+ <!-- YAML
377
+ added: REPLACEME
378
+ -->
379
+
380
+ * ` multicastInterface ` {String}
381
+
382
+ * Note: All references to scope in this section are refering to
383
+ [ IPv6 Zone Indices] [ ] , which are defined by [ RFC 4007] [ ] . In string form, an IP
384
+ with a scope index is written as ` 'IP%scope' ` where scope is an interface name or
385
+ interface number.*
386
+
387
+ Sets the default outgoing multicast interface of the socket to a chosen
388
+ interface or back to system interface selection. The ` multicastInterface ` must
389
+ be a valid string representation of an IP from the socket's family.
390
+
391
+ For IPv4 sockets, this should be the IP configured for the desired physical
392
+ interface. All packets sent to multicast on the socket will be sent on the
393
+ interface determined by the most recent successful use of this call.
394
+
395
+ For IPv6 sockets, ` multicastInterface ` should include a scope to indicate the
396
+ interface as in the examples that follow. In IPv6, individual ` send ` calls can
397
+ also use explicit scope in addresses, so only packets sent to a multicast
398
+ address without specifying an explicit scope are affected by the most recent
399
+ successful use of this call.
400
+
401
+ #### Examples: IPv6 Outgoing Multicast Interface
402
+
403
+ On most systems, where scope format uses the interface name:
404
+
405
+ ``` js
406
+ const socket = dgram .createSocket (' udp6' );
407
+
408
+ socket .bind (1234 , () => {
409
+ socket .setMulticastInterface (' ::%eth1' );
410
+ });
411
+ ```
412
+
413
+ On Windows, where scope format uses an interface number:
414
+
415
+ ``` js
416
+ const socket = dgram .createSocket (' udp6' );
417
+
418
+ socket .bind (1234 , () => {
419
+ socket .setMulticastInterface (' ::%2' );
420
+ });
421
+ ```
422
+
423
+ #### Example: IPv4 Outgoing Multicast Interface
424
+ All systems use an IP of the host on the desired physical interface:
425
+ ``` js
426
+ const socket = dgram .createSocket (' udp4' );
427
+
428
+ socket .bind (1234 , () => {
429
+ socket .setMulticastInterface (' 10.0.0.2' );
430
+ });
431
+ ```
432
+
433
+ #### Call Results
434
+
435
+ A call on a socket that is not ready to send or no longer open may throw a * Not
436
+ running* [ ` Error ` ] [ ] .
437
+
438
+ If ` multicastInterface ` can not be parsed into an IP then an * EINVAL*
439
+ [ ` System Error ` ] [ ] is thrown.
440
+
441
+ On IPv4, if ` multicastInterface ` is a valid address but does not match any
442
+ interface, or if the address does not match the family then
443
+ a [ ` System Error ` ] [ ] such as ` EADDRNOTAVAIL ` or ` EPROTONOSUP ` is thrown.
444
+
445
+ On IPv6, most errors with specifying or omiting scope will result in the socket
446
+ continuing to use (or returning to) the system's default interface selection.
447
+
448
+ A socket's address family's ANY address (IPv4 ` '0.0.0.0' ` or IPv6 ` '::' ` ) can be
449
+ used to return control of the sockets default outgoing interface to the system
450
+ for future multicast packets.
451
+
452
+
375
453
### socket.setMulticastLoopback(flag)
376
454
<!-- YAML
377
455
added: v0.3.8
@@ -510,4 +588,7 @@ and `udp6` sockets). The bound address and port can be retrieved using
510
588
[ `socket.address().address` ] : #dgram_socket_address
511
589
[ `socket.address().port` ] : #dgram_socket_address
512
590
[ `socket.bind()` ] : #dgram_socket_bind_port_address_callback
591
+ [ `System Error` ] : errors.html#errors_class_system_error
513
592
[ byte length ] : buffer.html#buffer_class_method_buffer_bytelength_string_encoding
593
+ [ IPv6 Zone Indices ] : https://en.wikipedia.org/wiki/IPv6_address#Link-local_addresses_and_zone_indices
594
+ [ RFC 4007 ] : https://tools.ietf.org/html/rfc4007
0 commit comments