| { |
| "source": "doc/api/dgram.markdown", |
| "modules": [ |
| { |
| "textRaw": "UDP / Datagram Sockets", |
| "name": "dgram", |
| "stability": 3, |
| "stabilityText": "Stable", |
| "desc": "<p>Datagram sockets are available through <code>require('dgram')</code>.\n\n</p>\n<p>Important note: the behavior of <code>dgram.Socket#bind()</code> has changed in v0.10\nand is always asynchronous now. If you have code that looks like this:\n\n</p>\n<pre><code>var s = dgram.createSocket('udp4');\ns.bind(1234);\ns.addMembership('224.0.0.114');</code></pre>\n<p>You have to change it to this:\n\n</p>\n<pre><code>var s = dgram.createSocket('udp4');\ns.bind(1234, function() {\n s.addMembership('224.0.0.114');\n});</code></pre>\n", |
| "methods": [ |
| { |
| "textRaw": "dgram.createSocket(type, [callback])", |
| "type": "method", |
| "name": "createSocket", |
| "signatures": [ |
| { |
| "return": { |
| "textRaw": "Returns: Socket object ", |
| "name": "return", |
| "desc": "Socket object" |
| }, |
| "params": [ |
| { |
| "textRaw": "`type` String. Either 'udp4' or 'udp6' ", |
| "name": "type", |
| "desc": "String. Either 'udp4' or 'udp6'" |
| }, |
| { |
| "textRaw": "`callback` Function. Attached as a listener to `message` events. Optional ", |
| "name": "callback", |
| "optional": true, |
| "desc": "Function. Attached as a listener to `message` events." |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "type" |
| }, |
| { |
| "name": "callback", |
| "optional": true |
| } |
| ] |
| } |
| ], |
| "desc": "<p>Creates a datagram Socket of the specified types. Valid types are <code>udp4</code>\nand <code>udp6</code>.\n\n</p>\n<p>Takes an optional callback which is added as a listener for <code>message</code> events.\n\n</p>\n<p>Call <code>socket.bind</code> if you want to receive datagrams. <code>socket.bind()</code> will bind\nto the "all interfaces" address on a random port (it does the right thing for\nboth <code>udp4</code> and <code>udp6</code> sockets). You can then retrieve the address and port\nwith <code>socket.address().address</code> and <code>socket.address().port</code>.\n\n</p>\n" |
| } |
| ], |
| "classes": [ |
| { |
| "textRaw": "Class: dgram.Socket", |
| "type": "class", |
| "name": "dgram.Socket", |
| "desc": "<p>The dgram Socket class encapsulates the datagram functionality. It\nshould be created via <code>dgram.createSocket(type, [callback])</code>.\n\n</p>\n", |
| "events": [ |
| { |
| "textRaw": "Event: 'message'", |
| "type": "event", |
| "name": "message", |
| "params": [], |
| "desc": "<p>Emitted when a new datagram is available on a socket. <code>msg</code> is a <code>Buffer</code> and <code>rinfo</code> is\nan object with the sender's address information and the number of bytes in the datagram.\n\n</p>\n" |
| }, |
| { |
| "textRaw": "Event: 'listening'", |
| "type": "event", |
| "name": "listening", |
| "desc": "<p>Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets\nare created.\n\n</p>\n", |
| "params": [] |
| }, |
| { |
| "textRaw": "Event: 'close'", |
| "type": "event", |
| "name": "close", |
| "desc": "<p>Emitted when a socket is closed with <code>close()</code>. No new <code>message</code> events will be emitted\non this socket.\n\n</p>\n", |
| "params": [] |
| }, |
| { |
| "textRaw": "Event: 'error'", |
| "type": "event", |
| "name": "error", |
| "params": [], |
| "desc": "<p>Emitted when an error occurs.\n\n</p>\n" |
| } |
| ], |
| "methods": [ |
| { |
| "textRaw": "socket.send(buf, offset, length, port, address, [callback])", |
| "type": "method", |
| "name": "send", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`buf` Buffer object. Message to be sent ", |
| "name": "buf", |
| "desc": "Buffer object. Message to be sent" |
| }, |
| { |
| "textRaw": "`offset` Integer. Offset in the buffer where the message starts. ", |
| "name": "offset", |
| "desc": "Integer. Offset in the buffer where the message starts." |
| }, |
| { |
| "textRaw": "`length` Integer. Number of bytes in the message. ", |
| "name": "length", |
| "desc": "Integer. Number of bytes in the message." |
| }, |
| { |
| "textRaw": "`port` Integer. Destination port. ", |
| "name": "port", |
| "desc": "Integer. Destination port." |
| }, |
| { |
| "textRaw": "`address` String. Destination hostname or IP address. ", |
| "name": "address", |
| "desc": "String. Destination hostname or IP address." |
| }, |
| { |
| "textRaw": "`callback` Function. Called when the message has been sent. Optional. ", |
| "name": "callback", |
| "desc": "Function. Called when the message has been sent. Optional.", |
| "optional": true |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "buf" |
| }, |
| { |
| "name": "offset" |
| }, |
| { |
| "name": "length" |
| }, |
| { |
| "name": "port" |
| }, |
| { |
| "name": "address" |
| }, |
| { |
| "name": "callback", |
| "optional": true |
| } |
| ] |
| } |
| ], |
| "desc": "<p>For UDP sockets, the destination port and address must be specified. A string\nmay be supplied for the <code>address</code> parameter, and it will be resolved with DNS.\n\n</p>\n<p>If the address is omitted or is an empty string, <code>'0.0.0.0'</code> or <code>'::0'</code> is used\ninstead. Depending on the network configuration, those defaults may or may not\nwork; it's best to be explicit about the destination address.\n\n</p>\n<p>If the socket has not been previously bound with a call to <code>bind</code>, it gets\nassigned a random port number and is bound to the "all interfaces" address\n(<code>'0.0.0.0'</code> for <code>udp4</code> sockets, <code>'::0'</code> for <code>udp6</code> sockets.)\n\n</p>\n<p>An optional callback may be specified to detect DNS errors or for determining\nwhen it's safe to reuse the <code>buf</code> object. Note that DNS lookups delay the time\nto send for at least one tick. The only way to know for sure that the datagram\nhas been sent is by using a callback.\n\n</p>\n<p>Example of sending a UDP packet to a random port on <code>localhost</code>;\n\n</p>\n<pre><code>var dgram = require('dgram');\nvar message = new Buffer("Some bytes");\nvar client = dgram.createSocket("udp4");\nclient.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {\n client.close();\n});</code></pre>\n<p><strong>A Note about UDP datagram size</strong>\n\n</p>\n<p>The maximum size of an <code>IPv4/v6</code> datagram depends on the <code>MTU</code> (<em>Maximum Transmission Unit</em>)\nand on the <code>Payload Length</code> field size.\n\n</p>\n<ul>\n<li><p>The <code>Payload Length</code> field is <code>16 bits</code> wide, which means that a normal payload\ncannot be larger than 64K octets including internet header and data\n(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header);\nthis is generally true for loopback interfaces, but such long datagrams\nare impractical for most hosts and networks.</p>\n</li>\n<li><p>The <code>MTU</code> is the largest size a given link layer technology can support for datagrams.\nFor any link, <code>IPv4</code> mandates a minimum <code>MTU</code> of <code>68</code> octets, while the recommended <code>MTU</code>\nfor IPv4 is <code>576</code> (typically recommended as the <code>MTU</code> for dial-up type applications),\nwhether they arrive whole or in fragments.</p>\n<p>For <code>IPv6</code>, the minimum <code>MTU</code> is <code>1280</code> octets, however, the mandatory minimum\nfragment reassembly buffer size is <code>1500</code> octets.\nThe value of <code>68</code> octets is very small, since most current link layer technologies have\na minimum <code>MTU</code> of <code>1500</code> (like Ethernet).</p>\n</li>\n</ul>\n<p>Note that it's impossible to know in advance the MTU of each link through which\na packet might travel, and that generally sending a datagram greater than\nthe (receiver) <code>MTU</code> won't work (the packet gets silently dropped, without\ninforming the source that the data did not reach its intended recipient).\n\n</p>\n" |
| }, |
| { |
| "textRaw": "socket.bind(port, [address], [callback])", |
| "type": "method", |
| "name": "bind", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`port` Integer ", |
| "name": "port", |
| "desc": "Integer" |
| }, |
| { |
| "textRaw": "`address` String, Optional ", |
| "name": "address", |
| "optional": true, |
| "desc": "String" |
| }, |
| { |
| "textRaw": "`callback` Function with no parameters, Optional. Callback when binding is done. ", |
| "name": "callback", |
| "desc": "Function with no parameters, Optional. Callback when binding is done.", |
| "optional": true |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "port" |
| }, |
| { |
| "name": "address", |
| "optional": true |
| }, |
| { |
| "name": "callback", |
| "optional": true |
| } |
| ] |
| } |
| ], |
| "desc": "<p>For UDP sockets, listen for datagrams on a named <code>port</code> and optional\n<code>address</code>. If <code>address</code> is not specified, the OS will try to listen on\nall addresses. After binding is done, a "listening" event is emitted\nand the <code>callback</code>(if specified) is called. Specifying both a\n"listening" event listener and <code>callback</code> is not harmful but not very\nuseful.\n\n</p>\n<p>A bound datagram socket keeps the node process running to receive\ndatagrams.\n\n</p>\n<p>If binding fails, an "error" event is generated. In rare case (e.g.\nbinding a closed socket), an <code>Error</code> may be thrown by this method.\n\n</p>\n<p>Example of a UDP server listening on port 41234:\n\n</p>\n<pre><code>var dgram = require("dgram");\n\nvar server = dgram.createSocket("udp4");\n\nserver.on("error", function (err) {\n console.log("server error:\\n" + err.stack);\n server.close();\n});\n\nserver.on("message", function (msg, rinfo) {\n console.log("server got: " + msg + " from " +\n rinfo.address + ":" + rinfo.port);\n});\n\nserver.on("listening", function () {\n var address = server.address();\n console.log("server listening " +\n address.address + ":" + address.port);\n});\n\nserver.bind(41234);\n// server listening 0.0.0.0:41234</code></pre>\n" |
| }, |
| { |
| "textRaw": "socket.close()", |
| "type": "method", |
| "name": "close", |
| "desc": "<p>Close the underlying socket and stop listening for data on it.\n\n</p>\n", |
| "signatures": [ |
| { |
| "params": [] |
| } |
| ] |
| }, |
| { |
| "textRaw": "socket.address()", |
| "type": "method", |
| "name": "address", |
| "desc": "<p>Returns an object containing the address information for a socket. For UDP sockets,\nthis object will contain <code>address</code> , <code>family</code> and <code>port</code>.\n\n</p>\n", |
| "signatures": [ |
| { |
| "params": [] |
| } |
| ] |
| }, |
| { |
| "textRaw": "socket.setBroadcast(flag)", |
| "type": "method", |
| "name": "setBroadcast", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`flag` Boolean ", |
| "name": "flag", |
| "desc": "Boolean" |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "flag" |
| } |
| ] |
| } |
| ], |
| "desc": "<p>Sets or clears the <code>SO_BROADCAST</code> socket option. When this option is set, UDP packets\nmay be sent to a local interface's broadcast address.\n\n</p>\n" |
| }, |
| { |
| "textRaw": "socket.setTTL(ttl)", |
| "type": "method", |
| "name": "setTTL", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`ttl` Integer ", |
| "name": "ttl", |
| "desc": "Integer" |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "ttl" |
| } |
| ] |
| } |
| ], |
| "desc": "<p>Sets the <code>IP_TTL</code> socket option. TTL stands for "Time to Live," but in this context it\nspecifies the number of IP hops that a packet is allowed to go through. Each router or\ngateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a\nrouter, it will not be forwarded. Changing TTL values is typically done for network\nprobes or when multicasting.\n\n</p>\n<p>The argument to <code>setTTL()</code> is a number of hops between 1 and 255. The default on most\nsystems is 64.\n\n</p>\n" |
| }, |
| { |
| "textRaw": "socket.setMulticastTTL(ttl)", |
| "type": "method", |
| "name": "setMulticastTTL", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`ttl` Integer ", |
| "name": "ttl", |
| "desc": "Integer" |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "ttl" |
| } |
| ] |
| } |
| ], |
| "desc": "<p>Sets the <code>IP_MULTICAST_TTL</code> socket option. TTL stands for "Time to Live," but in this\ncontext it specifies the number of IP hops that a packet is allowed to go through,\nspecifically for multicast traffic. Each router or gateway that forwards a packet\ndecrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.\n\n</p>\n<p>The argument to <code>setMulticastTTL()</code> is a number of hops between 0 and 255. The default on most\nsystems is 1.\n\n</p>\n" |
| }, |
| { |
| "textRaw": "socket.setMulticastLoopback(flag)", |
| "type": "method", |
| "name": "setMulticastLoopback", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`flag` Boolean ", |
| "name": "flag", |
| "desc": "Boolean" |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "flag" |
| } |
| ] |
| } |
| ], |
| "desc": "<p>Sets or clears the <code>IP_MULTICAST_LOOP</code> socket option. When this option is set, multicast\npackets will also be received on the local interface.\n\n</p>\n" |
| }, |
| { |
| "textRaw": "socket.addMembership(multicastAddress, [multicastInterface])", |
| "type": "method", |
| "name": "addMembership", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`multicastAddress` String ", |
| "name": "multicastAddress", |
| "desc": "String" |
| }, |
| { |
| "textRaw": "`multicastInterface` String, Optional ", |
| "name": "multicastInterface", |
| "optional": true, |
| "desc": "String" |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "multicastAddress" |
| }, |
| { |
| "name": "multicastInterface", |
| "optional": true |
| } |
| ] |
| } |
| ], |
| "desc": "<p>Tells the kernel to join a multicast group with <code>IP_ADD_MEMBERSHIP</code> socket option.\n\n</p>\n<p>If <code>multicastInterface</code> is not specified, the OS will try to add membership to all valid\ninterfaces.\n\n</p>\n" |
| }, |
| { |
| "textRaw": "socket.dropMembership(multicastAddress, [multicastInterface])", |
| "type": "method", |
| "name": "dropMembership", |
| "signatures": [ |
| { |
| "params": [ |
| { |
| "textRaw": "`multicastAddress` String ", |
| "name": "multicastAddress", |
| "desc": "String" |
| }, |
| { |
| "textRaw": "`multicastInterface` String, Optional ", |
| "name": "multicastInterface", |
| "optional": true, |
| "desc": "String" |
| } |
| ] |
| }, |
| { |
| "params": [ |
| { |
| "name": "multicastAddress" |
| }, |
| { |
| "name": "multicastInterface", |
| "optional": true |
| } |
| ] |
| } |
| ], |
| "desc": "<p>Opposite of <code>addMembership</code> - tells the kernel to leave a multicast group with\n<code>IP_DROP_MEMBERSHIP</code> socket option. This is automatically called by the kernel\nwhen the socket is closed or process terminates, so most apps will never need to call\nthis.\n\n</p>\n<p>If <code>multicastInterface</code> is not specified, the OS will try to drop membership to all valid\ninterfaces.\n\n</p>\n" |
| }, |
| { |
| "textRaw": "socket.unref()", |
| "type": "method", |
| "name": "unref", |
| "desc": "<p>Calling <code>unref</code> on a socket will allow the program to exit if this is the only\nactive socket in the event system. If the socket is already <code>unref</code>d calling\n<code>unref</code> again will have no effect.\n\n</p>\n", |
| "signatures": [ |
| { |
| "params": [] |
| } |
| ] |
| }, |
| { |
| "textRaw": "socket.ref()", |
| "type": "method", |
| "name": "ref", |
| "desc": "<p>Opposite of <code>unref</code>, calling <code>ref</code> on a previously <code>unref</code>d socket will <em>not</em>\nlet the program exit if it's the only socket left (the default behavior). If\nthe socket is <code>ref</code>d calling <code>ref</code> again will have no effect.\n</p>\n", |
| "signatures": [ |
| { |
| "params": [] |
| } |
| ] |
| } |
| ] |
| } |
| ], |
| "type": "module", |
| "displayName": "dgram" |
| } |
| ] |
| } |
