WebSocket连接
说明: 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
使用WebSocket建立服务器与客户端的双向连接,需要先通过[createWebSocket]方法创建[WebSocket]对象,然后通过[connect]方法连接到服务器。当连接成功后,客户端会收到[open]事件的回调,之后客户端就可以通过[send]方法与服务器进行通信。当服务器发信息给客户端时,客户端会收到[message]事件的回调。当客户端不要此连接时,可以通过调用[close]方法主动断开连接,之后客户端会收到[close]事件的回调。
若在上述任一过程中发生错误,客户端会收到[error]事件的回调。
导入模块
import webSocket from '@ohos.net.webSocket';
完整示例
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连接的打开事件、接收到服务器消息事件、关闭事件和错误事件。
系统能力:SystemCapability.Communication.NetStack
返回值:
类型 | 说明 |
---|---|
[WebSocket] | 返回一个WebSocket对象,里面包括connect、send、close、on和off方法。 |
示例:
let ws = webSocket.createWebSocket();
WebSocket
在调用WebSocket的方法前,需要先通过[webSocket.createWebSocket]创建一个WebSocket。
connect
connect(url: string, callback: AsyncCallback): void
根据URL地址,建立一个WebSocket连接,使用callback方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
url | string | 是 | 建立WebSocket连接的URL地址。 |
options | WebSocketRequestOptions | 是 | 参考[WebSocketRequestOptions]。 |
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方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
url | string | 是 | 建立WebSocket连接的URL地址。 |
options | WebSocketRequestOptions | 否 | 参考[WebSocketRequestOptions]。 |
返回值:
类型 | 说明 |
---|---|
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方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | WebSocketCloseOptions | 是 | 参考[WebSocketCloseOptions]。 |
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方式作为异步方法。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | WebSocketCloseOptions | 否 | 参考[WebSocketCloseOptions]。 |
返回值:
类型 | 说明 |
---|---|
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方式作为异步方法。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
说明: 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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<string | ArrayBuffer>): void
订阅WebSocket的接收到服务器消息事件,使用callback方式作为异步方法。
说明: AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
type | string | 是 | ‘message’:WebSocket的接收到服务器消息事件。 |
callback | AsyncCallback<string | ArrayBuffer 8+> | 是 |
示例:
let ws = webSocket.createWebSocket();
ws.on('message', (err, value) => {console.log("on message, message:" + value);
});
off(‘message’)
off(type: ‘message’, callback?: AsyncCallback<string | ArrayBuffer>): void
取消订阅WebSocket的接收到服务器消息事件,使用callback方式作为异步方法。
说明: AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
type | string | 是 | ‘message’:WebSocket的接收到服务器消息事件。 |
callback | AsyncCallback<string | ArrayBuffer 8+> | 否 |
示例:
let ws = webSocket.createWebSocket();
ws.off('message');
on(‘close’)
on(type: ‘close’, callback: AsyncCallback<{ code: number, reason: string }>): void
订阅WebSocket的关闭事件,使用callback方式作为异步方法。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
说明: 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
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方式作为异步方法。
说明: 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
系统能力:SystemCapability.Communication.NetStack
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
type | string | 是 | ‘error’:WebSocket的Error事件。 |
callback | ErrorCallback | 否 | 回调函数。 |
示例:
let ws = webSocket.createWebSocket();
ws.off('error');
WebSocketRequestOptions
建立WebSocket连接时,可选参数的类型和说明。
系统能力:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
header | Object | 否 | 建立WebSocket连接可选参数,代表建立连接时携带的HTTP头信息。参数内容自定义,也可以不指定。 |
WebSocketCloseOptions
关闭WebSocket连接时,可选参数的类型和说明。
系统能力:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
code | number | 否 | 错误码,关闭WebSocket连接时的可选参数,可根据实际情况来填。默认值为1000。 |
reason | string | 否 | 原因值,关闭WebSocket连接时的可选参数,可根据实际情况来填。默认值为空字符串(“”)。 |
close错误码说明
发送给服务端的错误码可以自行定义,下面的列表仅供参考。
系统能力:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。
值 | 说明 |
---|---|
1000 | 正常关闭 |
1001 | 服务器主动关闭 |
1002 | 协议错误 |
1003 | 无法处理的数据类型 |
1004~1015 | 保留值 |