harmony 鸿蒙# @ohos.net.webSocket (WebSocket Connection)

2022-08-09 浏览 (785)

# @ohos.net.webSocket (WebSocket Connection)

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

You can use WebSocket to establish a bidirectional connection between a server and a client. Before doing this, you need to use the createWebSocket API to create a WebSocket object and then use the connect API to connect to the server. If the connection is successful, the client will receive a callback of the open event. Then, the client can communicate with the server using the send API. When the server sends a message to the client, the client will receive a callback of the message event. If the client no longer needs this connection, it can call the close API to disconnect from the server. Then, the client will receive a callback of the close event.

If an error occurs in any of the preceding processes, the client will receive a callback of the error event.

Modules to Import

import webSocket from '@ohos.net.webSocket';

Examples

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let defaultIpAddress = "ws://";
let ws = webSocket.createWebSocket();
ws.on('open', (err:BusinessError, value: Object) => {
  if (err != undefined) {
    console.log(JSON.stringify(err))
    return
  }
  // When receiving the on('open') event, the client can use the send() API to communicate with the server.
  ws.send("Hello, server!", (err: BusinessError, value: boolean) => {
    if (!err) {
      console.log("send success");
    } else {
      console.log("send fail, err:" + JSON.stringify(err));
    }
  });
});
ws.on('message', (err: BusinessError, value: string) => {
  console.log("on message, message:" + value);
  // When receiving the `bye` message (the actual message name may differ) from the server, the client proactively disconnects from the server.
  if (value === 'bye') {
    ws.close((err: BusinessError, value: boolean) => {
      if (!err) {
        console.log("close success");
      } else {
        console.log("close fail, err is " + JSON.stringify(err));
      }
    });
  }
});
ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => {
  console.log("on close, code is " + value.code + ", reason is " + value.reason);
});
ws.on('error', (err: BusinessError) => {
  console.log("on error, error:" + JSON.stringify(err));
});
ws.connect(defaultIpAddress, (err: BusinessError, value: boolean) => {
  if (!err) {
    console.log("connect success");
  } else {
    console.log("connect fail, err:" + JSON.stringify(err));
  }
});

webSocket.createWebSocket6+

createWebSocket(): WebSocket

Creates a WebSocket connection. You can use this API to create or close a WebSocket connection, send data over it, or enable or disable listening for the open, close, message, and error events.

System capability: SystemCapability.Communication.NetStack

Return value

TypeDescription
WebSocketA WebSocket object, which contains the connect, send, close, on, or off method.

Example

let ws: webSocket = webSocket.createWebSocket();

WebSocket6+

Defines a WebSocket object. Before invoking WebSocket APIs, you need to call webSocket.createWebSocket to create a WebSocket object.

connect6+

connect(url: string, callback: AsyncCallback<boolean>): void

Initiates a WebSocket request to establish a WebSocket connection to a given URL. This API uses an asynchronous callback to return the result.

NOTE You can listen to error events to obtain the operation result. If an error occurs, the error code 200 will be returned.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
urlstringYesURL for establishing a WebSocket connection.
callbackAsyncCallback<boolean>YesCallback used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err: BusinessError, value: boolean) => {
  if (!err) {
    console.log("connect success");
  } else {
    console.log("connect fail, err:" + JSON.stringify(err))
  }
});

connect6+

connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback<boolean>): void

Initiates a WebSocket request carrying specified options to establish a WebSocket connection to a given URL. This API uses an asynchronous callback to return the result.

NOTE You can listen to error events to obtain the operation result. If an error occurs, the error code 200 will be returned.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
urlstringYesURL for establishing a WebSocket connection.
optionsWebSocketRequestOptionsYesRequest options. For details, see WebSocketRequestOptions.
callbackAsyncCallback<boolean>YesCallback used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
let header: Map<string, string>
header.set("key", "value")
header.set("key2", "value2")
let url = "ws://"
ws.connect(url, header as webSocket.WebSocketRequestOptions, (err: BusinessError, value: Object) => {
  if (!err) {
    console.log("connect success");
  } else {
    console.log("connect fail, err:" + JSON.stringify(err))
  }
});

connect6+

connect(url: string, options?: WebSocketRequestOptions): Promise<boolean>

Initiates a WebSocket request carrying specified options to establish a WebSocket connection to a given URL. This API uses a promise to return the result.

NOTE You can listen to error events to obtain the operation result. If an error occurs, the error code 200 will be returned.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
urlstringYesURL for establishing a WebSocket connection.
optionsWebSocketRequestOptionsNoRequest options. For details, see WebSocketRequestOptions.

Return value

TypeDescription
Promise<boolean>Promise used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';

let ws = webSocket.createWebSocket();
let url = "ws://"
let promise = ws.connect(url);
promise.then((value: boolean) => {
  console.log("connect success")
}).catch((err:string) => {
  console.log("connect fail, error:" + JSON.stringify(err))
});

send6+

send(data: string|ArrayBuffer, callback: AsyncCallback<boolean>): void

Sends data through a WebSocket connection. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
datastring |ArrayBufferYesData to send.
Only the string type is supported for API version 6 or earlier. Both the string and ArrayBuffer types are supported for API version 8 or later.
callbackAsyncCallback<boolean>YesCallback used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err: BusinessError, value: boolean) => {
  ws.send("Hello, server!", (err: BusinessError, value: boolean) => {
    if (!err) {
      console.log("send success");
    } else {
      console.log("send fail, err:" + JSON.stringify(err))
    }
  });
});

send6+

send(data: string|ArrayBuffer): Promise<boolean>

Sends data through a WebSocket connection. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
datastring |ArrayBufferYesData to send.
Only the string type is supported for API version 6 or earlier. Both the string and ArrayBuffer types are supported for API version 8 or later.

Return value

TypeDescription
Promise<boolean>Promise used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err: BusinessError, value: boolean) => {
  let promise = ws.send("Hello, server!");
  promise.then((value: boolean) => {
    console.log("send success")
  }).catch((err:string) => {
    console.log("send fail, error:" + JSON.stringify(err))
  });
});

close6+

close(callback: AsyncCallback<boolean>): void

Closes a WebSocket connection. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<boolean>YesCallback used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
ws.close((err: BusinessError) => {
  if (!err) {
    console.log("close success")
  } else {
    console.log("close fail, err is " + JSON.stringify(err))
  }
});

close6+

close(options: WebSocketCloseOptions, callback: AsyncCallback<boolean>): void

Closes a WebSocket connection carrying specified options such as code and reason. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
optionsWebSocketCloseOptionsYesRequest options. For details, see WebSocketCloseOptions.
callbackAsyncCallback<boolean>YesCallback used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();

let options: webSocket.WebSocketCloseOptions
options.code = 1000
options.reason = "your reason"
ws.close(options, (err: BusinessError) => {
  if (!err) {
    console.log("close success")
  } else {
    console.log("close fail, err is " + JSON.stringify(err))
  }
});

close6+

close(options?: WebSocketCloseOptions): Promise<boolean>

Closes a WebSocket connection carrying specified options such as code and reason. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
optionsWebSocketCloseOptionsNoRequest options. For details, see WebSocketCloseOptions.

Return value

TypeDescription
Promise<boolean>Promise used to return the result.

Error codes

IDError Message
401Parameter error.
201Permission denied.

Example

import webSocket from '@ohos.net.webSocket';

let ws = webSocket.createWebSocket();
let options: webSocket.WebSocketCloseOptions
options.code = 1000
options.reason = "your reason"
let promise = ws.close();
promise.then((value: boolean) => {
  console.log("close success")
}).catch((err:string) => {
  console.log("close fail, err is " + JSON.stringify(err))
});

on('open')6+

on(type: 'open', callback: AsyncCallback<Object>): void

Enables listening for the open events of a WebSocket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
open: event indicating that a WebSocket connection has been opened.
callbackAsyncCallback<Object>YesCallback used to return the result.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError, Callback } from '@ohos.base';

let ws= webSocket.createWebSocket();
class OutValue {
  status: number = 0
  message: string = ""
}
ws.on('open', (err: BusinessError, value: OutValue) => {
  console.log("on open, status:" + value.status + ", message:" + value.message);
});

off('open')6+

off(type: 'open', callback?: AsyncCallback<Object>): void

Disables listening for the open events of a WebSocket connection. This API uses an asynchronous callback to return the result.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
open: event indicating that a WebSocket connection has been opened.
callbackAsyncCallback<Object>NoCallback used to return the result.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
class OutValue {
  status: number = 0
  message: string = ""
}
let callback1 = (err: BusinessError, value: OutValue) => {
  console.log("on open, status:" + value.status + ", message:" + value.message);
}
ws.on('open', callback1);
// You can pass the callback of the on function to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
ws.off('open', callback1);

on('message')6+

on(type: 'message', callback: AsyncCallback<string|ArrayBuffer>): void

Enables listening for the message events of a WebSocket connection. This API uses an asynchronous callback to return the result. The maximum length of each message is 4 KB. If the length exceeds 4 KB, the message is automatically fragmented.

NOTE The data in AsyncCallback can be in the format of string (API version 6) or ArrayBuffer (API version 8).

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
message: event indicating that a message has been received from the server.
callbackAsyncCallback<string |ArrayBuffer 8+>YesCallback used to return the result.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
ws.on('message', (err: BusinessError, value: string) => {
  console.log("on message, message:" + value);
});

off('message')6+

off(type: 'message', callback?: AsyncCallback<string|ArrayBuffer>): void

Disables listening for the message events of a WebSocket connection. This API uses an asynchronous callback to return the result. The maximum length of each message is 4 KB. If the length exceeds 4 KB, the message is automatically fragmented.

NOTE The data in AsyncCallback can be in the format of string (API version 6) or ArrayBuffer (API version 8). You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
message: event indicating that a message has been received from the server.
callbackAsyncCallback<string |ArrayBuffer 8+>NoCallback used to return the result.

Example

import webSocket from '@ohos.net.webSocket';

let ws = webSocket.createWebSocket();
ws.off('message');

on('close')6+

on(type: 'close', callback: AsyncCallback<CloseResult>): void

Enables listening for the close events of a WebSocket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
close: event indicating that a WebSocket connection has been closed.
callbackAsyncCallback<CloseResult>YesCallback used to return the result.
close and reason indicate the error code and error cause for closing the connection, respectively.

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => {
  console.log("on close, code is " + value.code + ", reason is " + value.reason);
});

off('close')6+

off(type: 'close', callback?: AsyncCallback<CloseResult>): void

Disables listening for the close events of a WebSocket connection. This API uses an asynchronous callback to return the result.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
close: event indicating that a WebSocket connection has been closed.
callbackAsyncCallback<CloseResult>NoCallback used to return the result.
close and reason indicate the error code and error cause for closing the connection, respectively.

Example

import webSocket from '@ohos.net.webSocket';

let ws = webSocket.createWebSocket();
ws.off('close');

on('error')6+

on(type: 'error', callback: ErrorCallback): void

Enables listening for the error events of a WebSocket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
error: event indicating the WebSocket connection has encountered an error.
callbackErrorCallbackYesCallback used to return the result.
Common error code: 200

Example

import webSocket from '@ohos.net.webSocket';
import { BusinessError } from '@ohos.base';

let ws = webSocket.createWebSocket();
ws.on('error', (err: BusinessError) => {
  console.log("on error, error:" + JSON.stringify(err))
});

off('error')6+

off(type: 'error', callback?: ErrorCallback): void

Disables listening for the error events of a WebSocket connection. This API uses an asynchronous callback to return the result.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

NameTypeMandatoryDescription
typestringYesEvent type.
error: event indicating the WebSocket connection has encountered an error.
callbackErrorCallbackNoCallback used to return the result.

Example

import webSocket from '@ohos.net.webSocket';
let ws = webSocket.createWebSocket();
ws.off('error');

WebSocketRequestOptions

Defines the optional parameters carried in the request for establishing a WebSocket connection.

System capability: SystemCapability.Communication.NetStack

NameTypeMandatoryDescription
headerObjectNoHeader carrying optional parameters in the request for establishing a WebSocket connection. You can customize the parameter or leave it unspecified.

WebSocketCloseOptions

Defines the optional parameters carried in the request for closing a WebSocket connection.

System capability: SystemCapability.Communication.NetStack

NameTypeMandatoryDescription
codenumberNoError code. Set this parameter based on the actual situation. The default value is 1000.
reasonstringNoError cause. Set this parameter based on the actual situation. The default value is an empty string ("").

CloseResult10+

Represents the result obtained from the close event reported when the WebSocket connection is closed.

System capability: SystemCapability.Communication.NetStack

NameTypeMandatoryDescription
codenumberYesError code for closing the connection.
reasonstringYesError cause for closing the connection.

Result Codes for Closing a WebSocket Connection

You can customize the result codes sent to the server. The result codes in the following table are for reference only.

System capability: SystemCapability.Communication.NetStack

ValueDescription
1000Normally closed.
1001Connection closed by the server.
1002Incorrect protocol.
1003Data unable to be processed.
1004~1015Reserved.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/2881ed3e1f1646a8be7c6a25fa7bdc56