diff options
author | isaacs <i@izs.me> | 2012-02-27 23:08:27 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2012-03-01 04:04:51 +0400 |
commit | db8c55e77c884b1c89e2bb7004a80b2965e4bf05 (patch) | |
tree | edc25c4aa3f0bdc19ab4cd2bc48986ba34dca742 /doc/api | |
parent | f775c5cea4ff1e719e15a3dc8ef3a4abc9ea2650 (diff) |
doc refactor: dgram
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/dgram.markdown | 74 |
1 files changed, 53 insertions, 21 deletions
diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index d057b412fb6..150d5d8b155 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -1,50 +1,65 @@ -## UDP / Datagram Sockets +# UDP / Datagram Sockets + +<!-- name=dgram --> Datagram sockets are available through `require('dgram')`. +## dgram.createSocket(type, [callback]) + +* `type` String. Either 'udp4' or 'udp6' +* `callback` Function. Attached as a listener to `message` events. + Optional +* Returns: Socket object + +Creates a datagram Socket of the specified types. Valid types are `udp4` +and `udp6`. + +Takes an optional callback which is added as a listener for `message` events. + +Call `socket.bind` if you want to receive datagrams. `socket.bind()` will bind +to the "all interfaces" address on a random port (it does the right thing for +both `udp4` and `udp6` sockets). You can then retrieve the address and port +with `socket.address().address` and `socket.address().port`. + +## Class: Socket + +The dgram Socket class encapsulates the datagram functionality. It +should be created via `dgram.createSocket(type, [callback])`. + ### Event: 'message' -`function (msg, rinfo) { }` +* `msg` Buffer object. The message +* `rinfo` Object. Remote address information Emitted when a new datagram is available on a socket. `msg` is a `Buffer` and `rinfo` is an object with the sender's address information and the number of bytes in the datagram. ### Event: 'listening' -`function () { }` - Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets are created. ### Event: 'close' -`function () { }` - Emitted when a socket is closed with `close()`. No new `message` events will be emitted on this socket. ### Event: 'error' -`function (exception) {}` +* `exception` Error object Emitted when an error occurs. ---- - -### dgram.createSocket(type, [callback]) - -Creates a datagram socket of the specified types. Valid types are `udp4` -and `udp6`. - -Takes an optional callback which is added as a listener for `message` events. - -Call `socket.bind` if you want to receive datagrams. `socket.bind()` will bind -to the "all interfaces" address on a random port (it does the right thing for -both `udp4` and `udp6` sockets). You can then retrieve the address and port -with `socket.address().address` and `socket.address().port`. - ### dgram.send(buf, offset, length, port, address, [callback]) +* `buf` Buffer object. Message to be sent +* `offset` Integer. Offset in the buffer where the message starts. +* `length` Integer. Number of bytes in the message. +* `port` Integer. destination port +* `address` String. destination IP +* `callback` Function. Callback when message is done being delivered. + Optional. + For UDP sockets, the destination port and IP address must be specified. A string may be supplied for the `address` parameter, and it will be resolved with DNS. An optional callback may be specified to detect any DNS errors and when `buf` may be @@ -93,6 +108,9 @@ informing the source that the data did not reach its intended recipient). ### dgram.bind(port, [address]) +* `port` Integer +* `address` String, Optional + For UDP sockets, listen for datagrams on a named `port` and optional `address`. If `address` is not specified, the OS will try to listen on all addresses. @@ -128,11 +146,15 @@ this object will contain `address` and `port`. ### dgram.setBroadcast(flag) +* `flag` Boolean + Sets or clears the `SO_BROADCAST` socket option. When this option is set, UDP packets may be sent to a local interface's broadcast address. ### dgram.setTTL(ttl) +* `ttl` Integer + Sets the `IP_TTL` socket option. TTL stands for "Time to Live," but in this context it specifies the number of IP hops that a packet is allowed to go through. Each router or gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a @@ -144,6 +166,8 @@ systems is 64. ### dgram.setMulticastTTL(ttl) +* `ttl` Integer + Sets the `IP_MULTICAST_TTL` socket option. TTL stands for "Time to Live," but in this context it specifies the number of IP hops that a packet is allowed to go through, specifically for multicast traffic. Each router or gateway that forwards a packet @@ -154,11 +178,16 @@ systems is 64. ### dgram.setMulticastLoopback(flag) +* `flag` Boolean + Sets or clears the `IP_MULTICAST_LOOP` socket option. When this option is set, multicast packets will also be received on the local interface. ### dgram.addMembership(multicastAddress, [multicastInterface]) +* `multicastAddress` String +* `multicastInterface` String, Optional + Tells the kernel to join a multicast group with `IP_ADD_MEMBERSHIP` socket option. If `multicastInterface` is not specified, the OS will try to add membership to all valid @@ -166,6 +195,9 @@ interfaces. ### dgram.dropMembership(multicastAddress, [multicastInterface]) +* `multicastAddress` String +* `multicastInterface` String, Optional + Opposite of `addMembership` - tells the kernel to leave a multicast group with `IP_DROP_MEMBERSHIP` socket option. This is automatically called by the kernel when the socket is closed or process terminates, so most apps will never need to call |