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