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

   1 ## Module: net
   2
   3 ### Platform Support
   4
   5 The following shows net module APIs available for each platform.
   6
   7 |  | Linux<br/>(Ubuntu) | Raspbian<br/>(Raspberry Pi) | Nuttx<br/>(STM32F4-Discovery) |
   8 | :---: | :---: | :---: | :---: |
   9 | net.createServer | O | O | O |
  10 | net.connect | O | O | O |
  11 | net.createConnection | O | O | O |
  12 | net.Server.listen | O | O | O |
  13 | net.Server.close | O | O | O |
  14 | net.Socket.connect | O | O | O |
  15 | net.Socket.write | O | O | O |
  16 | net.Socket.end | O | O | O |
  17 | net.Socket.destroy | O | O | O |
  18 | net.Socket.pause | O | O | O |
  19 | net.Socket.resume | O | O | O |
  20 | net.Socket.setTimeout | O | O | O |
  21 | net.Socket.setKeepAlive | X | X | X |
  22
  23 ※ When writable stream is finished but readable stream is still alive, IoT.js tries to shutdown the socket, not destroy.
  24 However on `nuttx` due to lack of implementation, it does nothing inside.
  25
  26 IoT.js provides asynchronous networking through Net module.
  27
  28 You can use this module with `require('net')` and create both servers and clients.
  29
  30 ### Module Functions
  31
  32 #### net.connect(options[, connectListener])
  33 #### net.connect(port[, host][, connectListener])
  34 #### net.createConnection(options[, connectListener])
  35 #### net.createConnection(port[, host][, connectListener])
  36 * `options: Object`
  37 * `port: Number`
  38 * `host: String`, Default: `localhost`
  39 * `connectListener: Function()`
  40
  41 Creates a `net.Socket` and connects to the supplied host.
  42
  43 It is equivalent to `new net.Socket()` followed by `socket.connect()`.
  44
  45
  46 #### net.createServer([options][, connectionListener])
  47 * `options: Object`
  48 * `connectionListener: Function(connection: net.Socket)`
  49
  50 Creates a TCP server according to `options`.
  51
  52 `connectionListener` is automatically registered as `connection` event listener.
  53
  54
  55 ***
  56
  57 ## class: net.Server
  58
  59 You can create `net.Server` instance with `net.createServer()`.
  60
  61
  62 ### Events
  63
  64 #### `'close'`
  65 * `callback: Function()`
  66
  67 Emitted when server closed.
  68
  69 Note that this event will be emitted after all existing connections are closed.
  70
  71
  72 #### `'connection(socket)'`
  73 * `callback: Function(socket)`
  74  * `socket: net.Socket`
  75
  76 Emitted when new connection is established.
  77
  78
  79 #### `'error'`
  80 * `callback: Function()`
  81
  82 Emitted when an error occurs.
  83
  84
  85 #### `'listening'`
  86 * `callback: Function()`
  87
  88 Emitted when server has been started listening.
  89
  90
  91 ### Methods
  92
  93 #### server.close([closeListener])
  94 * `closeListener: Function()`
  95
  96 Stops listening new arriving connection.
  97
  98 Server socket will finally close when all existing connections are closed, then emit 'close' event.
  99
 100 `closeListener` is registered as `close` event listener.
 101
 102
 103 #### server.listen(port[, host][, backlog][, listenListener])
 104 #### server.listen(options[, listenListener])
 105 * `port: Number`
 106 * `host: String`
 107 * `backlog: Number`
 108 * `listenListener: Function()`
 109
 110 Starts listening and accepting connections on specified port and host.
 111
 112
 113 ***
 114
 115 ## class: net.Socket
 116
 117 net.Socket inherits [`Stream.Duplex`](IoT.js-API-Stream.md)
 118
 119 ### Constructor
 120
 121 #### new net.Socket([options])
 122 * `options: Object`
 123
 124 Creates a new socket object.
 125
 126 `options` is an object specifying following information:
 127
 128 * `allowHalfOpen: Boolean`
 129
 130
 131
 132 ### Events
 133
 134
 135 #### `'connect'`
 136 * `callback: Function()`
 137
 138 Emitted after connection is established.
 139
 140
 141 #### `'close'`
 142 * `callback: Function()`
 143
 144 Emitted when the socket closed.
 145
 146
 147 #### `'data'`
 148 * `callback: Function(data)`
 149  * `data: Buffer | String`
 150
 151 Emitted when data is received from the connection.
 152
 153
 154 #### `'drain'`
 155 * `callback: Function()`
 156
 157 Emitted when the write buffer becomes empty.
 158
 159
 160 #### `'end'`
 161 * `callback: Function()`
 162
 163 Emitted when FIN packet received.
 164
 165
 166 #### `'error'`
 167 * `callback: Function()`
 168
 169 Emitted when an error occurs.
 170
 171
 172 #### `'lookup'`
 173 * `callback: Function(err, address, family)`
 174  * `err: Error | Null`
 175  * `address: String`
 176  * `family: String | Null`
 177
 178 Emitted after resolving hostname.
 179
 180
 181 #### `'timeout'`
 182 * `callback: Function()`
 183
 184 Emitted when the connection remains idle for specified timeout.
 185
 186
 187 ### Methods
 188
 189 #### socket.connect(options[, connectListener])
 190 #### socket.connect(port[, host][, connectListener])
 191 * `options: Object`
 192 * `port: Number`
 193 * 'host: String`, Default: `'localhost'`
 194
 195 Opens the connection with supplied port and host.
 196
 197 `options` is an object specifying following information:
 198 * `port: Number` - port connect to (required)
 199 * `host: String` - host connect to (optional, default: `'127.0.0.1'`)
 200
 201 `connectionListener` is automatically registered as `connect` event listener which will be emitted when the connection is established.
 202
 203
 204 #### socket.destroy()
 205
 206 Destroys the socket.
 207
 208
 209 #### socket.end([data][, callback])
 210
 211 * `data: String | Buffer`
 212 * `callback: Function()`
 213
 214 Half-closes the socket.
 215
 216 If `data` is given it is equivalent to `socket.write(data)` followed by `socket.end()`.
 217
 218 * `data: String | Buffer`
 219
 220
 221 #### socket.pause()
 222
 223 Pauses reading data.
 224
 225
 226 #### socket.resume()
 227
 228 Resumes reading data after a call to `pause()`.
 229
 230
 231 #### socket.setKeepAlive([enable][, initialDelay])
 232
 233 * `enable: Boolean`
 234 * `initialDelay: Number`, Default: `0`
 235
 236 Enables or disables keep-alive functionality.
 237
 238
 239 #### socket.setTimeout(timeout[, callback])
 240 * `timeout: Number`
 241 * `callback: Function()`
 242
 243 Sets timeout for the socket.
 244
 245 If the socket is inactive for `timeout` milliseconds, `'timeout'` event will emit.
 246
 247 `callback` is registered as `timeout` event listener.
 248
 249
 250 #### socket.write(data[, callback])
 251 * `data: String | Buffer`
 252 * `callback: Function()`
 253
 254 Sends `data` on the socket.
 255
 256 `callback` function will be called after given data is flushed through the connection.