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

   1 # Module: http
   2
   3 IoT.js provides HTTP to support HTTP server and client enabling users to receive/send HTTP request easily.
   4
   5 ## Methods
   6 ### http.createServer(requestListener)
   7 * `requestListener: Function`
   8 * Return: `http.Server` instance
   9
  10
  11 ### http.request(options[, callback])
  12 * `options: Object`
  13 * `callback: Function`
  14 * Return: `http.ClientRequest` instance
  15
  16 ### http.get(options[, callback])
  17 * `options: Object`
  18 * `callback: Function`
  19 * Return: `http.ClientRequest` instance
  20
  21 Same as http.request except that `http.get` automatically call `req.end()` at the end.
  22
  23
  24 ## Class: http.Server
  25
  26 ### Event
  27
  28 #### 'request'
  29 * `request: http.IncomingMessage` instance.
  30 * `response: http.ServerResponse` instance.
  31 After request header is parsed, this event will be fired.
  32
  33 #### 'connection'
  34 This event is emitted when new TCP connection is established.
  35
  36 #### 'close'
  37 This event is emitted when server is closed.
  38
  39 ### Method
  40
  41 #### listen(port[, hostname][, backlog][, callback])
  42 * `port: Number`
  43 * `host: String`
  44 * `backlog: Number`
  45 * `callback: Function`
  46
  47 Wait for new TCP connection with specified port and hostname. If no hostname is provided, server accepts any IP address.
  48 `backlog` is maximum pending connections. Default backlog length is 511.
  49 `callback` will be called when server has been bound.
  50
  51 #### close([callback])
  52 * `callback: Function`
  53
  54 Stop accepting new connection to this server. However, the existing connections are preserved. When server is finally closed after all connections are closed, a callback is called.
  55
  56 #### setTimeout(ms, cb)
  57
  58 * `ms: Number`
  59 * `cb: Function`
  60
  61 Registers cb for 'timeout' event and sets socket's timeout value to ms. This event will be triggered by the underlying socket's 'timeout' event.
  62
  63 If cb is not provided, the socket will be destroyed automatically after timeout.
  64 If you provide cb, you should handle the socket's timeout.
  65
  66 Default timeout for server is 2 minutes.
  67
  68 ### Member Variable
  69 #### timeout
  70 Server's timeout value. Default value is 2 minutes.
  71
  72
  73 ## Class: http.ClientRequest
  74 ### Event
  75
  76 #### 'response'
  77 * `response: http.IncomingMessage` instance
  78
  79 This event is emitted when server's response header is parsed. ` http.IncomingMessage` object is passed as argument to handler.
  80
  81
  82 #### 'socket'
  83 * `Net.socket` instance
  84
  85 This event is emitted when a socket is assigned to this request. `Net.socket` object is passed as argument to handler.
  86
  87 After response header is parsed, this event will be fired.
  88
  89 ### Method
  90
  91 #### write(data[, callback])
  92 * `data: Buffer|String`
  93 * `callback: Function`
  94
  95 Sends `data` as a request body. `callback` will be called when data is flushed.
  96
  97
  98 #### end([data][, callback])
  99 * `data: Buffer|String`
 100 * `callback: Function`
 101
 102 Finishes sending the request.
 103
 104 If `data` is provided, it sends `data` first, and finishes.
 105
 106 If `callback` is specified, it is called when the request stream is finished.
 107
 108
 109
 110 #### setTimeout(ms, cb)
 111
 112 * `ms: Number`
 113 * `cb: Function`
 114
 115 Registers cb for 'timeout' event and set socket's timeout value to ms. This event will be triggered by the underlying socket's 'timeout' event.
 116
 117 If cb is not provided, the socket will be destroyed automatically after timeout.
 118 If you provides cb, you should handle the socket's timeout.
 119
 120
 121 ## Class: http.ServerResponse
 122 ### Event
 123 #### 'end'
 124 This event is fired when no more data to be sent.
 125
 126 #### 'close'
 127 When underlying connection is closed, 'close' event is emitted.
 128
 129 #### 'finish'
 130 This event is emitted when the response has been sent. It does not guarantee that client has received data yet.
 131
 132 ### Method
 133 #### writeHead(statusCode[, statusMessage][, headers])
 134 * `statusCode: Number`
 135 * `statusMessage: String`
 136 * `headers: Object`
 137
 138 Sets response's header. `headers` is a map between field and value in header.
 139
 140 #### setHeader(name, value)
 141 * `name: String`
 142 * `value: `
 143
 144 Sets response's header field(`name`) to `value`. If the field exists, it overwrites the existing value.
 145
 146 #### getHeader(name)
 147 * `name: String`
 148
 149 Returns `name` field of response's header
 150
 151 #### removeHeader(name)
 152 * `name: String`
 153
 154 Removes `name` field from response's header
 155
 156 #### write(data[, callback])
 157 * `data: Buffer|String`
 158 * `callback: Function`
 159
 160 Sends `data` as a response body. `callback` will be called when data is flushed.
 161
 162 #### end([data][, callback])
 163 * `data: Buffer|String`
 164 * `callback: Function`
 165
 166 Finishes sending the response.
 167
 168 If `data` is provided, it sends `data` first, and finishes.
 169
 170 If `callback` is specified, it is called when the response stream is finished.
 171
 172 #### setTimeout(ms, cb)
 173
 174 * `ms: Number`
 175 * `cb: Function`
 176
 177 Registers cb for 'timeout' event and set socket's timeout value to ms. This event will be triggered by the underlying socket's 'timeout' event.
 178
 179
 180
 181 ## Class: http.IncomingMessage
 182
 183 http.IncomingMessage inherits [`Stream.readable`](IoT.js-API-Stream.md)
 184
 185 ### Event
 186 #### 'end'
 187 This event is fired when no more data to be received.
 188
 189 #### 'close'
 190 When underlying connection is closed, 'close' event is emitted.
 191
 192 ### Method
 193 #### setTimeout(ms, cb)
 194
 195 * `ms: Number`
 196 * `cb: Function`
 197
 198 Registers cb for 'timeout' event set socket's timeout value to ms. This event will be triggered by the underlying socket's 'timeout' event.
 199
 200
 201
 202 ### Member Variable
 203 #### headers
 204 HTTP header object.
 205
 206 #### method
 207 Requests method as `String`
 208
 209 #### url
 210 Requests URL as `String`
 211
 212 #### statusCode
 213 HTTP response status code as `Number` of 3-digit.
 214
 215 #### statusMessage
 216 HTTP response status message as `String`
 217
 218 #### socket
 219 Underlying socket