1# @ohos.net.webSocket (WebSocket连接) 2 3<!--Kit: Network Kit--> 4<!--Subsystem: Communication--> 5<!--Owner: @wmyao_mm--> 6<!--Designer: @guo-min_net--> 7<!--Tester: @tongxilin--> 8<!--Adviser: @zhang_yixin13--> 9 10> **说明：** 11> 12> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13 14给第三方应用提供webSocket客户端和服务端服务器，实现客户端与服务端的双向连接，目前服务端仅支持智慧屏使用。 15 16客户端：使用WebSocket建立服务器与客户端的双向连接，需要先通过[createWebSocket](#websocketcreatewebsocket6)方法创建[WebSocket](#websocket6)对象，然后通过[connect](#connect6)方法连接到服务器。当连接成功后，客户端会收到[open](#onopen6)事件的回调，之后客户端就可以通过[send](#send6)方法与服务器进行通信。当服务器发信息给客户端时，客户端会收到[message](#onmessage6)事件的回调。当客户端想要取消此连接时，通过调用[close](#close6)方法主动断开连接后，客户端会收到[close](#onclose6)事件的回调。若在上述任一过程中发生错误，客户端会收到[error](#onerror6)事件的回调。 17 18服务端：（目前服务端仅支持智慧屏使用）使用WebSocket建立服务器与客户端的双向连接，需要先通过[createWebSocketServer](#websocketcreatewebsocketserver19)方法创建[WebSocketServer](#websocketserver19)对象，然后通过[start](#start19)方法启动服务器，监听客户端的申请建链的消息。当连接成功后，服务端会收到[connect](#onconnect19)事件的回调，之后服务端可以通过[send](#send19)方法与客户端进行通信，或者通过[listAllConnections](#listallconnections19)方法列举出当前与服务端建链的所有客户端信息。当客户端给服务端发消息时，服务端会收到[messageReceive](#onmessagereceive19)事件回调。当服务端想断开与某个客户端的连接时，可以通过调用[close](#close19)方法主动断开与某个客户端的连接，之后服务端会收到[close](#onclose19)事件的回调。当服务端想停止service时，可以调用[stop](#stop19)方法。若在上述任一过程中发生错误，服务端会收到[error](#onerror19)事件的回调。 19 20## 导入模块 21 22```ts 23import { webSocket } from '@kit.NetworkKit'; 24``` 25 26## webSocket.createWebSocket<sup>6+</sup> 27 28createWebSocket(): WebSocket 29 30创建一个WebSocket对象，里面包括建立连接、关闭连接、发送数据和订阅/取消订阅WebSocket连接的打开事件、接收到服务器消息事件、关闭事件和错误事件。 31 32**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 33 34**系统能力**：SystemCapability.Communication.NetStack 35 36**返回值：** 37 38| 类型 | 说明 | 39| :---------------------------------- | :----------------------------------------------------------- | 40| [WebSocket](#websocket6) | 返回一个WebSocket对象，里面包括connect、send、close、on和off方法。 | 41 42**示例：** 43 44```ts 45let ws: webSocket.WebSocket = webSocket.createWebSocket(); 46``` 47 48## WebSocket<sup>6+</sup> 49 50在调用WebSocket的方法前，需要先通过[webSocket.createWebSocket](#websocketcreatewebsocket6)创建一个WebSocket。 51 52### connect<sup>6+</sup> 53 54connect(url: string, callback: AsyncCallback\<boolean\>): void 55 56根据URL地址，建立一个WebSocket连接，使用callback方式作为异步方法。 57 58> **说明：** 59> 60> 可通过监听error事件获得该接口的执行结果。 61 62**需要权限**：ohos.permission.INTERNET 63 64**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 65 66**系统能力**：SystemCapability.Communication.NetStack 67 68**注意：** URL地址长度不能超过1024个字符，否则会连接失败。从API15开始，URL地址长度限制由1024修改为2048。 69 70**参数：** 71 72| 参数名 | 类型 | 必填 | 说明 | 73| -------- | ------------------------ | ---- | ---------------------------- | 74| url | string | 是 | 建立WebSocket连接的URL地址。 | 75| callback | AsyncCallback\<boolean\> | 是 | 回调函数。true:连接请求创建成功；false:连接请求创建失败。 | 76 77**错误码：** 78 79以下错误码的详细介绍参见[webSocket错误码](errorcode-net-webSocket.md)和[通用错误码](../errorcode-universal.md)。 80 81| 错误码ID | 错误信息 | 82| --------------------- | ------------------------------------------ | 83| 401 | Parameter error. | 84| 201 | Permission denied. | 85| 2302001 | Websocket url error. | 86| 2302002 | Websocket certificate file does not exist. | 87| 2302003 | Websocket connection already exists. | 88| 2302998 | It is not allowed to access this domain. | 89| 2302999 | Internal error. | 90 91 92**示例：** 93 94```ts 95import { webSocket } from '@kit.NetworkKit'; 96import { BusinessError } from '@kit.BasicServicesKit'; 97 98let ws = webSocket.createWebSocket(); 99let url = "ws://"; 100ws.connect(url, (err: BusinessError, value: boolean) => { 101 if (!err) { 102 console.info("connect success") 103 } else { 104 console.error(`connect fail. Code: ${err.code}, message: ${err.message}`) 105 } 106}); 107``` 108 109### connect<sup>6+</sup> 110 111connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback\<boolean\>): void 112 113根据URL地址，建立一个WebSocket连接，使用callback方式作为异步方法。 114 115> **说明：** 116> 117> 可通过监听error事件获得该接口的执行结果，错误发生时会得到错误码：200。 118 119**需要权限**：ohos.permission.INTERNET 120 121**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 122 123**系统能力**：SystemCapability.Communication.NetStack 124 125**注意：** URL地址长度不能超过1024个字符，否则会连接失败。 126 127**参数：** 128 129| 参数名 | 类型 | 必填 | 说明 | 130| -------- | ------------------------ | ---- | ------------------------------------------------------- | 131| url | string | 是 | 建立WebSocket连接的URL地址。 | 132| options | WebSocketRequestOptions | 是 | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 | 133| callback | AsyncCallback\<boolean\> | 是 | 回调函数。true:连接请求创建成功；false:连接请求创建失败。 | 134 135**错误码：** 136 137以下错误码的详细介绍参见[webSocket错误码](errorcode-net-webSocket.md)和[通用错误码](../errorcode-universal.md)。 138 139| 错误码ID | 错误信息 | 140| --------------------- | ------------------------------------------ | 141| 401 | Parameter error. | 142| 201 | Permission denied. | 143| 2302001 | Websocket url error. | 144| 2302002 | Websocket certificate file does not exist. | 145| 2302003 | Websocket connection already exists. | 146| 2302998 | It is not allowed to access this domain. | 147| 2302999 | Internal error. | 148 149**示例：** 150 151```ts 152import { webSocket } from '@kit.NetworkKit'; 153import { BusinessError } from '@kit.BasicServicesKit'; 154 155let ws = webSocket.createWebSocket(); 156let options: webSocket.WebSocketRequestOptions | undefined; 157if (options !=undefined) { 158 options.header = { 159 name1: "value1", 160 name2: "value2", 161 name3: "value3" 162 }; 163 options.caPath = ""; 164} 165let url = "ws://" 166ws.connect(url, options, (err: BusinessError, value: Object) => { 167 if (!err) { 168 console.info("connect success") 169 } else { 170 console.error(`connect fail. Code: ${err.code}, message: ${err.message}`) 171 } 172}); 173``` 174 175### connect<sup>6+</sup> 176 177connect(url: string, options?: WebSocketRequestOptions): Promise\<boolean\> 178 179根据URL地址和header，建立一个WebSocket连接。使用Promise异步回调。 180 181> **说明：** 182> 183> 可通过监听error事件获得该接口的执行结果，错误发生时会得到错误码：200。 184 185**需要权限**：ohos.permission.INTERNET 186 187**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 188 189**系统能力**：SystemCapability.Communication.NetStack 190 191**注意：** URL地址长度不能超过1024个字符，否则会连接失败。 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 说明 | 196| ------- | ----------------------- | ---- | ------------------------------------------------------- | 197| url | string | 是 | 建立WebSocket连接的URL地址。 | 198| options | WebSocketRequestOptions | 否 | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 | 199 200**返回值：** 201 202| 类型 | 说明 | 203| :----------------- | :-------------------------------- | 204| Promise\<boolean\> | 回调函数。true:连接请求创建成功；false:连接请求创建失败。 | 205 206**错误码：** 207 208以下错误码的详细介绍参见[webSocket错误码](errorcode-net-webSocket.md)和[通用错误码](../errorcode-universal.md)。 209 210| 错误码ID | 错误信息 | 211| --------------------- | ------------------------------------------ | 212| 401 | Parameter error. | 213| 201 | Permission denied. | 214| 2302001 | Websocket url error. | 215| 2302002 | Websocket certificate file does not exist. | 216| 2302003 | Websocket connection already exists. | 217| 2302998 | It is not allowed to access this domain. | 218| 2302999 | Internal error. | 219 220**示例：** 221 222```ts 223import { webSocket } from '@kit.NetworkKit'; 224 225let ws = webSocket.createWebSocket(); 226let url = "ws://" 227let promise = ws.connect(url); 228promise.then((value: boolean) => { 229 console.info("connect success") 230}).catch((err:string) => { 231 console.error("connect fail, error:" + JSON.stringify(err)) 232}); 233``` 234 235### send<sup>6+</sup> 236 237send(data: string | ArrayBuffer, callback: AsyncCallback\<boolean\>): void 238 239通过WebSocket连接发送数据，使用callback方式作为异步方法。 240 241**需要权限**：ohos.permission.INTERNET 242 243**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 244 245**系统能力**：SystemCapability.Communication.NetStack 246 247**参数：** 248 249| 参数名 | 类型 | 必填 | 说明 | 250| -------- | ------------------------ | ---- | ------------ | 251| data | string \| ArrayBuffer | 是 | 发送的数据。<br>API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。 | 252| callback | AsyncCallback\<boolean\> | 是 | 回调函数。true:发送请求创建成功；false:发送请求创建失败。 | 253 254**错误码：** 255 256以下错误码的详细介绍参见[通用错误码](../errorcode-universal.md)。 257 258| 错误码ID | 错误信息 | 259| ------- | ----------------------- | 260| 401 | Parameter error. | 261| 201 | Permission denied. | 262 263**示例：** 264 265```ts 266import { webSocket } from '@kit.NetworkKit'; 267import { BusinessError } from '@kit.BasicServicesKit'; 268 269let ws = webSocket.createWebSocket(); 270let url = "ws://" 271class OutValue { 272 status: number = 0 273 message: string = "" 274} 275ws.connect(url, (err: BusinessError, value: boolean) => { 276 if (!err) { 277 console.info("connect success") 278 } else { 279 console.error(`connect fail. Code: ${err.code}, message: ${err.message}`) 280 } 281}); 282ws.on('open', (err: BusinessError, value: Object) => { 283 console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message) 284 ws.send("Hello, server!", (err: BusinessError, value: boolean) => { 285 if (!err) { 286 console.info("send success") 287 } else { 288 console.error(`send fail. Code: ${err.code}, message: ${err.message}`) 289 } 290 }); 291}); 292``` 293 294> **说明：** 295> 296> send接口必须在监听到open事件后才可以调用。 297 298### send<sup>6+</sup> 299 300send(data: string | ArrayBuffer): Promise\<boolean\> 301 302通过WebSocket连接发送数据。使用Promise异步回调。 303 304**需要权限**：ohos.permission.INTERNET 305 306**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 307 308**系统能力**：SystemCapability.Communication.NetStack 309 310**参数：** 311 312| 参数名 | 类型 | 必填 | 说明 | 313| ------ | ------ | ---- | ------------ | 314| data | string \| ArrayBuffer | 是 | 发送的数据。<br>API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。 | 315 316**返回值：** 317 318| 类型 | 说明 | 319| :----------------- | :-------------------------------- | 320| Promise\<boolean\> | 以Promise形式返回发送数据的结果。true:发送请求创建成功；false:发送请求创建失败。 | 321 322**错误码：** 323 324以下错误码的详细介绍参见[通用错误码](../errorcode-universal.md)。 325 326| 错误码ID | 错误信息 | 327| ------- | ----------------------- | 328| 401 | Parameter error. | 329| 201 | Permission denied. | 330 331**示例：** 332 333```ts 334import { webSocket } from '@kit.NetworkKit'; 335import { BusinessError } from '@kit.BasicServicesKit'; 336 337let ws = webSocket.createWebSocket(); 338let url = "ws://" 339class OutValue { 340 status: number = 0 341 message: string = "" 342} 343ws.connect(url, (err: BusinessError, value: boolean) => { 344 if (!err) { 345 console.info("connect success") 346 } else { 347 console.error("connect fail. Code: ${err.code}, message: ${err.message}") 348 } 349}); 350 351ws.on('open', (err: BusinessError, value: Object) => { 352 console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message) 353 let promise = ws.send("Hello, server!"); 354 promise.then((value: boolean) => { 355 console.info("send success") 356 }).catch((err:string) => { 357 console.error("send fail, error:" + JSON.stringify(err)) 358 }); 359}); 360``` 361 362> **说明：** 363> 364> send接口必须在监听到open事件后才可以调用。 365 366### close<sup>6+</sup> 367 368close(callback: AsyncCallback\<boolean\>): void 369 370关闭WebSocket连接，使用callback方式作为异步方法。 371 372**需要权限**：ohos.permission.INTERNET 373 374**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 375 376**系统能力**：SystemCapability.Communication.NetStack 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| -------- | ------------------------ | ---- | ---------- | 382| callback | AsyncCallback\<boolean\> | 是 | 回调函数。true:关闭请求创建成功；false:关闭请求创建失败。 | 383 384**错误码：** 385 386以下错误码的详细介绍参见[通用错误码](../errorcode-universal.md)。 387 388| 错误码ID | 错误信息 | 389| ------- | ----------------------- | 390| 401 | Parameter error. | 391| 201 | Permission denied. | 392 393**示例：** 394 395```ts 396import { webSocket } from '@kit.NetworkKit'; 397import { BusinessError } from '@kit.BasicServicesKit'; 398 399let ws = webSocket.createWebSocket(); 400ws.close((err: BusinessError) => { 401 if (!err) { 402 console.info("close success") 403 } else { 404 console.error(`close fail. Code: ${err.code}, message: ${err.message}`) 405 } 406}); 407``` 408 409### close<sup>6+</sup> 410 411close(options: WebSocketCloseOptions, callback: AsyncCallback\<boolean\>): void 412 413根据参数options，关闭WebSocket连接，使用callback方式作为异步方法。 414 415**需要权限**：ohos.permission.INTERNET 416 417**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 418 419**系统能力**：SystemCapability.Communication.NetStack 420 421**参数：** 422 423| 参数名 | 类型 | 必填 | 说明 | 424| -------- | ------------------------ | ---- | ----------------------------------------------------- | 425| options | WebSocketCloseOptions | 是 | 参考[WebSocketCloseOptions](#websocketcloseoptions)。 | 426| callback | AsyncCallback\<boolean\> | 是 | 回调函数。true:关闭请求创建成功；false:关闭请求创建失败。 | 427 428**错误码：** 429 430以下错误码的详细介绍参见[通用错误码](../errorcode-universal.md)。 431 432| 错误码ID | 错误信息 | 433| ------- | ----------------------- | 434| 401 | Parameter error. | 435| 201 | Permission denied. | 436 437**示例：** 438 439```ts 440import { webSocket } from '@kit.NetworkKit'; 441import { BusinessError } from '@kit.BasicServicesKit'; 442 443let ws = webSocket.createWebSocket(); 444 445let options: webSocket.WebSocketCloseOptions | undefined; 446if (options != undefined) { 447 options.code = 1000 448 options.reason = "your reason" 449} 450ws.close(options, (err: BusinessError) => { 451 if (!err) { 452 console.info("close success") 453 } else { 454 console.error(`close fail. Code: ${err.code}, message: ${err.message}`) 455 } 456}); 457``` 458 459### close<sup>6+</sup> 460 461close(options?: WebSocketCloseOptions): Promise\<boolean\> 462 463根据可选参数code和reason，关闭WebSocket连接。使用Promise异步回调。 464 465**需要权限**：ohos.permission.INTERNET 466 467**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 468 469**系统能力**：SystemCapability.Communication.NetStack 470 471**参数：** 472 473| 参数名 | 类型 | 必填 | 说明 | 474| ------- | --------------------- | ---- | ----------------------------------------------------- | 475| options | WebSocketCloseOptions | 否 | 参考[WebSocketCloseOptions](#websocketcloseoptions)。 | 476 477**返回值：** 478 479| 类型 | 说明 | 480| :----------------- | :-------------------------------- | 481| Promise\<boolean\> | 以Promise形式返回关闭连接的结果。true:关闭请求创建成功；false:关闭请求创建失败。 | 482 483**错误码：** 484 485以下错误码的详细介绍参见[通用错误码](../errorcode-universal.md)。 486 487| 错误码ID | 错误信息 | 488| ------- | ----------------------- | 489| 401 | Parameter error. | 490| 201 | Permission denied. | 491 492**示例：** 493 494```ts 495import { webSocket } from '@kit.NetworkKit'; 496 497let ws = webSocket.createWebSocket(); 498let options: webSocket.WebSocketCloseOptions | undefined; 499if (options != undefined) { 500 options.code = 1000 501 options.reason = "your reason" 502} 503let promise = ws.close(); 504promise.then((value: boolean) => { 505 console.info("close success") 506}).catch((err:string) => { 507 console.error("close fail, error:" + JSON.stringify(err)) 508}); 509``` 510 511### on('open')<sup>6+</sup> 512 513on(type: 'open', callback: AsyncCallback\<Object\>): void 514 515订阅WebSocket的打开事件，使用callback方式作为异步方法。 516 517**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 518 519**系统能力**：SystemCapability.Communication.NetStack 520 521**参数：** 522 523| 参数名 | 类型 | 必填 | 说明 | 524| -------- | ----------------------- | ---- | ----------------------------- | 525| type | string | 是 | 订阅的事件类型。'open'：WebSocket的打开事件。 | 526| callback | AsyncCallback\<Object\> | 是 | 回调函数。 | 527 528**示例：** 529 530```ts 531import { webSocket } from '@kit.NetworkKit'; 532import { BusinessError, Callback } from '@kit.BasicServicesKit'; 533 534let ws= webSocket.createWebSocket(); 535class OutValue { 536 status: number = 0 537 message: string = "" 538} 539ws.on('open', (err: BusinessError, value: Object) => { 540 console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message) 541}); 542``` 543 544### off('open')<sup>6+</sup> 545 546off(type: 'open', callback?: AsyncCallback\<Object\>): void 547 548取消订阅WebSocket的打开事件，使用callback方式作为异步方法。 549 550> **说明：** 551> 552> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 553 554**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 555 556**系统能力**：SystemCapability.Communication.NetStack 557 558**参数：** 559 560| 参数名 | 类型 | 必填 | 说明 | 561| -------- | ----------------------- | ---- | ----------------------------- | 562| type | string | 是 | 取消订阅的事件类型。'open'：WebSocket的打开事件。 | 563| callback | AsyncCallback\<Object\> | 否 | 回调函数。 | 564 565**示例：** 566 567```ts 568import { webSocket } from '@kit.NetworkKit'; 569import { BusinessError } from '@kit.BasicServicesKit'; 570 571let ws = webSocket.createWebSocket(); 572class OutValue { 573 status: number = 0 574 message: string = "" 575} 576let callback1 = (err: BusinessError, value: Object) => { 577 console.info("on open, status:" + ((value as OutValue).status + ", message:" + (value as OutValue).message)) 578} 579ws.on('open', callback1); 580// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 581ws.off('open', callback1); 582``` 583 584### on('message')<sup>6+</sup> 585 586on(type: 'message', callback: AsyncCallback\<string | ArrayBuffer\>): void 587 588订阅WebSocket的接收服务器消息事件，使用callback方式作为异步方法。 589 590> **说明：** 591> 592> AsyncCallback中的数据可以是字符串（API version 6开始支持）或ArrayBuffer（API version 8开始支持）。 593 594**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 595 596**系统能力**：SystemCapability.Communication.NetStack 597 598**参数：** 599 600| 参数名 | 类型 | 必填 | 说明 | 601| -------- | ----------------------- | ---- | -------------------------------------------- | 602| type | string | 是 | 订阅的事件类型。'message'：WebSocket的接收服务器消息事件。 | 603| callback | AsyncCallback\<string \| ArrayBuffer <sup>8+</sup>\> | 是 | 回调函数。 | 604 605**示例：** 606 607```ts 608import { webSocket } from '@kit.NetworkKit'; 609import { BusinessError } from '@kit.BasicServicesKit'; 610 611let ws = webSocket.createWebSocket(); 612ws.on('message', (err: BusinessError<void>, value: string | ArrayBuffer) => { 613 console.info("on message, message:" + value) 614}); 615``` 616 617### off('message')<sup>6+</sup> 618 619off(type: 'message', callback?: AsyncCallback\<string | ArrayBuffer\>): void 620 621取消订阅WebSocket的接收服务器消息事件，使用callback方式作为异步方法。 622 623> **说明：** 624> 625> AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。 626> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 627 628**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 629 630**系统能力**：SystemCapability.Communication.NetStack 631 632**参数：** 633 634| 参数名 | 类型 | 必填 | 说明 | 635| -------- | --------------------------------------------------- | ---- | -------------------------------------------- | 636| type | string | 是 | 取消订阅的事件类型。'message'：WebSocket的接收到服务器消息事件。 | 637| callback | AsyncCallback\<string \|ArrayBuffer <sup>8+</sup>\> | 否 | 回调函数。 | 638 639**示例：** 640 641```ts 642import { webSocket } from '@kit.NetworkKit'; 643 644let ws = webSocket.createWebSocket(); 645ws.off('message'); 646``` 647 648### on('close')<sup>6+</sup> 649 650on(type: 'close', callback: AsyncCallback\<CloseResult\>): void 651 652订阅WebSocket的关闭事件，使用callback方式作为异步方法。 653 654**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 655 656**系统能力**：SystemCapability.Communication.NetStack 657 658**参数：** 659 660| 参数名 | 类型 | 必填 | 说明 | 661| -------- | ----------------------------------------------- | ---- | ------------------------------ | 662| type | string | 是 | 订阅的事件类型。'close'：WebSocket的关闭事件。 | 663| callback | AsyncCallback\<CloseResult\> | 是 | 回调函数。<br>close：close错误码，reason：错误码说明 | 664 665**示例：** 666 667```ts 668import { webSocket } from '@kit.NetworkKit'; 669import { BusinessError } from '@kit.BasicServicesKit'; 670 671let ws = webSocket.createWebSocket(); 672ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => { 673 console.info("on close, code is " + value.code + ", reason is " + value.reason) 674}); 675``` 676 677### off('close')<sup>6+</sup> 678 679off(type: 'close', callback?: AsyncCallback\<CloseResult\>): void 680 681取消订阅WebSocket的关闭事件，使用callback方式作为异步方法。 682 683> **说明：** 684> 685> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 686 687**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 688 689**系统能力**：SystemCapability.Communication.NetStack 690 691**参数：** 692 693| 参数名 | 类型 | 必填 | 说明 | 694| -------- | ----------------------------------------------- | ---- | ------------------------------ | 695| type | string | 是 | 取消订阅的事件类型。'close'：WebSocket的关闭事件。 | 696| callback | AsyncCallback\<CloseResult\> | 否 | 回调函数。<br>close：close错误码，reason：错误码说明 | 697 698**示例：** 699 700```ts 701import { webSocket } from '@kit.NetworkKit'; 702 703let ws = webSocket.createWebSocket(); 704ws.off('close'); 705``` 706 707### on('error')<sup>6+</sup> 708 709on(type: 'error', callback: ErrorCallback): void 710 711订阅WebSocket的Error事件，使用callback方式作为异步方法。 712 713**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 714 715**系统能力**：SystemCapability.Communication.NetStack 716 717**参数：** 718 719| 参数名 | 类型 | 必填 | 说明 | 720| -------- | ------------- | ---- | ------------------------------- | 721| type | string | 是 | 订阅的事件类型。'error'：WebSocket的Error事件。 | 722| callback | ErrorCallback | 是 | 回调函数。 | 723 724**示例：** 725 726```ts 727import { webSocket } from '@kit.NetworkKit'; 728import { BusinessError } from '@kit.BasicServicesKit'; 729 730let ws = webSocket.createWebSocket(); 731ws.on('error', (err: BusinessError) => { 732 console.error(`on error. Code: ${err.code}, message: ${err.message}`) 733}); 734``` 735 736### off('error')<sup>6+</sup> 737 738off(type: 'error', callback?: ErrorCallback): void 739 740取消订阅WebSocket的Error事件，使用callback方式作为异步方法。 741 742> **说明：** 743> 744> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 745 746**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 747 748**系统能力**：SystemCapability.Communication.NetStack 749 750**参数：** 751 752| 参数名 | 类型 | 必填 | 说明 | 753| -------- | ------------- | ---- | ------------------------------- | 754| type | string | 是 | 取消订阅的事件类型。'error'：WebSocket的Error事件。 | 755| callback | ErrorCallback | 否 | 回调函数。 | 756 757**示例：** 758 759```ts 760import { webSocket } from '@kit.NetworkKit'; 761 762let ws = webSocket.createWebSocket(); 763ws.off('error'); 764``` 765 766### on('dataEnd')<sup>11+</sup> 767 768on(type: 'dataEnd', callback: Callback\<void\>): void 769 770订阅WebSocket的数据接收结束事件，使用callback方式作为异步方法。 771 772**系统能力**：SystemCapability.Communication.NetStack 773 774**参数：** 775 776| 参数名 | 类型 | 必填 | 说明 | 777| -------- | ---------------- | ---- | --------------------------------------- | 778| type | string | 是 | 订阅的事件类型。'dataEnd'：WebSocket的数据接收结束事件。 | 779| callback | Callback\<void\> | 是 | 回调函数。 | 780 781**示例：** 782 783```ts 784import { webSocket } from '@kit.NetworkKit'; 785 786let ws = webSocket.createWebSocket(); 787ws.on('dataEnd', () => { 788 console.info("on dataEnd") 789}); 790``` 791 792### off('dataEnd')<sup>11+</sup> 793 794off(type: 'dataEnd', callback?: Callback\<void\>): void 795 796取消订阅WebSocket的数据接收结束事件，使用callback方式作为异步方法。 797 798> **说明：** 799> 800> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 801 802**系统能力**：SystemCapability.Communication.NetStack 803 804**参数：** 805 806| 参数名 | 类型 | 必填 | 说明 | 807| -------- | ---------------- | ---- | -------------------------------------- | 808| type | string | 是 | 取消订阅的事件类型。'dataEnd'：WebSocket的数据接收结束事件。| 809| callback | Callback\<void\> | 否 | 回调函数。 | 810 811**示例：** 812 813```ts 814import { webSocket } from '@kit.NetworkKit'; 815 816let ws = webSocket.createWebSocket(); 817ws.off('dataEnd'); 818``` 819 820### on('headerReceive')<sup>12+</sup> 821 822on(type: 'headerReceive', callback: Callback\<ResponseHeaders\>): void 823 824订阅HTTP Response Header事件，使用callback方式作为异步方法。 825 826**系统能力**：SystemCapability.Communication.NetStack 827 828**参数：** 829 830| 参数名 | 类型 | 必填 | 说明 | 831| -------- | ---------------- | ---- | -------------------------------------- | 832| type | string | 是 | 订阅的事件类型。'headerReceive'：WebSocket的headerReceive事件。| 833| callback | Callback\<ResponseHeaders\> | 是 | 回调函数，返回订阅事件。 | 834 835**示例：** 836 837```ts 838import { webSocket } from '@kit.NetworkKit'; 839 840let ws = webSocket.createWebSocket(); 841ws.on('headerReceive', (data) => { 842 console.info("on headerReceive " + JSON.stringify(data)) 843}); 844``` 845 846### off('headerReceive')<sup>12+</sup> 847 848off(type: 'headerReceive', callback?: Callback\<ResponseHeaders\>): void 849 850取消订阅HTTP Response Header事件，使用callback方式作为异步方法。 851 852> **说明：** 853> 854> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 855 856**系统能力**：SystemCapability.Communication.NetStack 857 858**参数：** 859 860| 参数名 | 类型 | 必填 | 说明 | 861| -------- | ---------------- | ---- | -------------------------------------- | 862| type | string | 是 | 取消订阅的事件类型。'headerReceive'：WebSocket的headerReceive事件。| 863| callback | Callback\<ResponseHeaders\> | 否 | 回调函数，返回订阅事件。 | 864 865**示例：** 866 867```ts 868import { webSocket } from '@kit.NetworkKit'; 869 870let ws = webSocket.createWebSocket(); 871ws.off('headerReceive'); 872``` 873 874## webSocket.createWebSocketServer<sup>19+</sup> 875 876createWebSocketServer(): WebSocketServer 877 878创建一个WebSocketServer对象，包括启动服务、发送数据、关闭连接、列出客户端信息、停止服务，订阅/取消订阅webSocket连接的连接事件、接收到客户端消息事件、关闭事件和错误事件。 879 880> **说明：** 881> 882> 目前该接口在TV中可正常调用，在其他设备中无效果，返回nullptr。 883 884**系统能力**: SystemCapability.Communication.NetStack 885 886**返回值：** 887 888| 类型 | 说明 | 889| :---------------------------------- | :----------------------------------------------------------- | 890| [WebSocketServer](#websocketserver19) | 返回一个WebSocketServer对象，里面包括start、listAllConnections、send、close、stop、on和off方法。 | 891 892**示例：** 893 894```ts 895let ws: webSocket.WebSocketServer = webSocket.createWebSocketServer(); 896``` 897 898## WebSocketServer<sup>19+</sup> 899 900在调用WebSocketServer方法前，需要先通过[webSocket.createWebSocketServer](#websocketcreatewebsocketserver19)创建一个WebSocketServer。 901 902### start<sup>19+</sup> 903 904start(config: WebSocketServerConfig): Promise\<boolean\> 905 906配置config参数，启动服务端service。使用Promise异步回调。 907 908> **说明：** 909> 910> 可通过监听error事件获得该接口的执行结果，错误码说明参见[webSocket错误码](errorcode-net-webSocket.md)。 911 912**需要权限**: ohos.permission.INTERNET 913 914**系统能力**: SystemCapability.Communication.NetStack 915 916**参数：** 917 918| 参数名 | 类型 | 必填 | 说明 | 919| ------- | ----------------------- | ---- | ------------------------------------------------------ | 920| config | [WebSocketServerConfig](#websocketserverconfig19) | 是 | 启动websocketServer服务器。 | 921 922**返回值：** 923 924| 类型 | 说明 | 925| :----------------- | :-------------------------------- | 926| Promise\<boolean\> | promise对象。返回true表示服务器启动成功；返回false表示服务启动失败。 | 927 928**错误码：** 929 930以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[webSocket错误码](errorcode-net-webSocket.md)。 931 932| 错误码ID | 错误信息 | 933| ------- | ------------------------------------------ | 934| 201 | Permission denied. | 935| 2302002 | Websocket certificate file does not exist. | 936| 2302004 | Can't listen on the given NIC. | 937| 2302005 | Can't listen on the given Port. | 938| 2302999 | Websocket other unknown error. | 939 940**示例：** 941 942```ts 943import { webSocket } from '@kit.NetworkKit'; 944import { BusinessError } from '@kit.BasicServicesKit'; 945 946let localServer: webSocket.WebSocketServer; 947let config: webSocket.WebSocketServerConfig = { 948 serverPort: 8080, // 监听端口 949 maxConcurrentClientsNumber: 10, 950 maxConnectionsForOneClient: 10, 951} 952 953localServer = webSocket.createWebSocketServer(); 954localServer.start(config).then((success: boolean) => { 955 if (success) { 956 console.info('webSocket server start success'); 957 } else { 958 console.error('websocket server start failed'); 959 } 960}).catch((error: BusinessError) => { 961 console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`); 962}); 963``` 964 965### send<sup>19+</sup> 966 967send(data: string \| ArrayBuffer, connection: WebSocketConnection): Promise\<boolean\> 968 969通过WebSocket连接发送数据。使用Promise异步回调。 970 971> **说明：** 972> 973> send接口必须在监听到connect事件后才可以调用。 974 975**需要权限**: ohos.permission.INTERNET 976 977**系统能力**: SystemCapability.Communication.NetStack 978 979**参数：** 980 981| 参数名 | 类型 | 必填 | 说明 | 982| ---------- | ---------------------- | --------------------- | ------------------------------------------------ | 983| data | string \| ArrayBuffer | 是 | 服务端发送消息的数据，同时支持string（字符串）和ArrayBuffer（二进制）类型。 | 984| connection | [WebSocketConnection](#websocketconnection19) | 是 | 发送的客户端信息。 | 985 986**返回值：** 987 988| 类型 | 说明 | 989| :----------------- | :-------------------------------- | 990| Promise\<boolean\> | promise对象。返回true表示发送请求创建成功；返回false表示发送请求创建失败。 | 991 992**错误码：** 993 994以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[webSocket错误码](errorcode-net-webSocket.md)。 995 996| 错误码ID | 错误信息 | 997| ------- | ----------------------- | 998| 201 | Permission denied. | 999| 2302006 | websocket connection does not exist. | 1000 1001**示例：** 1002 1003```ts 1004import { webSocket } from '@kit.NetworkKit'; 1005import { BusinessError } from '@kit.BasicServicesKit'; 1006 1007let localServer: webSocket.WebSocketServer; 1008let config: webSocket.WebSocketServerConfig = { 1009 serverPort: 8080, // 监听端口 1010 maxConcurrentClientsNumber: 10, 1011 maxConnectionsForOneClient: 10, 1012} 1013 1014localServer = webSocket.createWebSocketServer(); 1015localServer.start(config).then((success: boolean) => { 1016 if (success) { 1017 console.info('webSocket server start success'); 1018 } else { 1019 console.error('websocket server start failed'); 1020 } 1021}).catch((error: BusinessError) => { 1022 console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`); 1023}); 1024 1025localServer.on('connect', async (connection: webSocket.WebSocketConnection) => { 1026 console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`); 1027 // 当收到on('connect')事件时，可以通过send()方法与客户端进行通信 1028 localServer.send("Hello, I'm server!", connection).then((success: boolean) => { 1029 if (success) { 1030 console.info('message send successfully'); 1031 } else { 1032 console.error('message send failed'); 1033 } 1034 }).catch((error: BusinessError) => { 1035 console.error(`message send failed, Code: ${error.code}, message: ${error.message}`); 1036 }); 1037}); 1038``` 1039 1040### listAllConnections<sup>19+</sup> 1041 1042listAllConnections(): WebSocketConnection[] 1043 1044获取与服务端连接的所有客户端信息。 1045 1046**需要权限**: ohos.permission.INTERNET 1047 1048**系统能力**：SystemCapability.Communication.NetStack 1049 1050**返回值：** 1051| 类型 | 说明 | 1052| ------------------------------------------- | ---------------------------- | 1053| [WebSocketConnection[]](#websocketconnection19) | 以字符串数组形式返回所有客户端的信息。| 1054 1055**错误码：** 1056 1057以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1058 1059| 错误码ID | 错误信息 | 1060| ------- | ----------------------- | 1061| 201 | Permission denied. | 1062 1063**示例：** 1064```ts 1065import { webSocket } from '@kit.NetworkKit'; 1066import { BusinessError } from '@kit.BasicServicesKit'; 1067 1068let connections: webSocket.WebSocketConnection[] = []; 1069let localServer: webSocket.WebSocketServer; 1070let config: webSocket.WebSocketServerConfig = { 1071 serverPort: 8080, // 监听端口 1072 maxConcurrentClientsNumber: 10, 1073 maxConnectionsForOneClient: 10, 1074} 1075 1076localServer = webSocket.createWebSocketServer(); 1077localServer.start(config).then((success: boolean) => { 1078 if (success) { 1079 console.info('webSocket server start success'); 1080 } else { 1081 console.error('websocket server start failed'); 1082 } 1083}).catch((error: BusinessError) => { 1084 console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`); 1085}); 1086 1087localServer.on('connect', async (connection: webSocket.WebSocketConnection) => { 1088 console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`); 1089 try { 1090 connections = await localServer.listAllConnections(); 1091 if (connections.length === 0) { 1092 console.info('client list is empty'); 1093 } else { 1094 console.info(`client list cnt: ${connections.length}, client connections list is: ${connections}`); 1095 } 1096 } catch (error) { 1097 console.error(`Failed to listAllConnections. Code: ${error.code}, message: ${error.message}`); 1098 } 1099}); 1100``` 1101 1102### close<sup>19+</sup> 1103 1104close(connection: WebSocketConnection, options?: webSocket.WebSocketCloseOptions): Promise\<boolean\> 1105 1106关闭指定websocket连接。使用Promise异步回调。 1107 1108**需要权限**：ohos.permission.INTERNET 1109 1110**系统能力**：SystemCapability.Communication.NetStack 1111 1112**参数：** 1113 1114| 参数名 | 类型 | 必填 | 说明 | 1115| ---------- | --------------------- | ---- | ----------------------------------------------------- | 1116| connection | [WebSocketConnection](#websocketconnection19) | 是 | 客户端信息，包括客户端的ip地址和端口号port。 | 1117| options | [webSocket.WebSocketCloseOptions](#websocketcloseoptions) | 否 | 关闭WebSocket连接时，可选参数的类型和说明。<br>- 错误码默认：200。原因值默认：Websocket connect failed。 | 1118 1119**返回值：** 1120 1121| 类型 | 说明 | 1122| :----------------- | :------------------------------------------------------------------------- | 1123| Promise\<boolean\> | promise对象。返回true表示关闭请求创建成功；返回false表示关闭请求创建失败。 | 1124 1125**错误码：** 1126 1127以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[webSocket错误码](errorcode-net-webSocket.md)。 1128 1129| 错误码ID | 错误信息 | 1130| ------- | ----------------------- | 1131| 201 | Permission denied. | 1132| 2302006 | websocket connection does not exist.| 1133 1134**示例：** 1135 1136```ts 1137import { webSocket } from '@kit.NetworkKit'; 1138import { BusinessError } from '@kit.BasicServicesKit'; 1139 1140let localServer: webSocket.WebSocketServer; 1141let config: webSocket.WebSocketServerConfig = { 1142 serverPort: 8080, // 监听端口 1143 maxConcurrentClientsNumber: 10, 1144 maxConnectionsForOneClient: 10, 1145} 1146 1147localServer = webSocket.createWebSocketServer(); 1148localServer.start(config).then((success: boolean) => { 1149 if (success) { 1150 console.info('webSocket server start success'); 1151 } else { 1152 console.error('websocket server start failed'); 1153 } 1154}).catch((error: BusinessError) => { 1155 console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`); 1156}); 1157 1158localServer.on('connect', (connection: webSocket.WebSocketConnection) => { 1159 console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`); 1160 localServer.close(connection).then((success: boolean) => { 1161 if (success) { 1162 console.info('close client successfully'); 1163 } else { 1164 console.error('close client failed'); 1165 } 1166 }); 1167}); 1168``` 1169 1170### stop<sup>19+</sup> 1171 1172stop(): Promise\<boolean\> 1173 1174停止服务端服务。使用Promise异步回调。 1175 1176**需要权限**：ohos.permission.INTERNET 1177 1178**系统能力**：SystemCapability.Communication.NetStack 1179 1180**返回值：** 1181 1182| 类型 | 说明 | 1183| :----------------- | :------------------------------------------------------------------------- | 1184| Promise\<boolean\> | promise对象。返回true表示停止服务端service请求创建成功；返回false表示停止服务端service请求创建失败。 | 1185 1186**错误码：** 1187 1188以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1189 1190| 错误码ID | 错误信息 | 1191| ------- | ----------------------- | 1192| 201 | Permission denied. | 1193 1194**示例：** 1195 1196```ts 1197import { webSocket } from '@kit.NetworkKit'; 1198import { BusinessError } from '@kit.BasicServicesKit'; 1199 1200let localServer: webSocket.WebSocketServer; 1201let config: webSocket.WebSocketServerConfig = { 1202 serverPort: 8080, // 监听端口 1203 maxConcurrentClientsNumber: 10, 1204 maxConnectionsForOneClient: 10, 1205} 1206 1207localServer = webSocket.createWebSocketServer(); 1208localServer.start(config).then((success: boolean) => { 1209 if (success) { 1210 console.info('webSocket server start success'); 1211 } else { 1212 console.error('websocket server start failed'); 1213 } 1214}).catch((error: BusinessError) => { 1215 console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`); 1216}); 1217 1218localServer.stop().then((success: boolean) => { 1219 if (success) { 1220 console.info('server stop service successfully'); 1221 } else { 1222 console.error('server stop service failed'); 1223 } 1224}); 1225``` 1226 1227### on('connect')<sup>19+</sup> 1228 1229on(type: 'connect', callback: Callback\<WebSocketConnection\>): void 1230 1231订阅WebSocketServer的连接事件（客户端与服务端建链成功），使用callback方式作为异步方法。 1232 1233**系统能力**：SystemCapability.Communication.NetStack 1234 1235**参数：** 1236 1237| 参数名 | 类型 | 必填 | 说明 | 1238| -------- | ----------------------- | ---- | ------------------------------------------------------- | 1239| type | string | 是 | 事件回调类型，支持的事件为'connect'，当onconnect()调用完成，客户端与服务端建链成功。 | 1240| callback | Callback\<[WebSocketConnection](#websocketconnection19)\> | 是 | 回调函数。连接的客户端信息。| 1241 1242**示例：** 1243 1244```ts 1245import { webSocket } from '@kit.NetworkKit'; 1246import { BusinessError, Callback } from '@kit.BasicServicesKit'; 1247 1248let localServer = webSocket.createWebSocketServer(); 1249localServer.on('connect', (connection: webSocket.WebSocketConnection) => { 1250 console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`); 1251}); 1252``` 1253 1254### off('connect')<sup>19+</sup> 1255 1256off(type: 'connect', callback?: Callback\<WebSocketConnection\>): void 1257 1258取消订阅WebSocketServer的连接事件（客户端与服务端建链成功），使用callback方式作为异步方法。 1259 1260> **说明：** 1261> 1262> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1263 1264**系统能力**：SystemCapability.Communication.NetStack 1265 1266**参数：** 1267 1268| 参数名 | 类型 | 必填 | 说明 | 1269| -------- | ----------------------- | ---- | ------------------------------------------- | 1270| type | string | 是 | 事件回调类型，支持的事件为'connect'，当offconnect()调用完成，取消监听连接事件成功。 | 1271| callback | Callback\<[WebSocketConnection](#websocketconnection19)\> | 否 | 回调函数。连接的客户端信息。 | 1272 1273**示例：** 1274 1275```ts 1276import { webSocket } from '@kit.NetworkKit'; 1277import { BusinessError } from '@kit.BasicServicesKit'; 1278 1279let localServer = webSocket.createWebSocketServer(); 1280localServer.off('connect'); 1281``` 1282 1283### on('messageReceive')<sup>19+</sup> 1284 1285on(type: 'messageReceive', callback: Callback\<WebSocketMessage\>): void 1286 1287订阅WebSocketServer的接收客户端消息的事件，使用callback方式作为异步方法。 1288 1289**系统能力**：SystemCapability.Communication.NetStack 1290 1291**参数：** 1292 1293| 参数名 | 类型 | 必填 | 说明 | 1294| -------- | ----------------------- | ---- | -------------------------------- | 1295| type | string | 是 | 事件回调类型，支持的事件为'messageReceive'，当onmessageReceive()调用完成，接收到客户端消息成功。 | 1296| callback | Callback\<[WebSocketMessage](#websocketmessage19)\> | 是 | 回调函数。<br>clientconnection:客户端信息，data:客户端发送的数据消息。| 1297 1298**示例：** 1299 1300```ts 1301import { webSocket } from '@kit.NetworkKit'; 1302import { BusinessError, Callback } from '@kit.BasicServicesKit'; 1303 1304let localServer = webSocket.createWebSocketServer(); 1305localServer.on('messageReceive', (message: webSocket.WebSocketMessage) => { 1306 console.info(`on message received, client: ${message.clientConnection}, data: ${message.data}`); 1307}); 1308``` 1309 1310### off('messageReceive')<sup>19+</sup> 1311 1312off(type: 'messageReceive', callback?: Callback\<WebSocketMessage\>): void 1313 1314取消订阅WebSocketServer的接收到客户端消息事件，使用callback方式作为异步方法。 1315 1316> **说明：** 1317> 1318> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1319 1320**系统能力**：SystemCapability.Communication.NetStack 1321 1322**参数：** 1323 1324| 参数名 | 类型 | 必填 | 说明 | 1325| -------- | --------------------------------------------------- | ---- | -------------------------------------------- | 1326| type | string | 是 | 事件回调类型，支持的事件为'messageReceive'，当offmessageReceive()调用完成，取消订阅接收客户端消息成功。 | 1327| callback | Callback\<[WebSocketMessage](#websocketmessage19)\> | 否 | 从指定客户端接收到的消息，包括客户端的信息和数据。<br>- clientconnection：客户端信息。<br>- data：客户端发送的消息。| 1328 1329**示例：** 1330 1331```ts 1332import { webSocket } from '@kit.NetworkKit'; 1333import { BusinessError, Callback } from '@kit.BasicServicesKit'; 1334 1335let localServer = webSocket.createWebSocketServer(); 1336localServer.off('messageReceive'); 1337``` 1338 1339### on('close')<sup>19+</sup> 1340 1341on(type: 'close', callback: ClientConnectionCloseCallback): void 1342 1343订阅WebSocketServer的关闭事件，使用callback方式作为异步方法。 1344 1345**系统能力**：SystemCapability.Communication.NetStack 1346 1347**参数：** 1348 1349| 参数名 | 类型 | 必填 | 说明 | 1350| -------- | ----------------------------------------------- | ---- | ----------------------------------- | 1351| type | string | 是 | 事件回调类型，支持的事件为'close'，当onclose()调用完成，连接关闭成功。 | 1352| callback | [ClientConnectionCloseCallback](#clientconnectionclosecallback19) | 是 | 回调函数。<br>close：close错误码；reason：错误码说明。 | 1353 1354**示例：** 1355 1356```ts 1357import { webSocket } from '@kit.NetworkKit'; 1358import { BusinessError } from '@kit.BasicServicesKit'; 1359 1360let localServer = webSocket.createWebSocketServer(); 1361localServer.on('close', (clientConnection: webSocket.WebSocketConnection, closeReason: webSocket.CloseResult) => { 1362 console.info(`client close, client: ${clientConnection}, closeReason: Code: ${closeReason.code}, reason: ${closeReason.reason}`); 1363}); 1364``` 1365 1366### off('close')<sup>19+</sup> 1367 1368off(type: 'close', callback?: ClientConnectionCloseCallback): void 1369 1370取消订阅WebSocketServer的关闭事件，使用callback方式作为异步方法。 1371 1372> **说明：** 1373> 1374> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1375 1376**系统能力**：SystemCapability.Communication.NetStack 1377 1378**参数：** 1379 1380| 参数名 | 类型 | 必填 | 说明 | 1381| -------- | ----------------------------------------------- | ---- | ---------------------------------- | 1382| type | string | 是 | 事件回调类型，支持的事件为'close'，当offclose()调用完成，取消订阅连接关闭事件成功。 | 1383| callback | [ClientConnectionCloseCallback](#clientconnectionclosecallback19) | 否 | 回调函数。<br>close：close错误码；reason：错误码说明。 | 1384 1385**示例：** 1386 1387```ts 1388import { webSocket } from '@kit.NetworkKit'; 1389import { BusinessError } from '@kit.BasicServicesKit'; 1390 1391let localServer = webSocket.createWebSocketServer(); 1392localServer.off('close'); 1393``` 1394 1395### on('error')<sup>19+</sup> 1396 1397on(type: 'error', callback: ErrorCallback): void 1398 1399订阅WebSocketServer的Error事件，使用callback方式作为异步方法。 1400 1401**系统能力**：SystemCapability.Communication.NetStack 1402 1403**参数：** 1404 1405| 参数名 | 类型 | 必填 | 说明 | 1406| -------- | ------------- | ---- | ------------------------------------ | 1407| type | string | 是 | 事件回调类型，支持的事件为'error'，当onerror()调用完成，error事件发生。 | 1408| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 回调函数。| 1409 1410**示例：** 1411 1412```ts 1413import { webSocket } from '@kit.NetworkKit'; 1414import { BusinessError } from '@kit.BasicServicesKit'; 1415 1416let wsServer: webSocket.WebSocketServer = webSocket.createWebSocketServer(); 1417wsServer.on('error', (err: BusinessError) => { 1418 console.error(`error. Code: ${err.code}, message: ${err.message}`); 1419}); 1420``` 1421 1422### off('error')<sup>19+</sup> 1423 1424off(type: 'error', callback?: ErrorCallback): void 1425 1426取消订阅WebSocketServer的Error事件，使用callback方式作为异步方法。 1427 1428> **说明：** 1429> 1430> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1431 1432**系统能力**：SystemCapability.Communication.NetStack 1433 1434**参数：** 1435 1436| 参数名 | 类型 | 必填 | 说明 | 1437| -------- | ------------- | ---- | --------------------------------- | 1438| type | string | 是 | 事件回调类型，支持的事件为'error'，当offerror()调用完成，取消订阅error事件成功。 | 1439| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 回调函数。默认值：200。 | 1440 1441**示例：** 1442 1443```ts 1444import { webSocket } from '@kit.NetworkKit'; 1445import { BusinessError } from '@kit.BasicServicesKit'; 1446 1447let localServer = webSocket.createWebSocketServer(); 1448localServer.off('error'); 1449``` 1450 1451## WebSocketRequestOptions 1452 1453建立WebSocket连接时，可选参数的类型和说明。 1454 1455**系统能力**：SystemCapability.Communication.NetStack 1456 1457| 名称 | 类型 | 只读 | 可选 | 说明 | 1458| ------ | ------ |------ | ---- | ------------------------------------------------------------ | 1459| header | Object | 否 | 是 | 建立WebSocket连接可选参数，代表建立连接时携带的HTTP头信息。参数内容自定义，也可以不指定。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1460| caPath<sup>11+</sup> | string | 否 | 是 | 如果设置了此参数，系统将使用用户指定路径的CA证书，(开发者需保证该路径下CA证书的可访问性)，否则将使用系统预设CA证书，系统预设CA证书位置：/etc/ssl/certs/cacert.pem。证书路径为沙箱映射路径（开发者可通过UIAbilityContext提供的能力获取应用沙箱路径）。目前仅支持格式为pem的文本证书。 | 1461| clientCert<sup>11+</sup> | [ClientCert](#clientcert11) | 否 | 是 | 支持传输客户端证书。 | 1462| proxy<sup>12+</sup> | ProxyConfiguration | 否 | 是 | 通信过程中的代理信息，默认使用系统网络代理。 | 1463| protocol<sup>12+</sup> | string | 否 | 是 | 自定义Sec-WebSocket-Protocol字段，默认为""。 | 1464| skipServerCertVerification<sup>20+</sup> | boolean | 否 | 是 | 是否跳过服务器证书验证。true表示跳过服务器证书验证，false表示不跳过服务器证书验证。默认为false。 | 1465| pingInterval<sup>21+</sup> | int | 否 | 是 | 自定义[心跳检测](../../network/websocket-connection.md#场景介绍)时间，默认为30s。每pingInterval周期会发起心跳检测，设置为0则表示关闭心跳检测。最大值：30000s，最小值：0s。<br>**ArkTS版本：** 该接口仅适用于ArkTS1.2。 | 1466| pongTimeout<sup>21+</sup> | int | 否 | 是 | 自定义发起心跳检测后，超时断开时间，默认为30s。发起心跳检测后若pongTimeout时间未响应则断开连接。最大值：30000s，最小值：0s。pongTimeout须小于等于pingInterval。<br>**ArkTS版本：** 该接口仅适用于ArkTS1.2。| 1467 1468## ClientCert<sup>11+</sup> 1469 1470客户端证书类型。 1471 1472**系统能力**：SystemCapability.Communication.NetStack 1473 1474| 名称 | 类型 | 必填 | 说明 | 1475| ------ | ------ | ---- |-------------------| 1476| certPath | string | 是 | 证书路径。 | 1477| keyPath | string | 是 | 证书密钥的路径。 | 1478| keyPassword | string | 否 | 证书密钥的密码。缺省为空字符串。 | 1479 1480## ProxyConfiguration<sup>12+</sup> 1481type ProxyConfiguration = 'system' | 'no-proxy' | HttpProxy 1482 1483网络代理配置信息 1484 1485**系统能力**：SystemCapability.Communication.NetStack 1486 1487| 类型 | 说明 | 1488| ------ |------------------------- | 1489| 'system' | 使用系统默认网络代理。 | 1490| 'no-proxy' | 不使用网络代理。 | 1491| [HttpProxy](js-apis-net-connection.md#httpproxy10) | 使用指定的网络代理。 | 1492 1493## WebSocketCloseOptions 1494 1495关闭WebSocket连接时，可选参数的类型和说明。 1496 1497**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1498 1499**系统能力**：SystemCapability.Communication.NetStack 1500 1501| 名称 | 类型 | 必填 | 说明 | 1502| ------ | ------ | ---- | ------------------------------------------------------------ | 1503| code | number | 否 | 错误码，关闭WebSocket连接时的可选参数，可根据实际情况来填。传入值需为正整数，默认值为1000。 | 1504| reason | string | 否 | 原因值，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为空字符串（""）。 | 1505 1506## CloseResult<sup>10+</sup> 1507 1508关闭WebSocket连接时，订阅close事件得到的关闭结果。 1509 1510**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1511 1512**系统能力**：SystemCapability.Communication.NetStack 1513 1514| 名称 | 类型 | 必填 | 说明 | 1515| ------ | ------ | ---- | ------------------------------------------------------------ | 1516| code | number | 是 | 错误码，订阅close事件得到的关闭连接的错误码。 | 1517| reason | string | 是 | 原因值，订阅close事件得到的关闭连接的错误原因。 | 1518 1519## ResponseHeaders<sup>12+</sup> 1520type ResponseHeaders = { 1521 [k: string]: string | string[] | undefined; 1522} 1523 1524服务器发送的响应头。 1525 1526**系统能力**：SystemCapability.Communication.NetStack 1527 1528| 类型 | 说明 | 1529| ------ | ------------------------------------------------------------ | 1530| [k:string]:string \| string[] \| undefined | header数据类型为键值对、字符串或者undefined。 | 1531 1532## close错误码说明 1533 1534发送给服务端的错误码可以自行定义，下面的列表仅供参考。 1535 1536**系统能力**：SystemCapability.Communication.NetStack 1537 1538| 值 | 说明 | 1539| :-------- | :----------------- | 1540| 1000 | 正常关闭。 | 1541| 1001 | 服务器主动关闭。 | 1542| 1002 | 协议错误。 | 1543| 1003 | 无法处理的数据类型。 | 1544| 1004~1015 | 保留值。 | 1545 1546## HttpProxy<sup>12+</sup> 1547 1548type HttpProxy = connection.HttpProxy 1549 1550网络全局代理配置信息。 1551 1552**系统能力**：SystemCapability.Communication.NetManager.Core 1553 1554| 类型 | 说明 | 1555| ---------------- | --------------------------- | 1556| connection.HttpProxy | 使用指定的网络代理。 | 1557 1558## WebSocketServerConfig<sup>19+</sup> 1559 1560启动服务端的service时，需要输入的配置信息和说明。 1561 1562**系统能力**：SystemCapability.Communication.NetStack 1563 1564| 名称 | 类型 | 只读 | 可选 | 说明 | 1565| ---------- | ------ | ---- | ---- | ----------------------------------------------------- | 1566| serverIP | string | 否 | 是 | 服务端监听特定ip地址，默认是"0.0.0.0"。 | 1567| serverPort | number | 否 | 否 | 服务端监听的端口号。 | 1568| serverCert | [ServerCert](#servercert19) | 否 | 是 | 指定服务端证书的信息，包括服务端证书文件路径和服务端证书的私钥文件路径。 | 1569| protocol | string | 否 | 是 | 自定义协议。 | 1570| maxConcurrentClientsNumber | number | 否 | 否 | 最大并发客户端数量，当到达最大数时，服务端拒绝新连接。默认最大数量为10。 | 1571| maxConnectionsForOneClient | number | 否 | 否 | 单个客户端的最大连接数。默认最大数量为10。 | 1572 1573## ServerCert<sup>19+</sup> 1574 1575指定服务端证书的信息，包括服务端证书文件路径和服务端证书的私钥文件路径。 1576 1577**系统能力**：SystemCapability.Communication.NetStack 1578 1579| 名称 | 类型 | 只读 | 可选 | 说明 | 1580| ------ | ------ | ---- | --- | ----------------------- | 1581| certPath | string | 否 | 否 | 服务端证书文件路径。 | 1582| keyPath | string | 否 | 否 | 服务端证书的私钥文件路径。| 1583 1584## WebSocketMessage<sup>19+</sup> 1585 1586从指定客户端接收到的消息，包括客户端的信息和数据。 1587 1588**系统能力**：SystemCapability.Communication.NetStack 1589 1590| 名称 | 类型 | 只读 | 可选 | 说明 | 1591| ------ | ------ | ---- | ---- | ------------------------------------------------------- | 1592| data | string \|ArrayBuffer | 否 | 否 | 接收到的客户端发的消息数据。 | 1593| clientConnection | [WebSocketConnection](#websocketconnection19) | 否 | 否 | 客户端信息，包括客户端的ip地址和端口号port。| 1594 1595## WebSocketConnection<sup>19+</sup> 1596 1597客户端信息，包括客户端的ip地址和端口号port。 1598 1599**系统能力**：SystemCapability.Communication.NetStack 1600 1601| 名称 | 类型 | 只读 | 可选 | 说明 | 1602| ------ | ------ | ---- | --- |------------------ | 1603| clientIP | string | 否 | 否 | 客户端的ip地址。 | 1604| clientPort | number | 否 | 否 | 客户端的端口号port。 | 1605 1606## ClientConnectionCloseCallback<sup>19+</sup> 1607 1608type ClientConnectionCloseCallback = (clientConnection: WebSocketConnection, closeReason: CloseResult) => void 1609 1610关闭WebSocketServer连接时，订阅close事件得到的指定客户端的关闭结果。 1611 1612**系统能力**：SystemCapability.Communication.NetStack 1613 1614**参数：** 1615| 参数名 | 类型 | 必填 | 说明 | 1616| ---------------- | ------------------- | ------ | --------------------------------------------- | 1617| clientConnection | [WebSocketConnection](#websocketconnection19) | 是 | 客户端信息，包括客户端的ip地址和端口号port。 | 1618| closeReason | [CloseResult](#closeresult10) | 是 | 关闭WebSocket连接时，订阅close事件得到的关闭结果。 |