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