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