From 19526e3294c48bcb9056eeb57cdec26fd02a6fd4 Mon Sep 17 00:00:00 2001 From: clevercong Date: Fri, 4 Mar 2022 17:01:25 +0800 Subject: [PATCH] add netstack js api doc. Signed-off-by: clevercong --- .../reference/apis/js-apis-http.md | 466 ++++++ .../reference/apis/js-apis-socket.md | 1374 +++++++++++++++++ .../reference/apis/js-apis-webSocket.md | 600 +++++++ 3 files changed, 2440 insertions(+) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-http.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-socket.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-webSocket.md diff --git a/zh-cn/application-dev/reference/apis/js-apis-http.md b/zh-cn/application-dev/reference/apis/js-apis-http.md new file mode 100644 index 0000000000..ff82b65406 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-http.md @@ -0,0 +1,466 @@ +# 数据请求 + +- [导入模块](#s56d19203690d4782bfc74069abb6bd71) +- [权限列表](#section11257113618419) +- [完整示例](#section119676440437) +- [http.createHttp](#section375081875219) +- [HttpRequest](#section775213486457) + - [request](#section08941433184616) + - [request](#section1361727114718) + - [request](#section47538114482) + - [destroy](#section613614500483) + - [on\('headerReceive'\)](#section617831813498) + - [off\('headerReceive'\)](#section017612118508) + - [on\('headersReceive'\)8+](#section6178318134982) + - [off\('headersReceive'\)8+](#section0176121185082) + - [once\('headersReceive'\)8+](#section68221041134718) +- [HttpRequestOptions](#section12262183471518) +- [RequestMethod](#section63024410264) +- [ResponseCode](#section769218832018) +- [HttpResponse](#section15920192914312) + +>![](public_sys-resources/icon-note.gif) **说明：** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +>本模块所有接口需要设备具有系统能力：SystemCapability.Communication.NetStack + +## 导入模块 + +``` +import http from '@ohos.net.http'; +``` + +## 权限列表 + +ohos.permission.INTERNET + +## 完整示例 + +``` +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个http请求任务，不可复用 +let httpRequest = http.createHttp(); +// 用于订阅http响应头，此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始，使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (data) => { + console.info('header: ' + data.header); +}); +httpRequest.request( + // 填写http请求的url地址，可以带参数也可以不带参数。URL地址需要开发者自定义。GET请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: 'POST', // 可选，默认为“GET” + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + + extraData: { + "data": "data to send", + }, + connectTimeout: 60000, // 可选，默认为60s + readTimeout: 60000, // 可选，默认为60s + },(err, data) => { + if (!err) { + // data.result为http响应内容，可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为http响应头，可根据业务需要进行解析 + console.info('header:' + data.header); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + err); + // 当该请求使用完毕时，调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个http，里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header 事件。每一个HttpRequest对象对应一个Http请求。如需发起多个Http请求，须为每个Http请求创建对应HttpRequest对象。 + +- 返回值 + + | 类型 | 说明 | + | :---------- | :----------------------------------------------------------- | + | HttpRequest | 返回一个HttpRequest对象，里面包括request、destroy、on和off方法。 | + +- 示例 + + ``` + import http from '@ohos.net.http'; + let httpRequest = http.createHttp(); + ``` + + +## HttpRequest + +http请求任务。在调用HttpRequest的方法前，需要先通过[createHttp\(\)](#section375081875219)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址，发起HTTP网络请求，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------- | ---- | ----------------------- | + | url | string | 是 | 发起网络请求的URL地址。 | + | callback | AsyncCallback\<[HttpResponse](#section12262183471518)\> | 是 | 回调函数。 | + +- 示例 + + ``` + let httpRequest = http.createHttp(); + httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + data.header); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + err.data); + } + }); + ``` + + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项，发起HTTP网络请求，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------- | ---- | -------------------------------------------------- | + | url | string | 是 | 发起网络请求的URL地址。 | + | options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#section12262183471518)。 | + | callback | AsyncCallback\<[HttpResponse](#section12262183471518)\> | 是 | 回调函数。 | + +- 示例 + + ``` + let httpRequest= http.createHttp(); + httpRequest.request("EXAMPLE_URL", + { + method: 'GET', + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 + },(err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + data.header); + console.info('cookies:' + data.cookies); // 8+ + console.info('header['Content-Type']:' + data.header['Content-Type']); + console.info('header['Status-Line']:' + data.header['Status-Line']); + console.info('header.Date:' + data.header.Date); + console.info('header.Server:' + data.header.Server); + } else { + console.info('error:' + err.data); + } + }); + ``` + + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址，发起HTTP网络请求，使用Promise方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------ | ---- | -------------------------------------------------- | + | url | string | 是 | 发起网络请求的URL地址。 | + | options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#section12262183471518)。 | + +- 返回值 + + | 类型 | 说明 | + | :-------------------- | :-------------------------------- | + | Promise<[HttpResponse](#section12262183471518)> | 以Promise形式返回发起请求的结果。 | + + +- 示例 + + ``` + let httpRequest= http.createHttp(); + let promise = httpRequest.request("EXAMPLE_URL", { + method: "GET", + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } + }); + promise.then((value) => { + console.info('Result:' + value.result); + console.info('code:' + value.responseCode); + console.info('header:' + value.header); + console.info('cookies:' + value.cookies); // 8+ + console.info('header['Content-Type']:' + value.header['Content-Type']); + console.info('header['Status-Line']:' + value.header['Status-Line']); + console.info('header.Date:' + value.header.Date); + console.info('header.Server:' + value.header.Server); + }).catch((err) => { + console.error(`errCode:${err.code}, errMessage:${err.data}`); + }); + ``` + + +### destroy + +destroy\(\): void + +中断请求任务。 + +- 示例 + + ``` + let httpRequest= http.createHttp(); + httpRequest.destroy(); + ``` + + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\):void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明：** +> 此接口已废弃，建议使用on\('headersReceive'\)替代。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------- | ---- | ------------------------------------- | + | type | string | 是 | 订阅的事件类型，如：'headerReceive'。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let httpRequest= http.createHttp(); + httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + data.header); + } else { + console.info('error:' + err.data); + } + }); + ``` + + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\):void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明：** +> +>1. 此接口已废弃，建议使用off\('headersReceive'\)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------- | ---- | ------------------------------------- | + | type | string | 是 | 取消订阅的事件类型，'headerReceive'。 | + | callback | AsyncCallback\ | 否 | 回调函数。 | + +- 示例 + + ``` + let httpRequest= http.createHttp(); + httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + data.header); + } else { + console.info('error:' + err.data); + } + }); + httpRequest.off('headerReceive'); + ``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\):void + +订阅HTTP Response Header 事件。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------ | ---- | ---------------------------------- | + | type | string | 是 | 订阅的事件类型：'headersReceive'。 | + | callback | Callback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let httpRequest= http.createHttp(); + httpRequest.on('headersReceive', (data) => { + console.info('header: ' + data.header); + }); + ``` + + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\):void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------ | ---- | -------------------------------------- | + | type | string | 是 | 取消订阅的事件类型：'headersReceive'。 | + | callback | Callback\ | 否 | 回调函数。 | + +- 示例 + + ``` + let httpRequest= http.createHttp(); + httpRequest.off('headersReceive'); + ``` + +### once\('headersReceive'\)8+ + +once\(type: "headersReceive", callback: Callback\): void + +订阅HTTP Response Header 事件，但是只触发一次。一旦触发之后，订阅器就会被移除。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------ | ---- | ---------------------------------- | + | type | string | 是 | 订阅的事件类型：'headersReceive'。 | + | callback | Callback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let httpRequest= http.createHttp(); + httpRequest.once('headersReceive', (data) => { + console.info('header: ' + data.header); + }); + ``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +| 参数 | 类型 | 必填 | 说明 | +| -------------- | ------------------------------------ | ---- | ---------------------------------------------------------- | +| method | [RequestMethod](#section63024410264) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer8+ | 否 | 发送请求的额外数据。详见下方说明。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒（ms），默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒（ms），默认为60000ms。 | + +> ![](public_sys-resources/icon-note.gif) **说明：** +> +> 1. 当HTTP请求为POST、PUT等方法时，此字段为HTTP请求的content。 +> +> 2. 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时，此字段为HTTP请求的参数补充，参数内容会拼接到URL中进行发送。8+ +> +> 3. 开发者传入string对象，开发者需要自行编码，将编码后的string传入。8+ + +## RequestMethod + +HTTP 请求方法。 + +| **method 的合法值** | 说明 | +| :------------------ | :------------------ | +| OPTIONS | HTTP 请求 OPTIONS。 | +| GET | HTTP 请求 GET。 | +| HEAD | HTTP 请求 HEAD。 | +| POST | HTTP 请求 POST。 | +| PUT | HTTP 请求 PUT。 | +| DELETE | HTTP 请求 DELETE。 | +| TRACE | HTTP 请求 TRACE。 | +| CONNECT | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +| 变量 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求，但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理，但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误，服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留，将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求，但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源（网页）。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长，超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码，服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大，服务器无法处理，因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长（URI通常为网址），服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误，无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能，无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护，服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器，未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ---------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer8+ | 是 | Http请求根据响应头中Content-type类型返回对应的响应格式内容。详见下方说明。 | +| responseCode | [ResponseCode](#section769218832018) \| number | 是 | 回调函数执行成功时，此字段为[ResponseCode](#section769218832018)。若执行失败，错误码将会从AsyncCallback中的err字段返回。错误码如下：
- 200：通用错误
- 202：参数错误
- 300：I/O错误 | +| header | Object | 是 | 发起http请求返回来的响应头。当前返回的是JSON格式字符串，如需具体字段内容，需开发者自行解析。常见字段及解析方式如下：
- Content-Type：header['Content-Type']；
- Status-Line：header['Status-Line']；
- Date：header.Date/header['Date']；
- Server：header.Server/header['Server']； | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +> ![](public_sys-resources/icon-note.gif) **说明：** +> +> 根据响应头中Content-type类型的不同，返回的类型不同： +> +> - application/json：返回JSON格式的字符串，如需Http响应具体内容，需开发者自行解析 +> - application/octet-stream：ArrayBuffer +> - 其他：string diff --git a/zh-cn/application-dev/reference/apis/js-apis-socket.md b/zh-cn/application-dev/reference/apis/js-apis-socket.md new file mode 100644 index 0000000000..94c71c7236 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-socket.md @@ -0,0 +1,1374 @@ +# Socket连接 + +- [支持设备](#section11223131205610) +- [导入模块](#s56d19203690d4782bfc74069abb6bd71) +- [权限列表](#section11257113618419) +- [socket.constructUDPSocketInstance](#section375081875219) +- [UDPSocket](#section1957294511568) + - [bind](#section7382103811272) + - [bind](#section12433131831219) + - [send](#section1859172655111) + - [send](#section61591275527) + - [close](#section068563155214) + - [close](#section1788163335319) + - [getState](#section1028719549533) + - [getState](#section1333814412551) + - [setExtraOptions](#section16890953175514) + - [setExtraOptions](#section5493159165611) + - [on\('message'\)](#section1632573015551) + - [off\('message'\)](#section789519374558) + - [on\('listening' | 'close'\)](#section20461174410557) + - [off\('listening' | 'close'\)](#section649105218559) + - [on\('error'\)](#section16745135855515) + - [off\('error'\)](#section49111157568) + +- [NetAddress](#section159132241295) +- [UDPSendOptions](#section13297558184010) +- [UDPExtraOptions](#section1650575184117) +- [SocketStateBase](#section164609984111) +- [SocketRemoteInfo](#section46021613174115) +- [socket.constructTCPSocketInstance](#section283119484161) +- [TCPSocket](#section1180211014548) + - [bind](#section8465924145710) + - [bind](#section27150134582) + - [connect](#section82761299586) + - [connect](#section374992304) + - [send](#section74991317709) + - [send](#section2841321507) + - [close](#section71701043701) + - [close](#section13523755306) + - [getRemoteAddress](#section1268431414115) + - [getRemoteAddress](#section89019337116) + - [getState](#section830554511115) + - [getState](#section3460522026) + - [setExtraOptions](#section738911419219) + - [setExtraOptions](#section1847278215) + - [on\('message'\)](#section642292019182) + - [off\('message'\)](#section8426920151811) + - [on\('connect' | 'close'\)](#section6429202001812) + - [off\('connect' | 'close'\)](#section54325209187) + - [on\('error'\)](#section19436172061817) + - [off\('error'\)](#section6438202013182) + +- [TCPConnectOptions](#section13821005712) +- [TCPSendOptions](#section1689232415715) +- [TCPExtraOptions](#section13892555115718) + +>![](public_sys-resources/icon-note.gif) **说明：** +> +>本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +>本模块所有接口需要设备具有系统能力：SystemCapability.Communication.NetStack + +## 导入模块 + +``` +import socket from '@ohos.net.socket'; +``` + +## 权限列表 + +ohos.permission.INTERNET + +## socket.constructUDPSocketInstance + +constructUDPSocketInstance\(\): UDPSocket + +创建一个UDPSocket对象。 + +- 返回值 + + | 类型 | 说明 | + | :--------------------------------- | :---------------------- | + | [UDPSocket](#section1957294511568) | 返回一个UDPSocket对象。 | + + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + ``` + + +## UDPSocket + +UDPSocket连接。在调用UDPSocket的方法前，需要先通过[socket.constructUDPSocketInstance](#section375081875219)创建UDPSocket对象。 + +### bind + +bind\(address: NetAddress, callback: AsyncCallback\): void + +绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------- | ---- | ------------------------------------------------------ | + | address | [NetAddress](#section159132241295) | 是 | 目标地址信息，参考[NetAddress](#section159132241295)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { + if (err) { + console.log('bind fail'); + return; + } + console.log('bind success'); + }) + ``` + + +### bind + +bind\(address: NetAddress\): Promise + +绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------- | ---- | ------------------------------------------------------ | + | address | [NetAddress](#section159132241295) | 是 | 目标地址信息，参考[NetAddress](#section159132241295)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :----------------------------------------- | + | Promise\ | 以Promise形式异步返回UDPSocket绑定的结果。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + let promise = udp.bind({address: '192.168.xx.xxx', port: 8080, family: 1}); + promise .then(() => { + console.log('bind success'); + }).catch(err => { + console.log('bind fail'); + }); + ``` + + +### send + +send\(options: UDPSendOptions, callback: AsyncCallback\): void + +通过UDPSocket连接发送数据。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [UDPSendOptions](#section13297558184010) | 是 | UDPSocket发送参数，参考[UDPSendOptions](#section13297558184010)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.send({ + data:'Hello, server!', + address: { + address:'192.168.xx.xxx', + port:xxxx, + family:1 + } + }, err=> { + if (err) { + console.log('send fail'); + return; + } + console.log('send success'); + }) + ``` + + +### send + +send\(options: UDPSendOptions\): Promise + +通过UDPSocket连接发送数据。使用Promise方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [UDPSendOptions](#section13297558184010) | 是 | UDPSocket发送参数，参考[UDPSendOptions](#section13297558184010)。 | + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :--------------------------------------------- | + | Promise\ | 以Promise形式返回UDPSocket连接发送数据的结果。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + let promise = udp.send({ + data:'Hello, server!', + address: { + address:'192.168.xx.xxx', + port:xxxx, + family:1 + } + }); + promise.then(() => { + console.log('send success'); + }).catch(err => { + console.log('send fail'); + }); + ``` + + +### close + +close\(callback: AsyncCallback\): void + +关闭UDPSocket连接。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | --------------------- | ---- | ---------- | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.close(err => { + if (err) { + console.log('close fail'); + return; + } + console.log('close success'); + }) + ``` + + +### close + +close\(\): Promise + +关闭UDPSocket连接。使用Promise方式作为异步方法。 + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :----------------------------------------- | + | Promise\ | 以Promise形式返回关闭UDPSocket连接的结果。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + let promise = udp.close(); + promise.then(() => { + console.log('close success'); + }).catch(err => { + console.log('close fail'); + }); + ``` + + +### getState + +getState\(callback: AsyncCallback\): void + +获取UDPSocket状态。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section7382103811272)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------ | ---- | ---------- | + | callback | AsyncCallback<[SocketStateBase](#section164609984111)> | 是 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { + if (err) { + console.log('bind fail'); + return; + } + console.log('bind success'); + udp.getState((err, data) => { + if (err) { + console.log('getState fail'); + return; + } + console.log('getState success:' + JSON.stringify(data)); + }) + }) + ``` + + +### getState + +getState\(\): Promise + +获取UDPSocket状态。使用Promise方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section7382103811272)方法调用成功后，才可调用此方法。 + +- 返回值 + + | 类型 | 说明 | + | :----------------------------------------------- | :----------------------------------------- | + | Promise<[SocketStateBase](#section164609984111)> | 以Promise形式返回获取UDPSocket状态的结果。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { + if (err) { + console.log('bind fail'); + return; + } + console.log('bind success'); + let promise = udp.getState({}); + promise.then(data => { + console.log('getState success:' + JSON.stringify(data)); + }).catch(err => { + console.log('getState fail'); + }); + }) + ``` + + +### setExtraOptions + +setExtraOptions\(options: UDPExtraOptions, callback: AsyncCallback\): void + +设置UDPSocket连接的其他属性。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section7382103811272)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [UDPExtraOptions](#section1650575184117) | 是 | UDPSocket连接的其他属性，参考[UDPExtraOptions](#section1650575184117)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.bind({address:'192.168.xx.xxx', port:xxxx, family:1}, err=> { + if (err) { + console.log('bind fail'); + return; + } + console.log('bind success'); + udp.setExtraOptions({ + receiveBufferSize:1000, + sendBufferSize:1000, + reuseAddress:false, + socketTimeout:6000, + broadcast:true + }, err=> { + if (err) { + console.log('setExtraOptions fail'); + return; + } + console.log('setExtraOptions success'); + }) + }) + ``` + + +### setExtraOptions + +setExtraOptions\(options: UDPExtraOptions\): Promise + +设置UDPSocket连接的其他属性。使用Promise方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section7382103811272)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [UDPExtraOptions](#section1650575184117) | 是 | UDPSocket连接的其他属性，参考[UDPExtraOptions](#section1650575184117)。 | + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :--------------------------------------------------- | + | Promise\ | 以Promise形式返回设置UDPSocket连接的其他属性的结果。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + let promise = udp.bind({address:'192.168.xx.xxx', port:xxxx, family:1}); + promise.then(() => { + console.log('bind success'); + let promise1 = udp.setExtraOptions({ + receiveBufferSize:1000, + sendBufferSize:1000, + reuseAddress:false, + socketTimeout:6000, + broadcast:true + }); + promise1.then(() => { + console.log('setExtraOptions success'); + }).catch(err => { + console.log('setExtraOptions fail'); + }); + }).catch(err => { + console.log('bind fail'); + }); + ``` + + +### on\('message'\) + +on\(type: 'message', callback: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void + +订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | + | type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | + | callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#section46021613174115)}> | 是 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.on('message', value => { + console.log("on message, message:" + value.message) + ", remoteInfo:" + value.remoteInfo); + }); + ``` + + +### off\('message'\) + +off\(type: 'message', callback?: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void + +取消订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | + | type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | + | callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#section46021613174115)}> | 否 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + let callback = value =>{ + console.log("on message, message:" + value.message) + ", remoteInfo:" + value.remoteInfo); + } + udp.on('message', callback); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + udp.off('message', callback); + udp.off('message'); + ``` + + +### on\('listening' | 'close'\) + +on\(type: 'listening' | 'close', callback: Callback\): void + +订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------- | ---- | ------------------------------------------------------------ | + | type | string | 是 | 订阅的事件类型。
- 'listening'：数据包消息事件。
- 'close'：关闭事件。 | + | callback | Callback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + udp.on('listening', () => { + console.log("on listening success")); + }); + udp.on('close', () => { + console.log("on close success" ); + }); + ``` + + +### off\('listening' | 'close'\) + +off\(type: 'listening' | 'close', callback?: Callback\): void + +取消订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------- | ---- | ------------------------------------------------------------ | + | type | string | 是 | 订阅事件类型。
- 'listening'：数据包消息事件。
- 'close'：关闭事件。 | + | callback | Callback\ | 否 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance(); + let callback1 = () =>{ + console.log("on listening, success"); + } + udp.on('listening', callback1); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + udp.off('listening', callback1); + udp.off('listening'); + let callback2 = () =>{ + console.log("on close, success"); + } + udp.on('close', callback2); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + udp.off('close', callback2); + udp.off('close'); + ``` + + +### on\('error'\) + +on\(type: 'error', callback: ErrorCallback\): void + +订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------- | ---- | ------------------------------------ | + | type | string | 是 | 订阅的事件类型。'error'：error事件。 | + | callback | ErrorCallback | 是 | 回调函数。 | + + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance() + udp.on('error', err => { + console.log("on error, err:" + JSON.stringify(err)) + }); + ``` + + +### off\('error'\) + +off\(type: 'error', callback?: ErrorCallback\): void + +取消订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------- | ---- | ------------------------------------ | + | type | string | 是 | 订阅的事件类型。'error'：error事件。 | + | callback | ErrorCallback | 否 | 回调函数。 | + +- 示例 + + ``` + let udp = socket.constructUDPSocketInstance() + let callback = err =>{ + console.log("on error, err:" + JSON.stringify(err)); + } + udp.on('error', callback); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + udp.off('error', callback); + udp.off('error'); + ``` + + +## NetAddress + +目标地址信息。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| address | string | 是 | 本地绑定的ip地址。 | +| port | number | 否 | 端口号 ，范围0~65535。如果不指定系统随机分配端口。 | +| family | number | 否 | 网络协议类型，可选类型：
- 1：IPv4
- 2：IPv6
默认为1。 | + +## UDPSendOptions + +UDPSocket发送参数。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ---------------------------------- | ---- | -------------- | +| data | string | 是 | 发送的数据。 | +| address | [NetAddress](#section159132241295) | 是 | 目标地址信息。 | + +## UDPExtraOptions + +UDPSocket连接的其他属性。 + +| 参数名 | 类型 | 必填 | 说明 | +| ----------------- | ------- | ---- | -------------------------------- | +| broadcast | boolean | 否 | 是否可以发送广播。默认为false。 | +| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 | +| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 | +| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 | +| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 | + +## SocketStateBase + +Socket的状态信息。 + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------- | ---- | ---------- | +| isBound | boolean | 是 | 是否绑定。 | +| isClose | boolean | 是 | 是否关闭。 | +| isConnected | boolean | 是 | 是否连接。 | + +## SocketRemoteInfo + +Socket的连接信息。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| address | string | 是 | 本地绑定的ip地址。 | +| family | string | 是 | 网络协议类型，可选类型：
- IPv4
- IPv6
默认为IPv4。 | +| port | number | 是 | 端口号，范围0~65535。 | +| size | number | 是 | 服务器响应信息的字节长度。 | + +## socket.constructTCPSocketInstance + +constructTCPSocketInstance\(\): TCPSocket + +创建一个TCPSocket对象。 + +- 返回值 + + | 类型 | 说明 | + | :--------------------------------- | :---------------------- | + | [TCPSocket](#section1180211014548) | 返回一个TCPSocket对象。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + ``` + + +## TCPSocket + +TCPSocket连接。在调用TCPSocket的方法前，需要先通过[socket.constructTCPSocketInstance](#section283119484161)创建TCPSocket对象。 + +### bind + +bind\(address: NetAddress, callback: AsyncCallback\): void + +绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方法作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------- | ---- | ------------------------------------------------------ | + | address | [NetAddress](#section159132241295) | 是 | 目标地址信息，参考[NetAddress](#section159132241295)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + tcp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { + if (err) { + console.log('bind fail'); + return; + } + console.log('bind success'); + }) + ``` + + +### bind + +bind\(address NetAddress\): Promise + +绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方法作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ---------------------------------- | ---- | ------------------------------------------------------ | + | address | [NetAddress](#section159132241295) | 是 | 目标地址信息，参考[NetAddress](#section159132241295)。 | + + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :------------------------------------------------------- | + | Promise\ | 以Promise形式返回TCPSocket绑定本机的IP地址和端口的结果。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}); + promise.then(() => { + console.log('bind success'); + }).catch(err => { + console.log('bind fail'); + }); + ``` + + +### connect + +connect\(options: TCPConnectOptions, callback: AsyncCallback\): void + +连接到指定的IP地址和端口。使用callback方法作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [TCPConnectOptions](#section13821005712) | 是 | TCPSocket连接的参数，参考[TCPConnectOptions](#section13821005712)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}, err => { + if (err) { + console.log('connect fail'); + return; + } + console.log('connect success'); + }) + ``` + + +### connect + +connect\(options: TCPConnectOptions\): Promise + +连接到指定的IP地址和端口。使用promise方法作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [TCPConnectOptions](#section13821005712) | 是 | TCPSocket连接的参数，参考[TCPConnectOptions](#section13821005712)。 | + + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :--------------------------------------------------------- | + | Promise\ | 以Promise形式返回TCPSocket连接到指定的IP地址和端口的结果。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise.then(() => { + console.log('connect success') + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### send + +send\(options: TCPSendOptions, callback: AsyncCallback\): void + +通过TCPSocket连接发送数据。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [TCPSendOptions](#section1689232415715) | 是 | TCPSocket发送请求的参数，参考[TCPSendOptions](#section1689232415715)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise.then(() => { + console.log('connect success'); + tcp.send({ + data:'Hello, server!' + },err => { + if (err) { + console.log('send fail'); + return; + } + console.log('send success'); + }) + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### send + +send\(options: TCPSendOptions\): Promise + +通过TCPSocket连接发送数据。使用Promise方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [TCPSendOptions](#section1689232415715) | 是 | TCPSocket发送请求的参数，参考[TCPSendOptions](#section1689232415715)。 | + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :------------------------------------------------- | + | Promise\ | 以Promise形式返回通过TCPSocket连接发送数据的结果。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise1 = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise1.then(() => { + console.log('connect success'); + let promise2 = tcp.send({ + data:'Hello, server!' + }); + promise2.then(() => { + console.log('send success'); + }).catch(err => { + console.log('send fail'); + }); + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### close + +close\(callback: AsyncCallback\): void + +关闭TCPSocket连接。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | --------------------- | ---- | ---------- | + | callback | AsyncCallback\ | 是 | 回调函数。 | + + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + tcp.close(err => { + if (err) { + console.log('close fail'); + return; + } + console.log('close success'); + }) + ``` + + +### close + +close\(\): Promise + +关闭TCPSocket连接。使用Promise方式作为异步方法。 + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :----------------------------------------- | + | Promise\ | 以Promise形式返回关闭TCPSocket连接的结果。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.close(); + promise.then(() => { + console.log('close success'); + }).catch(err => { + console.log('close fail'); + }); + ``` + + +### getRemoteAddress + +getRemoteAddress\(callback: AsyncCallback\): void + +获取对端Socket地址。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------- | ---- | ---------- | + | callback | AsyncCallback<[NetAddress](#section159132241295)> | 是 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise.then(() => { + console.log('connect success'); + tcp.getRemoteAddress((err, data) => { + if (err) { + console.log('getRemoteAddressfail'); + return; + } + console.log('getRemoteAddresssuccess:' + JSON.stringify(data)); + }) + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### getRemoteAddress + +getRemoteAddress\(\): Promise + +获取对端Socket地址。使用Promise方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 返回值 + + | 类型 | 说明 | + | :------------------------------------------ | :------------------------------------------ | + | Promise<[NetAddress](#section159132241295)> | 以Promise形式返回获取对端socket地址的结果。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise1 = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise1.then(() => { + console.log('connect success'); + let promise2 = tcp.getRemoteAddress(); + promise2.then(() => { + console.log('getRemoteAddress success:' + JSON.stringify(data)); + }).catch(err => { + console.log('getRemoteAddressfail'); + }); + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### getState + +getState\(callback: AsyncCallback\): void + +获取TCPSocket状态。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section8465924145710)或[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------ | ---- | ---------- | + | callback | AsyncCallback<[SocketStateBase](#section164609984111)> | 是 | 回调函数。 | + + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise.then(() => { + console.log('connect success'); + tcp.getState((err, data) => { + if (err) { + console.log('getState fail'); + return; + } + console.log('getState success:' + JSON.stringify(data)); + }); + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### getState + +getState\(\): Promise + +获取TCPSocket状态。使用Promise方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section8465924145710)或[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 返回值 + + | 类型 | 说明 | + | :----------------------------------------------- | :----------------------------------------- | + | Promise<[SocketStateBase](#section164609984111)> | 以Promise形式返回获取TCPSocket状态的结果。 | + + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise.then(() => { + console.log('connect success'); + let promise1 = tcp.getState(); + promise1.then(() => { + console.log('getState success:' + JSON.stringify(data)); + }).catch(err => { + console.log('getState fail'); + }); + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### setExtraOptions + +setExtraOptions\(options: TCPExtraOptions, callback: AsyncCallback\): void + +设置TCPSocket连接的其他属性。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section8465924145710)或[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [TCPExtraOptions](#section13892555115718) | 是 | TCPSocket连接的其他属性，参考[TCPExtraOptions](#section13892555115718)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise.then(() => { + console.log('connect success'); + tcp.setExtraOptions({ + keepAlive: true, + OOBInline: true, + TCPNoDelay: true, + socketLinger: { on:true, linger:10 } + receiveBufferSize: 1000, + sendBufferSize: 1000, + reuseAddress: true, + socketTimeout: 3000, + },err => { + if (err) { + console.log('setExtraOptions fail'); + return; + } + console.log('setExtraOptions success'); + }); + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### setExtraOptions + +setExtraOptions\(options: TCPExtraOptions\): Promise + +设置TCPSocket连接的其他属性，使用Promise方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>[bind](#section8465924145710)或[connect](#section82761299586)方法调用成功后，才可调用此方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | + | options | [TCPExtraOptions](#section13892555115718) | 是 | TCPSocket连接的其他属性，参考[TCPExtraOptions](#section13892555115718)。 | + + +- 返回值 + + | 类型 | 说明 | + | :-------------- | :--------------------------------------------------- | + | Promise\ | 以Promise形式返回设置TCPSocket连接的其他属性的结果。 | + + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); + promise.then(() => { + console.log('connect success'); + let promise1 = tcp.setExtraOptions({ + keepAlive: true, + OOBInline: true, + TCPNoDelay: true, + socketLinger: { on:true, linger:10 } + receiveBufferSize: 1000, + sendBufferSize: 1000, + reuseAddress: true, + socketTimeout: 3000, + }); + promise1.then(() => { + console.log('setExtraOptions success'); + }).catch(err => { + console.log('setExtraOptions fail'); + }); + }).catch(err => { + console.log('connect fail'); + }); + ``` + + +### on\('message'\) + +on\(type: 'message', callback: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void + +订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | + | type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | + | callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#section46021613174115)}> | 是 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + tcp.on('message', value => { + console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo) + }); + ``` + + +### off\('message'\) + +off\(type: 'message', callback?: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void + +取消订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | + | type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | + | callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#section46021613174115)}> | 否 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let callback = value =>{ + console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo); + } + tcp.on('message', callback); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + tcp.off('message', callback); + tcp.off('message'); + ``` + + +### on\('connect' | 'close'\) + +on\(type: 'connect' | 'close', callback: Callback\): void + +订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------- | ---- | ------------------------------------------------------------ | + | type | string | 是 | 订阅的事件类型。
- 'connect'：连接事件。
- 'close'：关闭事件。 | + | callback | Callback\ | 是 | 回调函数。 | + + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + tcp.on('connect', () => { + console.log("on connect success") + }); + tcp.on('close', data => { + console.log("on close success") + }); + ``` + + +### off\('connect' | 'close'\) + +off\(type: 'connect' | 'close', callback: Callback\): void + +取消订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------- | ---- | ------------------------------------------------------------ | + | type | string | 是 | 订阅的事件类型。
- 'connect'：连接事件。
- 'close'：关闭事件。 | + | callback | Callback\ | 否 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let callback1 = () =>{ + console.log("on connect success"); + } + tcp.on('connect', callback1); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + tcp.off('connect', callback1); + tcp.off('connect'); + let callback2 = () =>{ + console.log("on close success"); + } + tcp.on('close', callback2); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + tcp.off('close', callback2); + tcp.off('close'); + ``` + + +### on\('error'\) + +on\(type: 'error', callback: ErrorCallback\): void + +订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------- | ---- | ------------------------------------ | + | type | string | 是 | 订阅的事件类型。'error'：error事件。 | + | callback | ErrorCallback | 是 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + tcp.on('error', err => { + console.log("on error, err:" + JSON.stringify(err)) + }); + ``` + + +### off\('error'\) + +off\(type: 'error', callback?: ErrorCallback\): void + +取消订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------- | ---- | ------------------------------------ | + | type | string | 是 | 订阅的事件类型。'error'：error事件。 | + | callback | ErrorCallback | 否 | 回调函数。 | + +- 示例 + + ``` + let tcp = socket.constructTCPSocketInstance(); + let callback = err =>{ + console.log("on error, err:" + JSON.stringify(err)); + } + tcp.on('error', callback); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + tcp.off('error', callback); + tcp.off('error'); + ``` + + +## TCPConnectOptions + +TCPSocket连接的参数。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ---------------------------------- | ---- | -------------------------- | +| address | [NetAddress](#section159132241295) | 是 | 绑定的地址以及端口。 | +| timeout | number | 否 | 超时时间，单位毫秒（ms）。 | + +## TCPSendOptions + +TCPSocket发送请求的参数。 + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| data | string | 是 | 发送的数据。 | +| encoding | string | 否 | 字符编码(UTF-8，UTF-16BE，UTF-16LE，UTF-16，US-AECII，ISO-8859-1)，默认为UTF-8。 | + +## TCPExtraOptions + +TCPSocket连接的其他属性。 + +| 参数名 | 类型 | 必填 | 说明 | +| ----------------- | ------- | ---- | ------------------------------------------------------------ | +| keepAlive | boolean | 否 | 是否保持连接。默认为false。 | +| OOBInline | boolean | 否 | 是否为OOB内联。默认为false。 | +| TCPNoDelay | boolean | 否 | TCPSocket连接是否无时延。默认为false。 | +| socketLinger | Object | 是 | socket是否继续逗留。
- on：是否逗留（true：逗留；false：不逗留）。
- linger：逗留时长，单位毫秒（ms），取值范围为0~65535。
当入参on设置为true时，才需要设置。 | +| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 | +| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 | +| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 | +| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-webSocket.md b/zh-cn/application-dev/reference/apis/js-apis-webSocket.md new file mode 100644 index 0000000000..42a9304b26 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-webSocket.md @@ -0,0 +1,600 @@ +# WebSocket连接 + +- [导入模块](#s56d19203690d4782bfc74069abb6bd71) +- [权限列表](#section11257113618419) +- [完整示例](#section20761171275912) +- [webSocket.createWebSocket](#section375081875219) +- [WebSocket](#section16411174314593) + - [connect](#section1377525513113) + - [connect](#section18952991528) + - [connect](#section10573126422) + - [send](#section156451414213) + - [send](#section137609541324) + - [close](#section202411451433) + - [close](#section10491513437) + - [close](#section118451219536) + - [on\('open'\)](#section923017271834) + - [off\('open'\)](#section207051331730) + - [on\('message'\)](#section1066819418488) + - [off\('message'\)](#section1467019413484) + - [on\('close'\)](#section169378107484) + - [off\('close'\)](#section993911074812) + - [on\('error'\)](#section2997161484815) + - [off\('error'\)](#section13999114164815) + +- [WebSocketRequestOptions](#section11251233123910) +- [WebSocketCloseOptions](#section12262183471518) +- [close错误码说明](#section1635681416477) + +>![](public_sys-resources/icon-note.gif) **说明：** +>本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +使用WebSocket建立服务器与客户端的双向连接，需要先通过[createWebSocket](#section375081875219)方法创建[WebSocket](#section16411174314593)对象，然后通过[connect](WebSocket连接.md)方法连接到服务器。当连接成功后，客户端会收到[open](#section923017271834)事件的回调，之后客户端就可以通过[send](#section156451414213)方法与服务器进行通信。当服务器发信息给客户端时，客户端会收到[message](#section1066819418488)事件的回调。当客户端不要此连接时，可以通过调用[close](#section202411451433)方法主动断开连接，之后客户端会收到[close](#section169378107484)事件的回调。 + +若在上述任一过程中发生错误，客户端会收到[error](#section2997161484815)事件的回调。 + + +## 导入模块 + +``` +import webSocket from '@ohos.net.webSocket'; +``` + +## 权限列表 + +需要ohos.permission.INTERNET权限。 + +## 完整示例 + +``` +import webSocket from '@ohos.net.webSocket'; + +var defaultIpAddress = "ws://"; +let ws = webSocket.createWebSocket(); +ws.on('open', (err, value) => { + console.log("on open, status:" + value.status + ", message:" + value.message); + // 当收到on('open')事件时，可以通过send()方法与服务器进行通信 + ws.send("Hello, server!", (err, value) => { + if (!err) { + console.log("send success"); + } else { + console.log("send fail, err:" + JSON.stringify(err)); + } + }); +}); +ws.on('message', (err, value) => { + console.log("on message, message:" + value); + // 当收到服务器的`bye`消息时（此消息字段仅为示意，具体字段需要与服务器协商），主动断开连接 + if (value === 'bye') { + ws.close((err, value) => { + if (!err) { + console.log("close success"); + } else { + console.log("close fail, err is " + JSON.stringify(err)); + } + }); + } +}); +ws.on('close', (err, value) => { + console.log("on close, code is " + value.code + ", reason is " + value.reason); +}); +ws.on('error', (err) => { + console.log("on error, error:" + JSON.stringify(err)); +}); +ws.connect(defaultIpAddress, (err, value) => { + if (!err) { + console.log("connect success"); + } else { + console.log("connect fail, err:" + JSON.stringify(err)); + } +}); +``` + +## webSocket.createWebSocket + +createWebSocket\(\): WebSocket + +创建一个WebSocket，里面包括建立连接、关闭连接、发送数据和订阅/取消订阅WebSocket连接的打开事件、接收到服务器消息事件、关闭事件和错误事件。 + +- 返回值 + + | 类型 | 说明 | + | :---------------------------------- | :----------------------------------------------------------- | + | [WebSocket](#section16411174314593) | 返回一个WebSocket对象，里面包括connect、send、close、on和off方法。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ``` + + +## WebSocket + +在调用WebSocket的方法前，需要先通过[webSocket.createWebSocket](#section375081875219)创建一个WebSocket。 + +### connect + +connect\(url: string, callback: AsyncCallback\): void + +根据URL地址，建立一个WebSocket连接，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------ | ---- | ---------------------------- | + | url | string | 是 | 建立WebSocket连接的URL地址。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + ws.connect(url, (err, value) => { + if (!err) { + console.log("connect success"); + } else { + console.log("connect fail, err:" + JSON.stringify(err)) + } + }); + ``` + + +### connect + +connect\(url: string, options: WebSocketRequestOptions, callback: AsyncCallback\): void + +根据URL地址和header，建立一个WebSocket连接，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------ | ---- | ------------------------------------------------------- | + | url | string | 是 | 建立WebSocket连接的URL地址。 | + | options | WebSocketRequestOptions | 是 | 参考[WebSocketRequestOptions](#section11251233123910)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + ws.connect(url, { + header: { + "key": "value", + "key2": "value2" + } + }, (err, value) => { + if (!err) { + console.log("connect success"); + } else { + console.log("connect fail, err:" + JSON.stringify(err)) + } + }); + ``` + + +### connect + +connect\(url: string, options?: WebSocketRequestOptions\): Promise + +根据URL地址和header，建立一个WebSocket连接，使用Promise方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------------------- | ---- | ------------------------------------------------------- | + | url | string | 是 | 建立WebSocket连接的URL地址。 | + | options | WebSocketRequestOptions | 否 | 参考[WebSocketRequestOptions](#section11251233123910)。 | + +- 返回值 + + | 类型 | 说明 | + | :----------------- | :-------------------------------- | + | Promise\ | 以Promise形式返回建立连接的结果。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + let promise = ws.connect(url); + promise.then((value) => { + console.log("connect success") + }).catch((err) => { + console.log("connect fail, error:" + JSON.stringify(err)) + }); + ``` + + +### send + +send\(data: string | ArrayBuffer, callback: AsyncCallback\): void + +通过WebSocket连接发送数据，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------ | ---- | ------------ | + | data | string \| ArrayBuffer 8+ | 是 | 发送的数据。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + ws.connect(url, (err, value) => { + ws.send("Hello, server!", (err, value) => { + if (!err) { + console.log("send success"); + } else { + console.log("send fail, err:" + JSON.stringify(err)) + } + }); + }); + ``` + + +### send + +send\(data: string | ArrayBuffer\): Promise + +通过WebSocket连接发送数据，使用Promise方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------ | + | data | string \| ArrayBuffer 8+ | 是 | 发送的数据。 | + +- 返回值 + + | 类型 | 说明 | + | :----------------- | :-------------------------------- | + | Promise\ | 以Promise形式返回发送数据的结果。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + ws.connect(url, (err, value) => { + let promise = ws.send("Hello, server!"); + promise.then((value) => { + console.log("send success") + }).catch((err) => { + console.log("send fail, error:" + JSON.stringify(err)) + }); + }); + ``` + + +### close + +close\(callback: AsyncCallback\): void + +关闭WebSocket连接，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------ | ---- | ---------- | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + ws.close((err, value) => { + if (!err) { + console.log("close success") + } else { + console.log("close fail, err is " + JSON.stringify(err)) + } + }); + ``` + + +### close + +close\(options: WebSocketCloseOptions, callback: AsyncCallback\): void + +根据可选参数code和reason，关闭WebSocket连接，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------ | ---- | ----------------------------------------------------- | + | options | WebSocketCloseOptions | 是 | 参考[WebSocketCloseOptions](#section12262183471518)。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + ws.close({ + code: 1000, + reason: "your reason" + }, (err, value) => { + if (!err) { + console.log("close success") + } else { + console.log("close fail, err is " + JSON.stringify(err)) + } + }); + ``` + + +### close + +close\(options?: WebSocketCloseOptions\): Promise + +根据可选参数code和reason，关闭WebSocket连接，使用Promise方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | --------------------- | ---- | ----------------------------------------------------- | + | options | WebSocketCloseOptions | 否 | 参考[WebSocketCloseOptions](#section12262183471518)。 | + +- 返回值 + + | 类型 | 说明 | + | :--------------- | :-------------------------------- | + | Promise | 以Promise形式返回关闭连接的结果。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let url = "ws://" + let promise = ws.close({ + code: 1000, + reason: "your reason" + }); + promise.then((value) => { + console.log("close success") + }).catch((err) => { + console.log("close fail, err is " + JSON.stringify(err)) + }); + ``` + + +### on\('open'\) + +on\(type: 'open', callback: AsyncCallback\): void + +订阅WebSocket的打开事件，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------- | ---- | ----------------------------- | + | type | string | 是 | 'open'：WebSocket的打开事件。 | + | callback | AsyncCallback\ | 是 | 回调函数。 | + + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ws.on('open', (err, value) => { + console.log("on open, status:" + value.status + ", message:" + value.message); + }); + ``` + + +### off\('open'\) + +off\(type: 'open', callback?: AsyncCallback\): void + +取消订阅WebSocket的打开事件，使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------- | ---- | ----------------------------- | + | type | string | 是 | 'open'：WebSocket的打开事件。 | + | callback | AsyncCallback\ | 否 | 回调函数。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + let callback1 = (err, value) => { + console.log("on open, status:" + value.status + ", message:" + value.message); + } + ws.on('open', callback1); + // 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅 + ws.off('open', callback1); + ``` + + +### on\('message'\) + +on\(type: 'message', callback: AsyncCallback\): void + +订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>AsyncCallback中的数据可以是字符串\(API 6\)或ArrayBuffer\(API 8\)。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------- | ---- | -------------------------------------------- | + | type | string | 是 | 'message'：WebSocket的接收到服务器消息事件。 | + | callback | AsyncCallback\8+\> | 是 | 回调函数。 | + + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ws.on('message', (err, value) => { + console.log("on message, message:" + value); + }); + ``` + + +### off\('message'\) + +off\(type: 'message', callback?: AsyncCallback\): void + +取消订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>AsyncCallback中的数据可以是字符串\(API 6\)或ArrayBuffer\(API 8\)。 +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | --------------------------------------------------- | ---- | -------------------------------------------- | + | type | string | 是 | 'message'：WebSocket的接收到服务器消息事件。 | + | callback | AsyncCallback\8+\> | 否 | 回调函数。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ws.off('message'); + ``` + + +### on\('close'\) + +on\(type: 'close', callback: AsyncCallback<\{ code: number, reason: string \}\>\): void + +订阅WebSocket的关闭事件，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------------------------------- | ---- | ------------------------------ | + | type | string | 是 | 'close'：WebSocket的关闭事件。 | + | callback | AsyncCallback<{ code: number, reason: string }> | 是 | 回调函数。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ws.on('close', (err, value) => { + console.log("on close, code is " + value.code + ", reason is " + value.reason); + }); + ``` + + +### off\('close'\) + +off\(type: 'close', callback?: AsyncCallback<\{ code: number, reason: string \}\>\): void + +取消订阅WebSocket的关闭事件，使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ----------------------------------------------- | ---- | ------------------------------ | + | type | string | 是 | 'close'：WebSocket的关闭事件。 | + | callback | AsyncCallback<{ code: number, reason: string }> | 否 | 回调函数。 | + + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ws.off('close'); + ``` + + +### on\('error'\) + +on\(type: 'error', callback: ErrorCallback\): void + +订阅WebSocket的Error事件，使用callback方式作为异步方法。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------- | ---- | ------------------------------- | + | type | string | 是 | 'error'：WebSocket的Error事件。 | + | callback | ErrorCallback | 是 | 回调函数。 | + + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ws.on('error', (err) => { + console.log("on error, error:" + JSON.stringify(err)) + }); + ``` + + +### off\('error'\) + +off\(type: 'error', callback?: ErrorCallback\): void + +取消订阅WebSocket的Error事件，使用callback方式作为异步方法。 + +>![](public_sys-resources/icon-note.gif) **说明：** +>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 + +- 参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------- | ---- | ------------------------------- | + | type | string | 是 | 'error'：WebSocket的Error事件。 | + | callback | ErrorCallback | 否 | 回调函数。 | + +- 示例 + + ``` + let ws = webSocket.createWebSocket(); + ws.off('error'); + ``` + + +## WebSocketRequestOptions + +建立WebSocket连接时，可选参数的类型和说明。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| header | Object | 否 | 建立WebSocket连接可选参数，代表建立连接时携带的HTTP头信息。参数内容自定义，也可以不指定。 | + + +## WebSocketCloseOptions + +关闭WebSocket连接时，可选参数的类型和说明。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| code | number | 否 | 错误码，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为1000。 | +| reason | string | 否 | 原因值，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为空字符串（""）。 | + +## close错误码说明 + +发送给服务端的错误码可以自行定义，下面的列表仅供参考。 + +| 值 | 说明 | +| :-------- | :----------------- | +| 1000 | 正常关闭 | +| 1001 | 服务器主动关闭 | +| 1002 | 协议错误 | +| 1003 | 无法处理的数据类型 | +| 1004~1015 | 保留值 | + -- GitLab