docs/api/IoT.js-API-DGRAM.md

   1 ## Module: dgram
   2
   3 ### Platform Support
   4
   5 The following shows dgram module APIs available for each platform.
   6
   7 |  | Linux<br/>(Ubuntu) | Raspbian<br/>(Raspberry Pi) | Nuttx<br/>(STM32F4-Discovery) |
   8 | :---: | :---: | :---: | :---: |
   9 | dgram.createSocket | O | O | O |
  10 | dgram.Socket.bind | O | O | O |
  11 | dgram.Socket.close | O | O | O |
  12 | dgram.Socket.send | O | O | O |
  13 | dgram.Socket.address | O | O | X |
  14 | dgram.Socket.setBroadcast | O | O | X |
  15 | dgram.Socket.setTTL | O | O | X |
  16 | dgram.Socket.addMembership | O | O | X |
  17 | dgram.Socket.dropMembership | O | O | X |
  18 | dgram.Socket.setMulticastLoopback | O | O | X |
  19 | dgram.Socket.setMulticastTTL | X | X | X |
  20
  21 IoT.js provides udp connections through Dgram module.
  22
  23 You can use this module with `require('dgram')` and create sockets.
  24
  25
  26 ### Module Functions
  27
  28
  29 #### dgram.createSocket(options[, createListener])
  30 #### dgram.createSocket(type[, createListener])
  31 * `options: Object`
  32  * `type: String`: it indicates an address family either `udp4` or `udp6`.
  33  * `reuseAddr: Boolean`: it indicates to allow socket to bind the address and port used previously.
  34
  35 * `type: String`: it indicates an address family either 'udp4' or 'udp6'.
  36
  37 * `createListener: Function(msg, rinfo)`
  38  * `msg: Buffer`
  39  * `rinfo: Object`
  40    * `address: String`
  41    * `family: String`: it indicates an address family either `IPv4` or `IPv6`
  42    * `port: Number`
  43
  44 Creates a `dgram.Socket` according to `options` or `type`. (Currently we only accept `type`, `udp4`.)
  45
  46 `createListener` is automatically registered as `message` event listener.
  47
  48
  49 ***
  50
  51
  52 ## class: dgram.Socket
  53
  54 You can create `dgram.Socket` instance with `dgram.createSocket()`.
  55
  56
  57 ### Events
  58
  59
  60 #### `'close'`
  61 * `callback: Function()`
  62
  63 Emitted when socket closed.
  64
  65
  66 #### `'error'`
  67 * `callback: Function()`
  68
  69 Emitted when an error occurs.
  70
  71
  72 #### `'listening'`
  73 * `callback: Function()`
  74
  75 Emitted when socket is ready to receive data.
  76
  77
  78 #### `'message'`
  79 * `callback: Function(msg, rinfo)`
  80  * `msg: Buffer`
  81  * `rinfo: Object`
  82    * `address: String`
  83    * `family: String`: it indicates an address family either `IPv4` or `IPv6`
  84    * `port: Number`
  85
  86 Emitted when message comes to the socket.
  87
  88
  89
  90 ### Methods
  91
  92
  93 #### socket.address()
  94
  95 Returns an object with the properties `address`, `port` and `family`. Basically the returned object is same with the object `rinfo` mentioned above.
  96
  97
  98 #### socket.addMembership(multicastAddress[, multicastInterface])
  99 * `multicastAddress: String`
 100 * `multicastInterface: String`
 101
 102 Joins for socket the given multicast group with given `multicastAddress` and `multicastInterface`.
 103
 104
 105 #### socket.dropMembership(multicastAddress[, multicastInterface])
 106 * `multicastAddress: String`
 107 * `multicastInterface: String`
 108
 109 Leaves for socket the given multicast group with given `multicastAddress` and `multicastInterface`.
 110
 111
 112 #### socket.bind([port][, address][, bindListener])
 113 #### socket.bind(options[, bindListener])
 114 * `port: Number`, if it is not specified, OS will bind socket with a random port.
 115 * `options: Object`
 116  * `port: Number`
 117  * `address: String`, Default: `0.0.0.0`
 118 * `bindListener: Function()`
 119
 120 Binds `net.Socket` with given `address` and `port`.
 121
 122 `bindListener` is automatically registered as `listening` event listener.
 123
 124
 125 #### socket.close([closeListener])
 126 * `closeListener: Function()`
 127
 128 Stops listening data.
 129
 130 `closeListener` is registered as `close` event listener.
 131
 132
 133 #### socket.setBroadcast(flag)
 134 * `flag: Boolean`
 135
 136 Sets or clears the `SO_BROADCAST` socket option.
 137
 138
 139 #### socket.setTTL(ttl)
 140 * `ttl: Number`, it should be between 1 and 255.
 141
 142 Sets the `IP_TTL` socket option.
 143
 144
 145 #### socket.send(msg, [offset, length], port, address[, sendListener])
 146 * `msg: Buffer | String | Array`
 147 * `offset: Number`, is is only valid when `msg` is Buffer.
 148 * `length: Number`, is is only valid when `msg` is Buffer.
 149 * `port: Number`
 150 * `address: String`, Default: `127.0.0.1` or `::1`
 151 * `sendListener: Function(err, length)`
 152  * `err: Null | Error`
 153    * `code: String`, temporally, it is just a String of *"error"*.
 154    * `errno: String`, it is same with `code`
 155    * `syscall: Number`
 156    * `address: String`
 157    * `port: Number`
 158  * `length: Number`, it indicates the length of data.
 159
 160 Sends the message to the destination with given `address` and `port`.
 161
 162 If send operation is successfully completed, `sendListener` will be called with Null and the length of data, otherwise with Error object and the length of data.
 163
 164
 165 #### socket.setMulticastLoopback(flag)
 166 * `flag: Boolean`
 167
 168 Sets or clears the `IP_MULTICAST_LOOP` socket option.
 169
 170
 171 #### socket.setMulticastTTL(ttl)
 172 * `ttl: Number`, it should be between 0 and 255.
 173
 174 Sets the `IP_MULTICAST_TTL` socket option.