http.md_w3cschool

`ngui/http`

提供http与https协议的客服端支持

可以使用get方式访问服务端数据，并可很方便的将这些数据保存到本地

也可使用post方式发送数据或上传文件到服务器

`Enum: HttpMethod`

发送http的方法

HTTP_METHOD_GET

HTTP_METHOD_POST

HTTP_METHOD_HEAD

HTTP_METHOD_DELETE

HTTP_METHOD_PUT

`Enum: HttpReadyState`

HttpClientRequest请求状态，状态的变化触发onreadystateChange

HTTP_READY_STATE_INITIAL

未初始化，未调用send()或一个请求完成后

HTTP_READY_STATE_READY

准备发送状态，调用完send()后的正在建立连接或打开本地缓存

HTTP_READY_STATE_SENDING

连接已经建立开始发送请求与数据，如果使用本地缓存，这个状态不会被触发

触发这个状态后会连续触发onwrite事件直到数据发送完成

HTTP_READY_STATE_RESPONSE

请求发送完成，开始接收响应数据

触发这个状态后会连续触发ondata事件直到响应完成

HTTP_READY_STATE_COMPLETED

完成请求，如果是一个没有异常的请求，会触发onend事件

`Class: HttpClientRequest`

Http客服端请求类

HttpClientRequest.onError

请求出现异常时触发,触发异常一般会接着触发onabort.

返回的事件数据为Error类型

HttpClientRequest.onWrite

发送数据时连续触发,直到数据发送完成

HttpClientRequest.onHeader

接收响应头完成触发

HttpClientRequest.onData

接收响应数据时连续触发,直到数据接收完成,事件数据为主体响应片段Buffer

HttpClientRequest.onEnd

请求完成触发

HttpClientRequest.onReadystateChange

状态变化时触发

HttpClientRequest.onTimeout

超时时触发，HttpClientRequest.setTimeout() 设置超时时间

HttpClientRequest.onAbort

请求被中止时触发

Example:

var cl = new HttpClientRequest()
// Prints: Error: Network error
cl.onError = function(ev) { console.log(ev.data) }
// Prints: <Buffer 00 aa cf 67>
cl.onData = function(ev) { console.log(ev.data) }
// Prints: 4 200
cl.onReadystateChange = function() { console.log(this.readyState, this.statusCode) }

HttpClientRequest.constructor()

HttpClientRequest.setMethod(method)

设置请求方法默认为HTTP_METHOD_GET方法

@arg method {HttpMethod}

HttpClientRequest.setUrl(url)

@arg url {String}

HttpClientRequest.setSavePath(path)

设置一个路径将数据保存到本地

@arg path {String}

HttpClientRequest.setUsername(username)

http请求头Authorization用户名

@arg username {String}

HttpClientRequest.setPassword(password)

http请求头Authorization密码

@arg password {String}

HttpClientRequest.disableCache(disable)

禁用缓存,既不保存下载的数据也不读取本地缓存数据

@arg disable {bool}

HttpClientRequest.disableCookie(disable)

完全禁用cookie,不保存也不读取

@arg disable {bool}

HttpClientRequest.disableSendCookie(disable)

只是不发送本地保存的cookie,但保存服务器设置的cookie

@arg disable {bool}

HttpClientRequest.disableSslVerify(disable)

禁用ssl认证,如果站点没有合法的证书,默认请求会发送失败,但可以设置禁用忽略认证

@arg disable {bool}

HttpClientRequest.setRequestHeader(headerName, value)

@arg headerName {String} ascii string
@arg value {String}

HttpClientRequest.setForm(formName, value)

设置表单数据

待发送请求时会自动添加请求头 Content-Type: application/x-www-form-urlencoded; charset=utf-8

必须使用HTTP_METHOD_POST方法发送请求否则会忽略表单

@arg formName {String}
@arg value {String}

HttpClientRequest.setUploadFile(formName, localPath)

上传本地文件设置以multipart/form-data形式, 并在发送请求时自动添加请求头

Content-Type: multipart/form-data; boundary=----NGUIFormBoundaryrGKCBY7qhFd3TrwA

必须使用HTTP_METHOD_POST方法发送请求否则会忽略表单

@arg formName {String}
@arg localPath {String}

HttpClientRequest.clearRequestHeader()

清空原先设置的请示头

HttpClientRequest.clearFormData()

清空原先设置的表单

HttpClientRequest.getResponseHeader(headerName)

@arg headerName {String}
@ret {String}

HttpClientRequest.getAllResponseHeaders()

@ret {Object}

HttpClientRequest.setKeepAlive(keepAlive)

设置为true保持这个http连接,如果下次有这个服务器的请求会直接使用需无需再重新建立socket连接

当然这个功能需要服务器支持,如果服务完成请求后立即断开连接,那就是无效的。

默认为true

@arg keepAlive {bool}

HttpClientRequest.setTimeout(time)

设置一个超时时间,达到超时时间还未完成请求客户端会立即主动中止这个请求,并触发onTimeout与onAbort事件

默认为0表示永远不超时,单位为毫秒ms

@arg time {uint} ms

HttpClientRequest.send([data])

发送请求与数据,如果要发送数据这个请求必须为HTTP_METHOD_POST方式,否则会忽略这些数据

如果在这里设置数据，那么之前设置的表单数据将被完全忽略

@arg [data] {String|ArrayBuffer|Buffer}

HttpClientRequest.pause()

暂停请求

HttpClientRequest.resume()

恢复暂停的请求

HttpClientRequest.abort()

中止请求

Example:

var cl = new http.HttpClientRequest()
cl.setUrl('https://www.baidu.com/')
cl2.setSavePath(path.documents('baidu.html'));
// Prints: 
// <Buffer 3c 68 74 6d 6c 3e 0d ... >
// <Buffer 3c 21 44 4f 43 54 59 ... > 
// ...
cl.onData = function(ev) {
    console.log(ev.data);
}
cl.onEnd = function() {
    // Prints:
    // true
    // 4 200
    console.log(fs.existsSync(path.documents('baidu.html')))
    console.log(this.readyState, this.statusCode)
}
cl.send();


var cl2 = new http.HttpClientRequest()
cl2.setUrl('http://192.168.1.100:1026/Tools/uploadFile')
cl2.setMethod(http.HTTP_METHOD_POST);
cl2.setUploadFile('uploadFile', path.resources('util/http.js'))
cl2.onEnd = function() {
    // Prints: complete
    console.log('complete')
}
cl2.send();

`Object: RequestOptions`

调用request()orrequestSync()时使用的选项数据, 这是个Object类型描述并没有实际存在的构造函数

RequestOptions.url

{String}

RequestOptions.method

{HttpMethod}

RequestOptions.headers

{Object}

RequestOptions.postData

{Buffer|ArrayBuffer|String}

RequestOptions.save

{String}

RequestOptions.upload

{String}

RequestOptions.disableSslVerify

{bool}

RequestOptions.disableCache

{bool}

RequestOptions.disableCookie

{bool}

Example:

// uploat file and save body data
var opts = {
    url: 'http://192.168.1.100:1026/Tools/uploadFile',
    method: http.HTTP_METHOD_POST,
    headers: { test: 'test' },
    // postData: 'a=A',
    save: path.documents('uploadFile.html'),
    upload: path.resources('util/http.js'),
    disableSslVerify: false,
    disableCache: true,
    disableCookie: false,
};
http.request(opts, function(buff){ 
    // Prints: <Buffer ...>
    console.log(buff)
}.catch(e=>{ /*Fail*/ }))

request(options[,cb])

发送http请通过RequestOptions参数，并返回中止id失败抛出异常

成功通过回调返回Buffer

Callback: cb(buff) (buff:Buffer)

@arg options {RequestOptions}
@arg [cb] {Function}
@ret {uint} return req id

Example:

var abortid = http.request({
    url: 'http://192.168.1.100:1026/',
}, function(buff){ /*Success*/ }.catch(e=>{ /*Fail*/ }))

requestStream(options[,cb])

发送http请通过RequestOptions参数，并返回中止id失败抛出异常

成功通过回调返回StreamData

Callback: cb(data) (data:StreamData)

@arg options {RequestOptions}
@arg [cb] {Function}
@ret {uint} return req id

Example:

var abortid = http.requestStream({ 
    url: 'http://192.168.1.100:1026/' 
}, function(d){ 
    // Prints: <Buffer ...>
    console.log(d.data) 
}.catch(e=>{ /*Fail*/ }));

requestSync(options)

同步发送http请求通过RequestOptions参数，失败抛出异常

成功返回主体Buffer数据

@arg options {Object}
@ret {Buffer}

Example:

// Prints: <Buffer ...>
try {
    console.log(http.requestSync({ url: 'http://192.168.1.100:1026/' }));
} catch(e) { /*Fail*/ }

download(url,save[,cb])

下载并保存文件，返回中止id失败抛出异常

Callback: cb()

@arg url {String} 请求的url
@arg save {String} 本地保存路径
@arg [cb] {Function}
@ret {uint} return req id

upload(url,localPath[,cb])

上传本地文件到服务器，返回中止id失败抛出异常

Callback: cb()

@arg url {String} 请求有url
@arg localPath {String} 要上传的本地文件路径
@arg [cb] {Function}
@ret {uint} return req id

get(url[,cb])

发送HTTP_METHOD_GET请求，返回中止id失败抛出异常

成功通过回调返回响应数据

Callback cb(buff) cb(buff:Buffer)

@arg url {String}
@arg [cb] {Function}
@ret {uint} return req id

post(url,data[,cb])

发送HTTP_METHOD_POST请求，返回中止id失败抛出异常

成功通过回调返回响应数据

Callback cb(buff) cb(buff:Buffer)

@arg url {String}
@arg data {String|ArrayBuffer|Buffer}
@arg [cb] {Function}
@ret {uint} return req id

getSync(url)

同步发送HTTP_METHOD_GET请求，成功返回数据Buffer，失败抛出异常

@arg url {String}
@ret {Buffer}

postSync(url,data)

同步发送HTTP_METHOD_POST请求，成功返回数据Buffer，失败抛出异常

@arg url {String}
@arg data {String|ArrayBuffer|Buffer}
@ret {Buffer}

abort(id)

通过传入中止id强制中止异步任务与之相似的方法有fs.abort() or reader.abort()

@arg id {uint} abort id

Example:

var id0 = http.download('http://192.168.1.100:1026/libs/util/http.js');
var id1 = http.upload('http://192.168.1.100:1026/Tools/uploadFile', path.resources('util/http.js'));
// force abort task
http.abort(id0);
http.abort(id1);

userAgent()

返回 User Agent

@ret {String}

setUserAgent(userAgent)

设置 User Agent

@arg userAgent {String}

cachePath()

返回缓存路径

@ret {String}

setCachePath(path)

设置缓存路径

@arg path {String}

clearCache()

清空缓存数据文件

clearCookie()

清空cookie

http.md

ngui/http

Enum: HttpMethod

HTTP_METHOD_GET

HTTP_METHOD_POST

HTTP_METHOD_HEAD

HTTP_METHOD_DELETE

HTTP_METHOD_PUT

Enum: HttpReadyState

HTTP_READY_STATE_INITIAL

HTTP_READY_STATE_READY

HTTP_READY_STATE_SENDING

HTTP_READY_STATE_RESPONSE

HTTP_READY_STATE_COMPLETED

Class: HttpClientRequest

HttpClientRequest.onError

HttpClientRequest.onWrite

HttpClientRequest.onHeader

HttpClientRequest.onData

HttpClientRequest.onEnd

HttpClientRequest.onReadystateChange

HttpClientRequest.onTimeout

HttpClientRequest.onAbort

HttpClientRequest.constructor()

HttpClientRequest.setMethod(method)

HttpClientRequest.setUrl(url)

HttpClientRequest.setSavePath(path)

HttpClientRequest.setUsername(username)

HttpClientRequest.setPassword(password)

HttpClientRequest.disableCache(disable)

HttpClientRequest.disableCookie(disable)

HttpClientRequest.disableSendCookie(disable)

HttpClientRequest.disableSslVerify(disable)

HttpClientRequest.setRequestHeader(headerName, value)

HttpClientRequest.setForm(formName, value)

HttpClientRequest.setUploadFile(formName, localPath)

HttpClientRequest.clearRequestHeader()

HttpClientRequest.clearFormData()

HttpClientRequest.getResponseHeader(headerName)

HttpClientRequest.getAllResponseHeaders()

HttpClientRequest.setKeepAlive(keepAlive)

HttpClientRequest.setTimeout(time)

HttpClientRequest.send([data])

HttpClientRequest.pause()

HttpClientRequest.resume()

HttpClientRequest.abort()

Get: HttpClientRequest.uploadTotal

Get: HttpClientRequest.uploadSize

Get: HttpClientRequest.downloadTotal

Get: HttpClientRequest.downloadSize

Get: HttpClientRequest.readyState

Get: HttpClientRequest.statusCode

Get: HttpClientRequest.url

Object: RequestOptions

RequestOptions.url

RequestOptions.method

RequestOptions.headers

RequestOptions.postData

RequestOptions.save

RequestOptions.upload

RequestOptions.disableSslVerify

RequestOptions.disableCache

RequestOptions.disableCookie

request(options[,cb])

requestStream(options[,cb])

requestSync(options)

download(url,save[,cb])

upload(url,localPath[,cb])

get(url[,cb])

post(url,data[,cb])

getSync(url)

postSync(url,data)

abort(id)

userAgent()

setUserAgent(userAgent)

cachePath()

setCachePath(path)

clearCache()

clearCookie()

`ngui/http`

`Enum: HttpMethod`

`Enum: HttpReadyState`

`Class: HttpClientRequest`

`Object: RequestOptions`