1# @ohos.net.webSocket (WebSocket连接) 2 3> **说明：** 4> 5> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6 7 8使用WebSocket建立服务器与客户端的双向连接，需要先通过[createWebSocket](#websocketcreatewebsocket6)方法创建[WebSocket](#websocket6)对象，然后通过[connect](#connect6)方法连接到服务器。 9当连接成功后，客户端会收到[open](#onopen6)事件的回调，之后客户端就可以通过[send](#send6)方法与服务器进行通信。 10当服务器发信息给客户端时，客户端会收到[message](#onmessage6)事件的回调。当客户端不要此连接时，可以通过调用[close](#close6)方法主动断开连接，之后客户端会收到[close](#onclose6)事件的回调。 11 12若在上述任一过程中发生错误，客户端会收到[error](#onerror6)事件的回调。 13 14## 导入模块 15 16```ts 17import { webSocket } from '@kit.NetworkKit'; 18``` 19 20## 完整示例 21 22```ts 23import { webSocket } from '@kit.NetworkKit'; 24import { BusinessError } from '@kit.BasicServicesKit'; 25 26let defaultIpAddress = "ws://"; 27let ws = webSocket.createWebSocket(); 28ws.on('open', (err:BusinessError, value: Object) => { 29 if (err != undefined) { 30 console.log(JSON.stringify(err)); 31 return; 32 } 33 // 当收到on('open')事件时，可以通过send()方法与服务器进行通信 34 ws.send("Hello, server!", (err: BusinessError, value: boolean) => { 35 if (!err) { 36 console.log("send success"); 37 } else { 38 console.log("send fail, err:" + JSON.stringify(err)); 39 } 40 }); 41}); 42ws.on('message',(error: BusinessError, value: string | ArrayBuffer) => { 43 console.log("on message, message:" + value); 44 // 当收到服务器的`bye`消息时（此消息字段仅为示意，具体字段需要与服务器协商），主动断开连接 45 if (value === 'bye') { 46 ws.close((err: BusinessError, value: boolean) => { 47 if (!err) { 48 console.log("close success"); 49 } else { 50 console.log("close fail, err is " + JSON.stringify(err)); 51 } 52 }); 53 } 54}); 55ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => { 56 console.log("on close, code is " + value.code + ", reason is " + value.reason); 57}); 58ws.on('error', (err: BusinessError) => { 59 console.log("on error, error:" + JSON.stringify(err)); 60}); 61ws.connect(defaultIpAddress, { 62 header:{ 63 name1: 'value1', 64 name2: 'value2', 65 name3: 'value3' 66 }, 67 proxy: { 68 host: '192.168.0.150', 69 port: 8888, 70 exclusionList: [] 71 }, 72 protocol: 'my-protocol', 73 }, (err: BusinessError, value: boolean) => { 74 if (!err) { 75 console.log("connect success"); 76 } else { 77 console.log("connect fail, err:" + JSON.stringify(err)); 78 } 79 ws.close((err: BusinessError) => { 80 if (!err) { 81 console.log("close success"); 82 } else { 83 console.log("close fail, err is " + JSON.stringify(err)); 84 } 85 }); 86}); 87``` 88 89## webSocket.createWebSocket<sup>6+</sup> 90 91createWebSocket(): WebSocket 92 93创建一个WebSocket，里面包括建立连接、关闭连接、发送数据和订阅/取消订阅WebSocket连接的打开事件、接收到服务器消息事件、关闭事件和错误事件。 94 95**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 96 97**系统能力**：SystemCapability.Communication.NetStack 98 99**返回值：** 100 101| 类型 | 说明 | 102| :---------------------------------- | :----------------------------------------------------------- | 103| [WebSocket](#websocket6) | 返回一个WebSocket对象，里面包括connect、send、close、on和off方法。 | 104 105**示例：** 106 107```ts 108let ws: webSocket.WebSocket = webSocket.createWebSocket(); 109``` 110 111## WebSocket<sup>6+</sup> 112 113在调用WebSocket的方法前，需要先通过[webSocket.createWebSocket](#websocketcreatewebsocket6)创建一个WebSocket。 114 115### connect<sup>6+</sup> 116 117connect(url: string, callback: AsyncCallback\<boolean\>): void 118 119根据URL地址，建立一个WebSocket连接，使用callback方式作为异步方法。 120 121> **说明：** 122> 可通过监听error事件获得该接口的执行结果，错误发生时会得到错误码：200。 123 124**需要权限**：ohos.permission.INTERNET 125 126**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 127 128**系统能力**：SystemCapability.Communication.NetStack 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| -------- | ------------------------ | ---- | ---------------------------- | 134| url | string | 是 | 建立WebSocket连接的URL地址。 | 135| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 136 137**错误码：** 138 139| 错误码ID | 错误信息 | 140| --------------------- | ------------------------------------------ | 141| 401 | Parameter error. | 142| 201 | Permission denied. | 143| 2302001<sup>12+</sup> | Websocket url error. | 144| 2302002<sup>12+</sup> | Websocket certificate file does not exist. | 145| 2302003<sup>12+</sup> | Websocket connection already exists. | 146| 2302998<sup>12+</sup> | It is not allowed to access this domain. | 147| 2302999<sup>10+</sup> | Websocket other unknown error. | 148 149> **错误码说明：** 150> 以上错误码的详细介绍参见[webSocket错误码](errorcode-net-webSocket.md)。 151 152**示例：** 153 154```ts 155import { webSocket } from '@kit.NetworkKit'; 156import { BusinessError } from '@kit.BasicServicesKit'; 157 158let ws = webSocket.createWebSocket(); 159let url = "ws://"; 160ws.connect(url, (err: BusinessError, value: boolean) => { 161 if (!err) { 162 console.log("connect success"); 163 } else { 164 console.log("connect fail, err:" + JSON.stringify(err)); 165 } 166}); 167``` 168 169### connect<sup>6+</sup> 170 171connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback\<boolean\>): void 172 173根据URL地址和header，建立一个WebSocket连接，使用callback方式作为异步方法。 174 175> **说明：** 176> 可通过监听error事件获得该接口的执行结果，错误发生时会得到错误码：200。 177 178**需要权限**：ohos.permission.INTERNET 179 180**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 181 182**系统能力**：SystemCapability.Communication.NetStack 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| -------- | ------------------------ | ---- | ------------------------------------------------------- | 188| url | string | 是 | 建立WebSocket连接的URL地址。 | 189| options | WebSocketRequestOptions | 是 | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 | 190| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 191 192**错误码：** 193 194| 错误码ID | 错误信息 | 195| --------------------- | ------------------------------------------ | 196| 401 | Parameter error. | 197| 201 | Permission denied. | 198| 2302001<sup>12+</sup> | Websocket url error. | 199| 2302002<sup>12+</sup> | Websocket certificate file does not exist. | 200| 2302003<sup>12+</sup> | Websocket connection already exists. | 201| 2302998<sup>12+</sup> | It is not allowed to access this domain. | 202| 2302999<sup>10+</sup> | Websocket other unknown error. | 203 204> **错误码说明：** 205> 以上错误码的详细介绍参见[webSocket错误码](errorcode-net-webSocket.md)。 206 207**示例：** 208 209```ts 210import { webSocket } from '@kit.NetworkKit'; 211import { BusinessError } from '@kit.BasicServicesKit'; 212 213let ws = webSocket.createWebSocket(); 214let options: webSocket.WebSocketRequestOptions | undefined; 215if (options !=undefined) { 216 options.header = { 217 name1: "value1", 218 name2: "value2", 219 name3: "value3" 220 }; 221 options.caPath = ""; 222} 223let url = "ws://" 224ws.connect(url, options, (err: BusinessError, value: Object) => { 225 if (!err) { 226 console.log("connect success"); 227 } else { 228 console.log("connect fail, err:" + JSON.stringify(err)) 229 } 230}); 231``` 232 233### connect<sup>6+</sup> 234 235connect(url: string, options?: WebSocketRequestOptions): Promise\<boolean\> 236 237根据URL地址和header，建立一个WebSocket连接，使用Promise方式作为异步方法。 238 239> **说明：** 240> 可通过监听error事件获得该接口的执行结果，错误发生时会得到错误码：200。 241 242**需要权限**：ohos.permission.INTERNET 243 244**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 245 246**系统能力**：SystemCapability.Communication.NetStack 247 248**参数：** 249 250| 参数名 | 类型 | 必填 | 说明 | 251| ------- | ----------------------- | ---- | ------------------------------------------------------- | 252| url | string | 是 | 建立WebSocket连接的URL地址。 | 253| options | WebSocketRequestOptions | 否 | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 | 254 255**返回值：** 256 257| 类型 | 说明 | 258| :----------------- | :-------------------------------- | 259| Promise\<boolean\> | 以Promise形式返回建立连接的结果。 | 260 261**错误码：** 262 263| 错误码ID | 错误信息 | 264| --------------------- | ------------------------------------------ | 265| 401 | Parameter error. | 266| 201 | Permission denied. | 267| 2302001<sup>12+</sup> | Websocket url error. | 268| 2302002<sup>12+</sup> | Websocket certificate file does not exist. | 269| 2302003<sup>12+</sup> | Websocket connection already exists. | 270| 2302998<sup>12+</sup> | It is not allowed to access this domain. | 271| 2302999<sup>10+</sup> | Websocket other unknown error. | 272 273> **错误码说明：** 274> 以上错误码的详细介绍参见[webSocket错误码](errorcode-net-webSocket.md)。 275 276**示例：** 277 278```ts 279import { webSocket } from '@kit.NetworkKit'; 280 281let ws = webSocket.createWebSocket(); 282let url = "ws://" 283let promise = ws.connect(url); 284promise.then((value: boolean) => { 285 console.log("connect success") 286}).catch((err:string) => { 287 console.log("connect fail, error:" + JSON.stringify(err)) 288}); 289``` 290 291### send<sup>6+</sup> 292 293send(data: string | ArrayBuffer, callback: AsyncCallback\<boolean\>): void 294 295通过WebSocket连接发送数据，使用callback方式作为异步方法。 296 297**需要权限**：ohos.permission.INTERNET 298 299**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 300 301**系统能力**：SystemCapability.Communication.NetStack 302 303**参数：** 304 305| 参数名 | 类型 | 必填 | 说明 | 306| -------- | ------------------------ | ---- | ------------ | 307| data | string \| ArrayBuffer | 是 | 发送的数据。<br>API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。 | 308| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 309 310**错误码：** 311 312| 错误码ID | 错误信息 | 313| ------- | ----------------------- | 314| 401 | Parameter error. | 315| 201 | Permission denied. | 316 317**示例：** 318 319```ts 320import { webSocket } from '@kit.NetworkKit'; 321import { BusinessError } from '@kit.BasicServicesKit'; 322 323let ws = webSocket.createWebSocket(); 324let url = "ws://" 325class OutValue { 326 status: number = 0 327 message: string = "" 328} 329ws.connect(url, (err: BusinessError, value: boolean) => { 330 if (!err) { 331 console.log("connect success"); 332 } else { 333 console.log("connect fail, err:" + JSON.stringify(err)) 334 } 335}); 336ws.on('open', (err: BusinessError, value: Object) => { 337 console.log("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message); 338 ws.send("Hello, server!", (err: BusinessError, value: boolean) => { 339 if (!err) { 340 console.log("send success"); 341 } else { 342 console.log("send fail, err:" + JSON.stringify(err)) 343 } 344 }); 345}); 346``` 347 348> **说明** 349> 350> send接口必须在监听到open事件后才可以调用。 351 352### send<sup>6+</sup> 353 354send(data: string | ArrayBuffer): Promise\<boolean\> 355 356通过WebSocket连接发送数据，使用Promise方式作为异步方法。 357 358**需要权限**：ohos.permission.INTERNET 359 360**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 361 362**系统能力**：SystemCapability.Communication.NetStack 363 364**参数：** 365 366| 参数名 | 类型 | 必填 | 说明 | 367| ------ | ------ | ---- | ------------ | 368| data | string \| ArrayBuffer | 是 | 发送的数据。<br>API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。 | 369 370**返回值：** 371 372| 类型 | 说明 | 373| :----------------- | :-------------------------------- | 374| Promise\<boolean\> | 以Promise形式返回发送数据的结果。 | 375 376**错误码：** 377 378| 错误码ID | 错误信息 | 379| ------- | ----------------------- | 380| 401 | Parameter error. | 381| 201 | Permission denied. | 382 383**示例：** 384 385```ts 386import { webSocket } from '@kit.NetworkKit'; 387import { BusinessError } from '@kit.BasicServicesKit'; 388 389let ws = webSocket.createWebSocket(); 390let url = "ws://" 391class OutValue { 392 status: number = 0 393 message: string = "" 394} 395ws.connect(url, (err: BusinessError, value: boolean) => { 396 if (!err) { 397 console.log("connect success"); 398 } else { 399 console.log("connect fail, err:" + JSON.stringify(err)) 400 } 401}); 402 403ws.on('open', (err: BusinessError, value: Object) => { 404 console.log("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message); 405 let promise = ws.send("Hello, server!"); 406 promise.then((value: boolean) => { 407 console.log("send success") 408 }).catch((err:string) => { 409 console.log("send fail, error:" + JSON.stringify(err)) 410 }); 411}); 412``` 413 414> **说明** 415> 416> send接口必须在监听到open事件后才可以调用。 417 418### close<sup>6+</sup> 419 420close(callback: AsyncCallback\<boolean\>): void 421 422关闭WebSocket连接，使用callback方式作为异步方法。 423 424**需要权限**：ohos.permission.INTERNET 425 426**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 427 428**系统能力**：SystemCapability.Communication.NetStack 429 430**参数：** 431 432| 参数名 | 类型 | 必填 | 说明 | 433| -------- | ------------------------ | ---- | ---------- | 434| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 435 436**错误码：** 437 438| 错误码ID | 错误信息 | 439| ------- | ----------------------- | 440| 401 | Parameter error. | 441| 201 | Permission denied. | 442 443**示例：** 444 445```ts 446import { webSocket } from '@kit.NetworkKit'; 447import { BusinessError } from '@kit.BasicServicesKit'; 448 449let ws = webSocket.createWebSocket(); 450ws.close((err: BusinessError) => { 451 if (!err) { 452 console.log("close success") 453 } else { 454 console.log("close fail, err is " + JSON.stringify(err)) 455 } 456}); 457``` 458 459### close<sup>6+</sup> 460 461close(options: WebSocketCloseOptions, callback: AsyncCallback\<boolean\>): void 462 463根据可选参数code和reason，关闭WebSocket连接，使用callback方式作为异步方法。 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| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 477 478**错误码：** 479 480| 错误码ID | 错误信息 | 481| ------- | ----------------------- | 482| 401 | Parameter error. | 483| 201 | Permission denied. | 484 485**示例：** 486 487```ts 488import { webSocket } from '@kit.NetworkKit'; 489import { BusinessError } from '@kit.BasicServicesKit'; 490 491let ws = webSocket.createWebSocket(); 492 493let options: webSocket.WebSocketCloseOptions | undefined; 494if (options != undefined) { 495 options.code = 1000 496 options.reason = "your reason" 497} 498ws.close(options, (err: BusinessError) => { 499 if (!err) { 500 console.log("close success") 501 } else { 502 console.log("close fail, err is " + JSON.stringify(err)) 503 } 504}); 505``` 506 507### close<sup>6+</sup> 508 509close(options?: WebSocketCloseOptions): Promise\<boolean\> 510 511根据可选参数code和reason，关闭WebSocket连接，使用Promise方式作为异步方法。 512 513**需要权限**：ohos.permission.INTERNET 514 515**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 516 517**系统能力**：SystemCapability.Communication.NetStack 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522| ------- | --------------------- | ---- | ----------------------------------------------------- | 523| options | WebSocketCloseOptions | 否 | 参考[WebSocketCloseOptions](#websocketcloseoptions)。 | 524 525**返回值：** 526 527| 类型 | 说明 | 528| :----------------- | :-------------------------------- | 529| Promise\<boolean\> | 以Promise形式返回关闭连接的结果。 | 530 531**错误码：** 532 533| 错误码ID | 错误信息 | 534| ------- | ----------------------- | 535| 401 | Parameter error. | 536| 201 | Permission denied. | 537 538**示例：** 539 540```ts 541import { webSocket } from '@kit.NetworkKit'; 542 543let ws = webSocket.createWebSocket(); 544let options: webSocket.WebSocketCloseOptions | undefined; 545if (options != undefined) { 546 options.code = 1000 547 options.reason = "your reason" 548} 549let promise = ws.close(); 550promise.then((value: boolean) => { 551 console.log("close success") 552}).catch((err:string) => { 553 console.log("close fail, err is " + JSON.stringify(err)) 554}); 555``` 556 557### on('open')<sup>6+</sup> 558 559on(type: 'open', callback: AsyncCallback\<Object\>): void 560 561订阅WebSocket的打开事件，使用callback方式作为异步方法。 562 563**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 564 565**系统能力**：SystemCapability.Communication.NetStack 566 567**参数：** 568 569| 参数名 | 类型 | 必填 | 说明 | 570| -------- | ----------------------- | ---- | ----------------------------- | 571| type | string | 是 | 'open'：WebSocket的打开事件。 | 572| callback | AsyncCallback\<Object\> | 是 | 回调函数。 | 573 574**示例：** 575 576```ts 577import { webSocket } from '@kit.NetworkKit'; 578import { BusinessError, Callback } from '@kit.BasicServicesKit'; 579 580let ws= webSocket.createWebSocket(); 581class OutValue { 582 status: number = 0 583 message: string = "" 584} 585ws.on('open', (err: BusinessError, value: Object) => { 586 console.log("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message); 587}); 588``` 589 590### off('open')<sup>6+</sup> 591 592off(type: 'open', callback?: AsyncCallback\<Object\>): void 593 594取消订阅WebSocket的打开事件，使用callback方式作为异步方法。 595 596> **说明：** 597> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 598 599**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 600 601**系统能力**：SystemCapability.Communication.NetStack 602 603**参数：** 604 605| 参数名 | 类型 | 必填 | 说明 | 606| -------- | ----------------------- | ---- | ----------------------------- | 607| type | string | 是 | 'open'：WebSocket的打开事件。 | 608| callback | AsyncCallback\<Object\> | 否 | 回调函数。 | 609 610**示例：** 611 612```ts 613import { webSocket } from '@kit.NetworkKit'; 614import { BusinessError } from '@kit.BasicServicesKit'; 615 616let ws = webSocket.createWebSocket(); 617class OutValue { 618 status: number = 0 619 message: string = "" 620} 621let callback1 = (err: BusinessError, value: Object) => { 622 console.log("on open, status:" + ((value as OutValue).status + ", message:" + (value as OutValue).message)); 623} 624ws.on('open', callback1); 625// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅 626ws.off('open', callback1); 627``` 628 629### on('message')<sup>6+</sup> 630 631on(type: 'message', callback: AsyncCallback\<string | ArrayBuffer\>): void 632 633订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。每个消息最大长度为4K，超过4K自动分片。 634 635> **说明：** 636> AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。 637 638**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 639 640**系统能力**：SystemCapability.Communication.NetStack 641 642**参数：** 643 644| 参数名 | 类型 | 必填 | 说明 | 645| -------- | ----------------------- | ---- | -------------------------------------------- | 646| type | string | 是 | 'message'：WebSocket的接收到服务器消息事件。 | 647| callback | AsyncCallback\<string \| ArrayBuffer <sup>8+</sup>\> | 是 | 回调函数。 | 648 649**示例：** 650 651```ts 652import { webSocket } from '@kit.NetworkKit'; 653import { BusinessError } from '@kit.BasicServicesKit'; 654 655let ws = webSocket.createWebSocket(); 656ws.on('message', (err: BusinessError<void>, value: string | ArrayBuffer) => { 657 console.log("on message, message:" + value); 658}); 659``` 660 661### off('message')<sup>6+</sup> 662 663off(type: 'message', callback?: AsyncCallback\<string | ArrayBuffer\>): void 664 665取消订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。每个消息最大长度为4K，超过4K自动分片。 666 667> **说明：** 668> AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。 669> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 670 671**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 672 673**系统能力**：SystemCapability.Communication.NetStack 674 675**参数：** 676 677| 参数名 | 类型 | 必填 | 说明 | 678| -------- | --------------------------------------------------- | ---- | -------------------------------------------- | 679| type | string | 是 | 'message'：WebSocket的接收到服务器消息事件。 | 680| callback | AsyncCallback\<string \|ArrayBuffer <sup>8+</sup>\> | 否 | 回调函数。 | 681 682**示例：** 683 684```ts 685import { webSocket } from '@kit.NetworkKit'; 686 687let ws = webSocket.createWebSocket(); 688ws.off('message'); 689``` 690 691### on('close')<sup>6+</sup> 692 693on(type: 'close', callback: AsyncCallback\<CloseResult\>): void 694 695订阅WebSocket的关闭事件，使用callback方式作为异步方法。 696 697**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 698 699**系统能力**：SystemCapability.Communication.NetStack 700 701**参数：** 702 703| 参数名 | 类型 | 必填 | 说明 | 704| -------- | ----------------------------------------------- | ---- | ------------------------------ | 705| type | string | 是 | 'close'：WebSocket的关闭事件。 | 706| callback | AsyncCallback\<CloseResult\> | 是 | 回调函数。<br>close：close错误码，reason：错误码说明 | 707 708**示例：** 709 710```ts 711import { webSocket } from '@kit.NetworkKit'; 712import { BusinessError } from '@kit.BasicServicesKit'; 713 714let ws = webSocket.createWebSocket(); 715ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => { 716 console.log("on close, code is " + value.code + ", reason is " + value.reason); 717}); 718``` 719 720### off('close')<sup>6+</sup> 721 722off(type: 'close', callback?: AsyncCallback\<CloseResult\>): void 723 724取消订阅WebSocket的关闭事件，使用callback方式作为异步方法。 725 726> **说明：** 727> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 728 729**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 730 731**系统能力**：SystemCapability.Communication.NetStack 732 733**参数：** 734 735| 参数名 | 类型 | 必填 | 说明 | 736| -------- | ----------------------------------------------- | ---- | ------------------------------ | 737| type | string | 是 | 'close'：WebSocket的关闭事件。 | 738| callback | AsyncCallback\<CloseResult\> | 否 | 回调函数。<br>close：close错误码，reason：错误码说明 | 739 740**示例：** 741 742```ts 743import { webSocket } from '@kit.NetworkKit'; 744 745let ws = webSocket.createWebSocket(); 746ws.off('close'); 747``` 748 749### on('error')<sup>6+</sup> 750 751on(type: 'error', callback: ErrorCallback): void 752 753订阅WebSocket的Error事件，使用callback方式作为异步方法。 754 755**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 756 757**系统能力**：SystemCapability.Communication.NetStack 758 759**参数：** 760 761| 参数名 | 类型 | 必填 | 说明 | 762| -------- | ------------- | ---- | ------------------------------- | 763| type | string | 是 | 'error'：WebSocket的Error事件。 | 764| callback | ErrorCallback | 是 | 回调函数。<br>常见错误码：200 | 765 766**示例：** 767 768```ts 769import { webSocket } from '@kit.NetworkKit'; 770import { BusinessError } from '@kit.BasicServicesKit'; 771 772let ws = webSocket.createWebSocket(); 773ws.on('error', (err: BusinessError) => { 774 console.log("on error, error:" + JSON.stringify(err)) 775}); 776``` 777 778### off('error')<sup>6+</sup> 779 780off(type: 'error', callback?: ErrorCallback): void 781 782取消订阅WebSocket的Error事件，使用callback方式作为异步方法。 783 784> **说明：** 785> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 786 787**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 788 789**系统能力**：SystemCapability.Communication.NetStack 790 791**参数：** 792 793| 参数名 | 类型 | 必填 | 说明 | 794| -------- | ------------- | ---- | ------------------------------- | 795| type | string | 是 | 'error'：WebSocket的Error事件。 | 796| callback | ErrorCallback | 否 | 回调函数。 | 797 798**示例：** 799 800```ts 801import { webSocket } from '@kit.NetworkKit'; 802 803let ws = webSocket.createWebSocket(); 804ws.off('error'); 805``` 806 807### on('dataEnd')<sup>11+</sup> 808 809on(type: 'dataEnd', callback: Callback\<void\>): void 810 811订阅WebSocket的数据接收结束事件，使用callback方式作为异步方法。 812 813**系统能力**：SystemCapability.Communication.NetStack 814 815**参数：** 816 817| 参数名 | 类型 | 必填 | 说明 | 818| -------- | ---------------- | ---- | --------------------------------------- | 819| type | string | 是 | 'dataEnd'：WebSocket的数据接收结束事件。 | 820| callback | Callback\<void\> | 是 | 回调函数。 | 821 822**示例：** 823 824```ts 825import { webSocket } from '@kit.NetworkKit'; 826 827let ws = webSocket.createWebSocket(); 828ws.on('dataEnd', () => { 829 console.log("on dataEnd") 830}); 831``` 832 833### off('dataEnd')<sup>11+</sup> 834 835off(type: 'dataEnd', callback?: Callback\<void\>): void 836 837取消订阅WebSocket的数据接收结束事件，使用callback方式作为异步方法。 838 839> **说明：** 840> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 841 842**系统能力**：SystemCapability.Communication.NetStack 843 844**参数：** 845 846| 参数名 | 类型 | 必填 | 说明 | 847| -------- | ---------------- | ---- | -------------------------------------- | 848| type | string | 是 | 'dataEnd'：WebSocket的数据接收结束事件。| 849| callback | Callback\<void\> | 否 | 回调函数。 | 850 851**示例：** 852 853```ts 854import { webSocket } from '@kit.NetworkKit'; 855 856let ws = webSocket.createWebSocket(); 857ws.off('dataEnd'); 858``` 859 860### on('headerReceive')<sup>12+</sup> 861 862on(type: 'headerReceive', callback: Callback\<ResponseHeaders\>): void 863 864订阅HTTP Response Header事件，使用callback方式作为同步方法。 865 866**系统能力**：SystemCapability.Communication.NetStack 867 868**参数：** 869 870| 参数名 | 类型 | 必填 | 说明 | 871| -------- | ---------------- | ---- | -------------------------------------- | 872| type | string | 是 | 'headerReceive'：WebSocket的headerReceive事件。| 873| callback | Callback\<ResponseHeaders\> | 是 | 回调函数,返回订阅事件。 | 874 875**示例：** 876 877```ts 878import { webSocket } from '@kit.NetworkKit'; 879 880let ws = webSocket.createWebSocket(); 881ws.on('headerReceive', (data) => { 882 console.log("on headerReceive " + JSON.stringify(data)); 883}); 884``` 885 886### off('headerReceive')<sup>12+</sup> 887 888off(type: 'headerReceive', callback?: Callback\<ResponseHeaders\>): void 889 890取消订阅HTTP Response Header事件，使用callback方式作为同步方法。 891 892> **说明：** 893> 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 894 895**系统能力**：SystemCapability.Communication.NetStack 896 897**参数：** 898 899| 参数名 | 类型 | 必填 | 说明 | 900| -------- | ---------------- | ---- | -------------------------------------- | 901| type | string | 是 | 'headerReceive'：WebSocket的headerReceive事件。| 902| callback | Callback\<ResponseHeaders\> | 否 | 回调函数,返回订阅事件。 | 903 904**示例：** 905 906```ts 907import { webSocket } from '@kit.NetworkKit'; 908 909let ws = webSocket.createWebSocket(); 910ws.off('headerReceive'); 911``` 912 913## WebSocketRequestOptions 914 915建立WebSocket连接时，可选参数的类型和说明。 916 917**系统能力**：SystemCapability.Communication.NetStack 918 919| 名称 | 类型 | 只读 | 可选 | 说明 | 920| ------ | ------ |------ | ---- | ------------------------------------------------------------ | 921| header | Object | 否 | 是 | 建立WebSocket连接可选参数，代表建立连接时携带的HTTP头信息。参数内容自定义，也可以不指定。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 922| caPath<sup>11+</sup> | string | 否 | 是 | 如果设置了此参数，系统将使用用户指定路径的CA证书，(开发者需保证该路径下CA证书的可访问性)，否则将使用系统预设CA证书，系统预设CA证书位置：/etc/ssl/certs/cacert.pem。证书路径为沙箱映射路径（开发者可通过Global.getContext().filesDir获取应用沙箱路径）。目前仅支持格式为pem的文本证书。 | 923| clientCert<sup>11+</sup> | [ClientCert](#clientcert11) | 否 | 是 | 支持传输客户端证书。 | 924| proxy<sup>12+</sup> | ProxyConfiguration | 否 | 是 | 通信过程中的代理信息，默认使用系统网络代理。 | 925| protocol<sup>12+</sup> | string | 否 | 是 | 自定义Sec-WebSocket-Protocol字段，默认为""。 | 926 927## ClientCert<sup>11+</sup> 928 929客户端证书类型。 930 931**系统能力**：SystemCapability.Communication.NetStack 932 933| 名称 | 类型 | 必填 | 说明 | 934| ------ | ------ | ---- | ------------------------------------------------------------ | 935| certPath | string | 是 | 证书路径。 | 936| keyPath | string | 是 | 证书秘钥的路径。 | 937| keyPassword | string | 否 | 证书秘钥的密码。 | 938 939## ProxyConfiguration<sup>12+</sup> 940type ProxyConfiguration = 'system' | 'no-proxy' | HttpProxy 941 942网络代理配置信息 943 944**系统能力**：SystemCapability.Communication.NetStack 945 946| 类型 | 说明 | 947| ------ |------------------------- | 948| 'system' | 使用系统默认网络代理。 | 949| 'no-proxy' | 不使用网络代理。 | 950| [HttpProxy](js-apis-net-connection.md#httpproxy10) | 使用指定的网络代理。 | 951 952## WebSocketCloseOptions 953 954关闭WebSocket连接时，可选参数的类型和说明。 955 956**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 957 958**系统能力**：SystemCapability.Communication.NetStack 959 960| 名称 | 类型 | 必填 | 说明 | 961| ------ | ------ | ---- | ------------------------------------------------------------ | 962| code | number | 否 | 错误码，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为1000。 | 963| reason | string | 否 | 原因值，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为空字符串（""）。 | 964 965## CloseResult<sup>10+</sup> 966 967关闭WebSocket连接时，订阅close事件得到的关闭结果。 968 969**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 970 971**系统能力**：SystemCapability.Communication.NetStack 972 973| 名称 | 类型 | 必填 | 说明 | 974| ------ | ------ | ---- | ------------------------------------------------------------ | 975| code | number | 是 | 错误码，订阅close事件得到的关闭连接的错误码。 | 976| reason | string | 是 | 原因值，订阅close事件得到的关闭连接的错误原因。 | 977 978## ResponseHeaders<sup>12+</sup> 979type ResponseHeaders = {[k: string]: string | string[] | undefined;} 980 981服务器发送的响应头。 982 983**系统能力**：SystemCapability.Communication.NetStack 984 985| 类型 | 说明 | 986| ------ | ------------------------------------------------------------ | 987| {[k:string]:string \| string[] \| undefined} | header数据类型为键值对、字符串或者undefined | 988 989## close错误码说明 990 991发送给服务端的错误码可以自行定义，下面的列表仅供参考。 992 993**系统能力**：SystemCapability.Communication.NetStack 994 995| 值 | 说明 | 996| :-------- | :----------------- | 997| 1000 | 正常关闭 | 998| 1001 | 服务器主动关闭 | 999| 1002 | 协议错误 | 1000| 1003 | 无法处理的数据类型 | 1001| 1004~1015 | 保留值 | 1002