1# @ohos.net.webSocket (WebSocket连接) 2 3> **说明：** 4> 5> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6 7 8使用WebSocket建立服务器与客户端的双向连接，需要先通过[createWebSocket](#websocketcreatewebsocket)方法创建[WebSocket](#websocket)对象，然后通过[connect](#connect)方法连接到服务器。当连接成功后，客户端会收到[open](#onopen)事件的回调，之后客户端就可以通过[send](#send)方法与服务器进行通信。当服务器发信息给客户端时，客户端会收到[message](#onmessage)事件的回调。当客户端不要此连接时，可以通过调用[close](#close)方法主动断开连接，之后客户端会收到[close](#onclose)事件的回调。 9 10若在上述任一过程中发生错误，客户端会收到[error](#onerror)事件的回调。 11 12 13## 导入模块 14 15```js 16import webSocket from '@ohos.net.webSocket'; 17``` 18 19## 完整示例 20 21```js 22import webSocket from '@ohos.net.webSocket'; 23 24var defaultIpAddress = "ws://"; 25let ws = webSocket.createWebSocket(); 26ws.on('open', (err, value) => { 27 console.log("on open, status:" + value['status'] + ", message:" + value['message']); 28 // 当收到on('open')事件时，可以通过send()方法与服务器进行通信 29 ws.send("Hello, server!", (err, value) => { 30 if (!err) { 31 console.log("send success"); 32 } else { 33 console.log("send fail, err:" + JSON.stringify(err)); 34 } 35 }); 36}); 37ws.on('message', (err, value) => { 38 console.log("on message, message:" + value); 39 // 当收到服务器的`bye`消息时（此消息字段仅为示意，具体字段需要与服务器协商），主动断开连接 40 if (value === 'bye') { 41 ws.close((err, value) => { 42 if (!err) { 43 console.log("close success"); 44 } else { 45 console.log("close fail, err is " + JSON.stringify(err)); 46 } 47 }); 48 } 49}); 50ws.on('close', (err, value) => { 51 console.log("on close, code is " + value.code + ", reason is " + value.reason); 52}); 53ws.on('error', (err) => { 54 console.log("on error, error:" + JSON.stringify(err)); 55}); 56ws.connect(defaultIpAddress, (err, value) => { 57 if (!err) { 58 console.log("connect success"); 59 } else { 60 console.log("connect fail, err:" + JSON.stringify(err)); 61 } 62}); 63``` 64 65## webSocket.createWebSocket 66 67createWebSocket(): WebSocket 68 69创建一个WebSocket，里面包括建立连接、关闭连接、发送数据和订阅/取消订阅WebSocket连接的打开事件、接收到服务器消息事件、关闭事件和错误事件。 70 71**系统能力**：SystemCapability.Communication.NetStack 72 73**返回值：** 74 75| 类型 | 说明 | 76| :---------------------------------- | :----------------------------------------------------------- | 77| [WebSocket](#websocket) | 返回一个WebSocket对象，里面包括connect、send、close、on和off方法。 | 78 79**示例：** 80 81```js 82let ws = webSocket.createWebSocket(); 83``` 84 85 86## WebSocket 87 88在调用WebSocket的方法前，需要先通过[webSocket.createWebSocket](#websocketcreatewebsocket)创建一个WebSocket。 89 90### connect 91 92connect(url: string, callback: AsyncCallback\<boolean\>): void 93 94根据URL地址，建立一个WebSocket连接，使用callback方式作为异步方法。 95 96**需要权限**：ohos.permission.INTERNET 97 98**系统能力**：SystemCapability.Communication.NetStack 99 100**参数：** 101 102| 参数名 | 类型 | 必填 | 说明 | 103| -------- | ------------------------ | ---- | ---------------------------- | 104| url | string | 是 | 建立WebSocket连接的URL地址。 | 105| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 106 107**错误码：** 108 109| 错误码ID | 错误信息 | 110| ------- | ----------------------- | 111| 401 | Parameter error. | 112| 201 | Permission denied. | 113 114**示例：** 115 116```js 117let ws = webSocket.createWebSocket(); 118let url = "ws://" 119ws.connect(url, (err, value) => { 120 if (!err) { 121 console.log("connect success"); 122 } else { 123 console.log("connect fail, err:" + JSON.stringify(err)) 124 } 125}); 126``` 127 128 129### connect 130 131connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback\<boolean\>): void 132 133根据URL地址和header，建立一个WebSocket连接，使用callback方式作为异步方法。 134 135**需要权限**：ohos.permission.INTERNET 136 137**系统能力**：SystemCapability.Communication.NetStack 138 139**参数：** 140 141| 参数名 | 类型 | 必填 | 说明 | 142| -------- | ------------------------ | ---- | ------------------------------------------------------- | 143| url | string | 是 | 建立WebSocket连接的URL地址。 | 144| options | WebSocketRequestOptions | 是 | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 | 145| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 146 147**错误码：** 148 149| 错误码ID | 错误信息 | 150| ------- | ----------------------- | 151| 401 | Parameter error. | 152| 201 | Permission denied. | 153 154**示例：** 155 156```js 157let ws = webSocket.createWebSocket(); 158let url = "ws://" 159ws.connect(url, { 160 header: { 161 "key": "value", 162 "key2": "value2" 163 } 164}, (err, value) => { 165 if (!err) { 166 console.log("connect success"); 167 } else { 168 console.log("connect fail, err:" + JSON.stringify(err)) 169 } 170}); 171``` 172 173 174### connect 175 176connect(url: string, options?: WebSocketRequestOptions): Promise\<boolean\> 177 178根据URL地址和header，建立一个WebSocket连接，使用Promise方式作为异步方法。 179 180**需要权限**：ohos.permission.INTERNET 181 182**系统能力**：SystemCapability.Communication.NetStack 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| ------- | ----------------------- | ---- | ------------------------------------------------------- | 188| url | string | 是 | 建立WebSocket连接的URL地址。 | 189| options | WebSocketRequestOptions | 否 | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 | 190 191**返回值：** 192 193| 类型 | 说明 | 194| :----------------- | :-------------------------------- | 195| Promise\<boolean\> | 以Promise形式返回建立连接的结果。 | 196 197**错误码：** 198 199| 错误码ID | 错误信息 | 200| ------- | ----------------------- | 201| 401 | Parameter error. | 202| 201 | Permission denied. | 203 204**示例：** 205 206```js 207let ws = webSocket.createWebSocket(); 208let url = "ws://" 209let promise = ws.connect(url); 210promise.then((value) => { 211 console.log("connect success") 212}).catch((err) => { 213 console.log("connect fail, error:" + JSON.stringify(err)) 214}); 215``` 216 217 218### send 219 220send(data: string | ArrayBuffer, callback: AsyncCallback\<boolean\>): void 221 222通过WebSocket连接发送数据，使用callback方式作为异步方法。 223 224**需要权限**：ohos.permission.INTERNET 225 226**系统能力**：SystemCapability.Communication.NetStack 227 228**参数：** 229 230| 参数名 | 类型 | 必填 | 说明 | 231| -------- | ------------------------ | ---- | ------------ | 232| data | string \| ArrayBuffer | 是 | 发送的数据。<br>API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。 | 233| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 234 235**错误码：** 236 237| 错误码ID | 错误信息 | 238| ------- | ----------------------- | 239| 401 | Parameter error. | 240| 201 | Permission denied. | 241 242**示例：** 243 244```js 245let ws = webSocket.createWebSocket(); 246let url = "ws://" 247ws.connect(url, (err, value) => { 248 ws.send("Hello, server!", (err, value) => { 249 if (!err) { 250 console.log("send success"); 251 } else { 252 console.log("send fail, err:" + JSON.stringify(err)) 253 } 254 }); 255}); 256``` 257 258 259### send 260 261send(data: string | ArrayBuffer): Promise\<boolean\> 262 263通过WebSocket连接发送数据，使用Promise方式作为异步方法。 264 265**需要权限**：ohos.permission.INTERNET 266 267**系统能力**：SystemCapability.Communication.NetStack 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| ------ | ------ | ---- | ------------ | 273| data | string \| ArrayBuffer | 是 | 发送的数据。<br>API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。 | 274 275**返回值：** 276 277| 类型 | 说明 | 278| :----------------- | :-------------------------------- | 279| Promise\<boolean\> | 以Promise形式返回发送数据的结果。 | 280 281**错误码：** 282 283| 错误码ID | 错误信息 | 284| ------- | ----------------------- | 285| 401 | Parameter error. | 286| 201 | Permission denied. | 287 288**示例：** 289 290```js 291let ws = webSocket.createWebSocket(); 292let url = "ws://" 293ws.connect(url, (err, value) => { 294 let promise = ws.send("Hello, server!"); 295 promise.then((value) => { 296 console.log("send success") 297 }).catch((err) => { 298 console.log("send fail, error:" + JSON.stringify(err)) 299 }); 300}); 301``` 302 303 304### close 305 306close(callback: AsyncCallback\<boolean\>): void 307 308关闭WebSocket连接，使用callback方式作为异步方法。 309 310**需要权限**：ohos.permission.INTERNET 311 312**系统能力**：SystemCapability.Communication.NetStack 313 314**参数：** 315 316| 参数名 | 类型 | 必填 | 说明 | 317| -------- | ------------------------ | ---- | ---------- | 318| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 319 320**错误码：** 321 322| 错误码ID | 错误信息 | 323| ------- | ----------------------- | 324| 401 | Parameter error. | 325| 201 | Permission denied. | 326 327**示例：** 328 329```js 330let ws = webSocket.createWebSocket(); 331let url = "ws://" 332ws.close((err, value) => { 333 if (!err) { 334 console.log("close success") 335 } else { 336 console.log("close fail, err is " + JSON.stringify(err)) 337 } 338}); 339``` 340 341 342### close 343 344close(options: WebSocketCloseOptions, callback: AsyncCallback\<boolean\>): void 345 346根据可选参数code和reason，关闭WebSocket连接，使用callback方式作为异步方法。 347 348**需要权限**：ohos.permission.INTERNET 349 350**系统能力**：SystemCapability.Communication.NetStack 351 352**参数：** 353 354| 参数名 | 类型 | 必填 | 说明 | 355| -------- | ------------------------ | ---- | ----------------------------------------------------- | 356| options | WebSocketCloseOptions | 是 | 参考[WebSocketCloseOptions](#websocketcloseoptions)。 | 357| callback | AsyncCallback\<boolean\> | 是 | 回调函数。 | 358 359**错误码：** 360 361| 错误码ID | 错误信息 | 362| ------- | ----------------------- | 363| 401 | Parameter error. | 364| 201 | Permission denied. | 365 366**示例：** 367 368```js 369let ws = webSocket.createWebSocket(); 370let url = "ws://" 371ws.close({ 372 code: 1000, 373 reason: "your reason" 374}, (err, value) => { 375 if (!err) { 376 console.log("close success") 377 } else { 378 console.log("close fail, err is " + JSON.stringify(err)) 379 } 380}); 381``` 382 383 384### close 385 386close(options?: WebSocketCloseOptions): Promise\<boolean\> 387 388根据可选参数code和reason，关闭WebSocket连接，使用Promise方式作为异步方法。 389 390**需要权限**：ohos.permission.INTERNET 391 392**系统能力**：SystemCapability.Communication.NetStack 393 394**参数：** 395 396| 参数名 | 类型 | 必填 | 说明 | 397| ------- | --------------------- | ---- | ----------------------------------------------------- | 398| options | WebSocketCloseOptions | 否 | 参考[WebSocketCloseOptions](#websocketcloseoptions)。 | 399 400**返回值：** 401 402| 类型 | 说明 | 403| :----------------- | :-------------------------------- | 404| Promise\<boolean\> | 以Promise形式返回关闭连接的结果。 | 405 406**错误码：** 407 408| 错误码ID | 错误信息 | 409| ------- | ----------------------- | 410| 401 | Parameter error. | 411| 201 | Permission denied. | 412 413**示例：** 414 415```js 416let ws = webSocket.createWebSocket(); 417let url = "ws://" 418let promise = ws.close({ 419 code: 1000, 420 reason: "your reason" 421}); 422promise.then((value) => { 423 console.log("close success") 424}).catch((err) => { 425 console.log("close fail, err is " + JSON.stringify(err)) 426}); 427``` 428 429 430### on('open') 431 432on(type: 'open', callback: AsyncCallback\<Object\>): void 433 434订阅WebSocket的打开事件，使用callback方式作为异步方法。 435 436**系统能力**：SystemCapability.Communication.NetStack 437 438**参数：** 439 440| 参数名 | 类型 | 必填 | 说明 | 441| -------- | ----------------------- | ---- | ----------------------------- | 442| type | string | 是 | 'open'：WebSocket的打开事件。 | 443| callback | AsyncCallback\<Object\> | 是 | 回调函数。 | 444 445 446**示例：** 447 448```js 449let ws = webSocket.createWebSocket(); 450ws.on('open', (err, value) => { 451 console.log("on open, status:" + value['status'] + ", message:" + value['message']); 452}); 453``` 454 455 456### off('open') 457 458off(type: 'open', callback?: AsyncCallback\<Object\>): void 459 460取消订阅WebSocket的打开事件，使用callback方式作为异步方法。 461 462>**说明：** 463>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 464 465**系统能力**：SystemCapability.Communication.NetStack 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470| -------- | ----------------------- | ---- | ----------------------------- | 471| type | string | 是 | 'open'：WebSocket的打开事件。 | 472| callback | AsyncCallback\<Object\> | 否 | 回调函数。 | 473 474**示例：** 475 476```js 477let ws = webSocket.createWebSocket(); 478let callback1 = (err, value) => { 479 console.log("on open, status:" + value['status'] + ", message:" + value['message']); 480} 481ws.on('open', callback1); 482// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅 483ws.off('open', callback1); 484``` 485 486 487### on('message') 488 489on(type: 'message', callback: AsyncCallback\<string | ArrayBuffer\>): void 490 491订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。每个消息最大长度为4K，超过4K自动分片。 492 493>**说明：** 494>AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。 495 496**系统能力**：SystemCapability.Communication.NetStack 497 498**参数：** 499 500| 参数名 | 类型 | 必填 | 说明 | 501| -------- | ----------------------- | ---- | -------------------------------------------- | 502| type | string | 是 | 'message'：WebSocket的接收到服务器消息事件。 | 503| callback | AsyncCallback\<string \| ArrayBuffer <sup>8+</sup>\> | 是 | 回调函数。 | 504 505**示例：** 506 507```js 508let ws = webSocket.createWebSocket(); 509ws.on('message', (err, value) => { 510 console.log("on message, message:" + value); 511}); 512``` 513 514 515### off('message') 516 517off(type: 'message', callback?: AsyncCallback\<string | ArrayBuffer\>): void 518 519取消订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。每个消息最大长度为4K，超过4K自动分片。 520 521>**说明：** 522>AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。 523>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 524 525**系统能力**：SystemCapability.Communication.NetStack 526 527**参数：** 528 529| 参数名 | 类型 | 必填 | 说明 | 530| -------- | --------------------------------------------------- | ---- | -------------------------------------------- | 531| type | string | 是 | 'message'：WebSocket的接收到服务器消息事件。 | 532| callback | AsyncCallback\<string \|ArrayBuffer <sup>8+</sup>\> | 否 | 回调函数。 | 533 534**示例：** 535 536```js 537let ws = webSocket.createWebSocket(); 538ws.off('message'); 539``` 540 541 542### on('close') 543 544on(type: 'close', callback: AsyncCallback\<{ code: number, reason: string }\>): void 545 546订阅WebSocket的关闭事件，使用callback方式作为异步方法。 547 548**系统能力**：SystemCapability.Communication.NetStack 549 550**参数：** 551 552| 参数名 | 类型 | 必填 | 说明 | 553| -------- | ----------------------------------------------- | ---- | ------------------------------ | 554| type | string | 是 | 'close'：WebSocket的关闭事件。 | 555| callback | AsyncCallback\<{ code: number, reason: string }\> | 是 | 回调函数。<br>close：close错误码，reason：错误码说明 | 556 557**示例：** 558 559```js 560let ws = webSocket.createWebSocket(); 561ws.on('close', (err, value) => { 562 console.log("on close, code is " + value.code + ", reason is " + value.reason); 563}); 564``` 565 566 567### off('close') 568 569off(type: 'close', callback?: AsyncCallback\<{ code: number, reason: string }\>): void 570 571取消订阅WebSocket的关闭事件，使用callback方式作为异步方法。 572 573>**说明：** 574>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 575 576**系统能力**：SystemCapability.Communication.NetStack 577 578**参数：** 579 580| 参数名 | 类型 | 必填 | 说明 | 581| -------- | ----------------------------------------------- | ---- | ------------------------------ | 582| type | string | 是 | 'close'：WebSocket的关闭事件。 | 583| callback | AsyncCallback\<{ code: number, reason: string }\> | 否 | 回调函数。<br>close：close错误码，reason：错误码说明 | 584 585**示例：** 586 587```js 588let ws = webSocket.createWebSocket(); 589ws.off('close'); 590``` 591 592 593### on('error') 594 595on(type: 'error', callback: ErrorCallback): void 596 597订阅WebSocket的Error事件，使用callback方式作为异步方法。 598 599**系统能力**：SystemCapability.Communication.NetStack 600 601**参数：** 602 603| 参数名 | 类型 | 必填 | 说明 | 604| -------- | ------------- | ---- | ------------------------------- | 605| type | string | 是 | 'error'：WebSocket的Error事件。 | 606| callback | ErrorCallback | 是 | 回调函数。 | 607 608**示例：** 609 610```js 611let ws = webSocket.createWebSocket(); 612ws.on('error', (err) => { 613 console.log("on error, error:" + JSON.stringify(err)) 614}); 615``` 616 617 618### off('error') 619 620off(type: 'error', callback?: ErrorCallback): void 621 622取消订阅WebSocket的Error事件，使用callback方式作为异步方法。 623 624>**说明：** 625>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 626 627**系统能力**：SystemCapability.Communication.NetStack 628 629**参数：** 630 631| 参数名 | 类型 | 必填 | 说明 | 632| -------- | ------------- | ---- | ------------------------------- | 633| type | string | 是 | 'error'：WebSocket的Error事件。 | 634| callback | ErrorCallback | 否 | 回调函数。 | 635 636**示例：** 637 638```js 639let ws = webSocket.createWebSocket(); 640ws.off('error'); 641``` 642 643 644## WebSocketRequestOptions 645 646建立WebSocket连接时，可选参数的类型和说明。 647 648**系统能力**：SystemCapability.Communication.NetStack 649 650| 名称 | 类型 | 必填 | 说明 | 651| ------ | ------ | ---- | ------------------------------------------------------------ | 652| header | Object | 否 | 建立WebSocket连接可选参数，代表建立连接时携带的HTTP头信息。参数内容自定义，也可以不指定。 | 653 654 655## WebSocketCloseOptions 656 657关闭WebSocket连接时，可选参数的类型和说明。 658 659**系统能力**：SystemCapability.Communication.NetStack 660 661| 名称 | 类型 | 必填 | 说明 | 662| ------ | ------ | ---- | ------------------------------------------------------------ | 663| code | number | 否 | 错误码，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为1000。 | 664| reason | string | 否 | 原因值，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为空字符串（""）。 | 665 666## close错误码说明 667 668发送给服务端的错误码可以自行定义，下面的列表仅供参考。 669 670**系统能力**：SystemCapability.Communication.NetStack 671 672| 值 | 说明 | 673| :-------- | :----------------- | 674| 1000 | 正常关闭 | 675| 1001 | 服务器主动关闭 | 676| 1002 | 协议错误 | 677| 1003 | 无法处理的数据类型 | 678| 1004~1015 | 保留值 | 679 680