- Dgram
- Class: dgram.Socket
- Event: ‘close’
- Event: ‘error’
- Event: ‘listening’
- Event: ‘message’
- socket.addMembership(multicastAddress[, multicastInterface])
- socket.address()
- socket.bind([port][, address][, bindListener])
- socket.bind(options[, bindListener])
- socket.close([closeListener])
- socket.dropMembership(multicastAddress[, multicastInterface])
- socket.setBroadcast(flag)
- socket.send(msg, [offset, length,] port [, address] [, sendListener])
- socket.sendto(msg, offset, length, port [, address] [, sendListener])
- socket.setMulticastLoopback(flag)
- socket.setMulticastTTL(ttl)
- socket.setTTL(ttl)
Dgram
The dgram module provides an implementation of UDP Datagram sockets.
The following example creates a UDP Datagram server.
Example
var dgram = require('dgram');
var server = dgram.createSocket('udp4');
server.on('error', function (err) {
console.log('Error: ' + err);
server.close();
});
server.on('message', function(msg, rinfo) {
// prints: message received
console.log('server got: ' + msg);
});
server.on('listening', function() {
console.log('server listening at ' + server.address().port);
});
server.bind(41234);
dgram.createSocket(options[, callback])
options
{Object}type
{string}reuseAddr
{boolean}
callback
{Function} (optional)
Creates a new dgram.Socket
object. The type of the connection is specified by options.type
. Currently only udp4
is supported.
If reuseAddr
is true the socket.bind()
call reuses the address even if this address has been bound by another process.
The optional ‘callback’ function is attached to the 'message'
event.
Example
var dgram = require('dgram');
var server = dgram.createSocket({ type: 'udp4', reuseAddr: true});
dgram.createSocket(type[, callback])
type
{string}callback
{Function} (optional)
Creates a new dgram.Socket
object. The type of the connection is specified by the type
argument. Currently only udp4
is supported.
The optional ‘callback’ function is attached to the 'message'
event.
Example
var dgram = require('dgram');
var server = dgram.createSocket('udp4');
Class: dgram.Socket
The dgram.Socket
object is an EventEmitter
that encapsulates the datagram functionality.
New instances of dgram.Socket
are created using dgram.createSocket()
. The new keyword must not be used to create dgram.Socket instances.
Supported events:
Event: ‘close’
The 'close'
event is emitted after a socket is closed with close()
. Once triggered, no new 'message'
events will be emitted on this socket.
Event: ‘error’
exception
{Error}
The 'error'
event is emitted whenever any error occurs. A single Error object is passed to the event handler.
Event: ‘listening’
The 'listening'
event is emitted whenever a socket begins listening for datagram messages. This occurs as soon as UDP sockets are created.
Event: ‘message’
msg
{Buffer} The message.rinfo
{Object} Remote address information.address
{string} The sender address.family
{string} The address family (‘IPv4’).port
{number} The sender port.size
{number} The message size.
The 'message'
event is emitted when a new datagram is received by the socket. The msg
argument contains the message data and the rinfo
argument contains the message properties.
socket.addMembership(multicastAddress[, multicastInterface])
multicastAddress
{string}multicastInterface
{string}
Joins the multicast group specified by multicastAddress
and multicastInterface
. If multicastInterface
is undefined the operating system will choose one add interface and will add membership to it. To add membership to every available interface, call addMembership multiple times, once per interface.
Example
var dgram = require('dgram');
var multicast_address = '230.255.255.250';
var server = dgram.createSocket('udp4');
server.bind(12345 /* port */, function() {
server.addMembership(multicast_address);
});
socket.address()
- Returns: {Object}
Returns an object with the properties address
, port
and family
.
Example
var dgram = require('dgram');
var server = dgram.createSocket('udp4');
server.on('listening', function () {
var address = server.address();
// prints: address and port of the server address
console.log('Addr: ' + address.address + ' port: ' + address.port);
});
server.bind(12345 /* port */);
socket.bind([port][, address][, bindListener])
port
{number}address
{string} Default:0.0.0.0
bindListener
{Function}
Assign the port
and address
to an UDP socket. If port
is not specified the operating system selects a random unused port.
The optional ‘bindListener’ function is attached to the 'listening'
event.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
var port = 12345;
socket.bind(port, function () {
// prints: Listening for packets
console.log('Listening for packets');
});
socket.bind(options[, bindListener])
options
{Object}port
{number}address
{string} Default:0.0.0.0
bindListener
{Function}
Assign options.port
and options.address
to an UDP socket. If options.port
is not specified the operating system selects a random unused port.
The optional ‘bindListener’ function is attached to the 'listening'
event.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
socket.bind({ port:12345 }, function () {
// prints: Listening for packets
console.log('Listening for packets');
});
socket.close([closeListener])
closeListener
{Function}
Close the underlying socket and stop listening for data on it.
The optional ‘closeListener’ function is attached to the 'close'
event.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
// prints: Close!
socket.close(function () {
// prints: Socket is closed
console.log('Socket is closed');
});
socket.dropMembership(multicastAddress[, multicastInterface])
multicastAddress
{string}multicastInterface
{string}
Leaves for socket the given multicast group with given multicastAddress
and multicastInterface
.
Example
var dgram = require('dgram');
var server = dgram.createSocket('udp4');
var multicast_address = '230.255.255.250';
server.bind(12345 /* port */, function() {
server.addMembership(multicast_address);
});
server.on('message', function(data, rinfo) {
// Drop membership when a message arrived.
server.dropMembership(multicast_address);
});
socket.setBroadcast(flag)
flag
{boolean}
Sets or clears the SO_BROADCAST
socket option. When flag
is true UDP packets may be sent to a local interface’s broadcast address.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
var port = 41237;
socket.bind(port, function() {
socket.setBroadcast(true);
});
socket.send(msg, [offset, length,] port [, address] [, sendListener])
msg
{Buffer|string|array}offset
{integer} Only valid ifmsg
is Buffer.length
{integer} Only valid ifmsg
is Buffer.port
{integer}address
{string} Default:127.0.0.1
or::1
sendListener
{Function}Error
{Object|null}code
{string} Currently it is always"error"
.errno
{string} Same ascode
.syscall
{integer}address
{string}port
{integer}
length
{integer} Length of data.
Transmits a message to the destination socket specified by address
and port
arguments. The msg
argument contains the data to be sent. It can be a {Buffer}, a {string} converted to UTF-8 bytes, or an array of {Buffer} and {string} values. In the latter case the items of the array are concatenated into a single {Buffer} before sending.
If send operation is successfully completed, sendListener
will be called with null
and the length of data. Otherwise an Error {Object} is passed along with the length of data.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
var broadcast_address = '255.255.255.255';
var port = 41237;
socket.bind(port, function() {
socket.setBroadcast(true);
socket.send('Hello IoT.js', port, broadcast_address);
});
socket.sendto(msg, offset, length, port [, address] [, sendListener])
msg
{Buffer|string|array}offset
{integer}length
{integer}port
{integer}address
{string} Default:127.0.0.1
or::1
sendListener
{Function}
Legacy function. It is the same as socket.send
except offset
and length
arguments are mandatory.
socket.setMulticastLoopback(flag)
flag
{boolean}
Sets or clears the IP_MULTICAST_LOOP
socket option. When flag
is true
multicast packets will also be received on the local interface.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
var port = 41237;
socket.bind(port, function() {
socket.setMulticastLoopback(true);
});
socket.setMulticastTTL(ttl)
ttl
{integer} This value must be between 0 and 255.
Sets the IP_MULTICAST_TTL
socket option which pecifies the number of IP hops that a packet is allowed to travel through, specifically for multicast traffic. Each router or gateway that forwards a packet decrements its TTL. When TTL reaches zero the packet is not forwarded anymore.
The default on most systems is 1 but can vary.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
var port = 41237;
socket.bind(port, function() {
socket.setMulticastTTL(1);
});
socket.setTTL(ttl)
ttl
{integer} This value must be between 1 and 255.
Sets the IP_TTL
socket option which specifies the number of IP hops that a packet is allowed to travel through. Each router or gateway that forwards a packet decrements its TTL. When TTL reaches zero the packet is not forwarded anymore.
The default on most systems is 64 but can vary.
Example
var dgram = require('dgram');
var socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
var port = 41237;
socket.bind(port, function() {
socket.setTTL(64);
});