1@page websocket websocket 2 3[更正文档](https://gitee.com/alios-things/http/edit/master/README.md)      [贡献说明](https://help.aliyun.com/document_detail/302301.html) 4 5 6# 概述 7 8websocket是一个用C实现的轻量级的websocket客户端，支持TLS。 9 10## 版权信息 11> MIT License 12 13## 目录结构 14```tree 15. 16├── examples 17│ └── test_librws_creation.c # 测试代码 18├── include 19│ ├── librws.h # 对外头文件 20│ ├── rws_common.h # 内部头文件 21│ ├── rws_error.h # 内部头文件 22│ ├── rws_frame.h # 内部头文件 23│ ├── rws_list.h # 内部头文件 24│ ├── rws_memory.h # 内部头文件 25│ ├── rws_network.h # 内部头文件 26│ ├── rws_socket.h # 内部头文件 27│ ├── rws_string.h # 内部头文件 28│ └── rws_thread.h # 内部头文件 29├── package.yaml 30├── README.md 31└── src 32 ├── librws.c 33 ├── rws_common.c 34 ├── rws_error.c # 错误处理 35 ├── rws_frame.c # 帧处理 36 ├── rws_list.c # 链表 37 ├── rws_memory.c # 内存 38 ├── rws_socketpriv.c # 主处理流程 39 ├── rws_socketpub.c # 对外接口 40 ├── rws_string.c # 字符串 41 └── rws_thread.c # 线程 42``` 43 44## 依赖组件 45 46* posix 47* ulog 48* mbedtls 49 50# 常用配置 51websocket的常用配置在文件**package.yaml内** 52> WEBSOCKET_SSL_ENABLE ：是否开启SSL支持，默认开启 53```yaml 54WEBSOCKET_SSL_ENABLE: 1 55``` 56 57# API说明 58- 参考 [websocket_api](https://g.alicdn.com/alios-things-3.3/doc/group__websocket__api.html) 59 60## 创建websocket上下文所需空间，返回具柄。注意，此时尚未连接。 61```C 62rws_socket rws_socket_create(void) 63``` 64 65|args |description| 66|:----- |:----| 67|void |N/A| 68 69## 设置websocket连接URL信息，包括安全/非安全模式、域名、端口、路径 70```C 71void rws_socket_set_url(rws_socket socket, 72 const char * scheme, 73 const char * host, 74 const int port, 75 const char * path) 76``` 77 78|args |description| 79|:----- |:----| 80|socket |websocket具柄| 81|scheme |模式，"ws"或者"wss"| 82|host |域名，如"echo.websocket.org"| 83|port |端口，如443| 84|path |路径，如"/"| 85 86## 设置websocket连接安全/非安全模式。 87```C 88void rws_socket_set_scheme(rws_socket socket, const char * scheme) 89``` 90 91|args |description| 92|:----- |:----| 93|socket |websocket具柄| 94|scheme |模式，"ws"或者"wss"| 95 96## 设置websocket连接域名。 97```C 98void rws_socket_set_host(rws_socket socket, const char * host) 99``` 100 101|args |description| 102|:----- |:----| 103|socket |websocket具柄| 104|host |域名，如"echo.websocket.org"| 105 106## 设置websocket连接端口。 107```C 108void rws_socket_set_port(rws_socket socket, const int port) 109``` 110 111|args |description| 112|:----- |:----| 113|socket |websocket具柄| 114|port |端口，如443| 115 116## 设置websocket连接路径。 117```C 118void rws_socket_set_path(rws_socket socket, const char * path) 119``` 120 121|args |description| 122|:----- |:----| 123|socket |websocket具柄| 124|port |路径，如"/"| 125 126## 设置websocket连接请求报文中协议字段。 127```C 128void rws_socket_set_protocol(rws_socket socket, const char * protocol) 129``` 130 131|args |description| 132|:----- |:----| 133|socket |websocket具柄| 134|protocol |协议字段，如"echo-protocol"或 "chat, superchat"| 135 136 137## 获取websocket连接域名。 138```C 139const char * rws_socket_get_host(rws_socket socket) 140``` 141 142|args |description| 143|:----- |:----| 144|socket |websocket具柄| 145 146## 获取websocket连接模式。 147```C 148const char * rws_socket_get_host(rws_socket socket) 149``` 150 151|args |description| 152|:----- |:----| 153|socket |websocket具柄| 154 155## 获取websocket连接端口。 156```C 157int rws_socket_get_port(rws_socket socket) 158``` 159 160|args |description| 161|:----- |:----| 162|socket |websocket具柄| 163 164## 获取websocket连接路径。 165```C 166const char * rws_socket_get_path(rws_socket socket) 167``` 168 169|args |description| 170|:----- |:----| 171|socket |websocket具柄| 172 173## 设置websocket在安全模式下服务端的证书。 174```C 175void rws_socket_set_server_cert(rws_socket socket, const char *server_cert, int server_cert_len) 176``` 177 178|args |description| 179|:----- |:----| 180|socket |websocket具柄| 181|server_cert |服务证书| 182|socket |服务证书长度| 183 184## 获取websocket当前错误。 185```C 186rws_error rws_socket_get_error(rws_socket socket) 187``` 188 189|args |description| 190|:----- |:----| 191|socket |websocket具柄| 192 193## 启动连接websocket。 194```C 195rws_bool rws_socket_connect(rws_socket socket) 196``` 197 198|args |description| 199|:----- |:----| 200|socket |websocket具柄| 201 202## 断开websocket连接并释放资源，释放后勿再操作该具柄。 203```C 204void rws_socket_disconnect_and_release(rws_socket socket) 205``` 206 207|args |description| 208|:----- |:----| 209|socket |websocket具柄| 210 211## 判断该websocket是否已连接。 212```C 213rws_bool rws_socket_is_connected(rws_socket socket); 214``` 215 216|args |description| 217|:----- |:----| 218|socket |websocket具柄| 219 220 221## 向服务端发送text数据。 222```C 223rws_bool rws_socket_send_text(rws_socket socket, const char * text) 224``` 225 226|args |description| 227|:----- |:----| 228|socket |websocket具柄| 229|text |需要发送的text数据| 230 231## 开始向服务端发送二进制数据，该接口需要和rws_socket_send_bin_continue、rws_socket_send_bin_finish配合使用。 232```C 233rws_bool rws_socket_send_bin_start(rws_socket socket, const char *bin, size_t len) 234``` 235 236|args |description| 237|:----- |:----| 238|socket |websocket具柄| 239|bin |需要发送二进制数据| 240|len |二进制数据长度| 241 242## 继续向服务端发送二进制数据，该接口需要和rws_socket_send_bin_start、rws_socket_send_bin_finish配合使用。 243```C 244rws_bool rws_socket_send_bin_continue(rws_socket socket, const char *bin, size_t len) 245``` 246 247|args |description| 248|:----- |:----| 249|socket |websocket具柄| 250|bin |需要发送二进制数据| 251|len |二进制数据长度| 252 253## 向服务端发送结束二进制数据，该接口需要和rws_socket_send_bin_start、rws_socket_send_bin_continue配合使用。 254```C 255rws_bool rws_socket_send_bin_finish(rws_socket socket, const char *bin, size_t len) 256``` 257 258|args |description| 259|:----- |:----| 260|socket |websocket具柄| 261|bin |需要发送二进制数据| 262|len |二进制数据长度| 263 264## 向服务端发送ping包。 265```C 266rws_bool rws_socket_send_ping(rws_socket socket) 267``` 268 269|args |description| 270|:----- |:----| 271|socket |websocket具柄| 272 273## 设置websocket连接成功后的回调函数。 274```C 275void rws_socket_set_on_connected(rws_socket socket, rws_on_socket callback) 276``` 277 278|args |description| 279|:----- |:----| 280|socket |websocket具柄| 281|callback |回调函数| 282 283## 设置websocket连接断开后的回调函数。 284```C 285void rws_socket_set_on_disconnected(rws_socket socket, rws_on_socket callback) 286``` 287 288|args |description| 289|:----- |:----| 290|socket |websocket具柄| 291|callback |回调函数| 292 293## 设置websocket成功发送ping后回调函数。 294```C 295void rws_socket_set_on_send_ping(rws_socket socket, rws_on_socket_send_ping callback) 296``` 297 298|args |description| 299|:----- |:----| 300|socket |websocket具柄| 301|callback |回调函数| 302 303## 设置websocke接收到text数据的回调函数。 304```C 305void rws_socket_set_on_received_text(rws_socket socket, rws_on_socket_recvd_text callback) 306``` 307 308|args |description| 309|:----- |:----| 310|socket |websocket具柄| 311|callback |回调函数| 312 313 314## 设置websocke接收到bin数据的回调函数。 315```C 316void rws_socket_set_on_received_bin(rws_socket socket, rws_on_socket_recvd_bin callback) 317``` 318 319|args |description| 320|:----- |:----| 321|socket |websocket具柄| 322|callback |回调函数| 323 324 325## 设置websocke接收到pong消息的回调函数。 326```C 327void rws_socket_set_on_received_pong(rws_socket socket, rws_on_socket_recvd_pong callback) 328``` 329 330|args |description| 331|:----- |:----| 332|socket |websocket具柄| 333|callback |回调函数| 334 335 336## 获取错误码。 337```C 338int rws_error_get_code(rws_error error) 339``` 340 341|args |description| 342|:----- |:----| 343|error |错误| 344 345## 获取http错误码 346```C 347int rws_error_get_http_error(rws_error error) 348``` 349 350|args |description| 351|:----- |:----| 352|error |错误| 353 354## 获取获取错误描述 355```C 356const char * rws_error_get_description(rws_error error) 357``` 358 359|args |description| 360|:----- |:----| 361|error |错误| 362 363# 使用示例 364 365组件使用示例相关的代码下载、编译和固件烧录均依赖AliOS Things配套的开发工具，所以首先需要参考[《AliOS Things集成开发环境使用说明之搭建开发环境》](https://help.aliyun.com/document_detail/302378.html)，下载安装。 366待开发环境搭建完成后，可以按照以下步骤进行示例的测试。 367 368## 步骤1 创建或打开工程 369 370**打开已有工程** 371 372如果用于测试的案例工程已存在，可参考[《AliOS Things集成开发环境使用说明之打开工程》](https://help.aliyun.com/document_detail/302381.html)打开已有工程。 373 374**创建新的工程** 375 376组件的示例代码可以通过编译链接到AliOS Things的任意案例（solution）来运行，这里选择helloworld_demo案例。helloworld_demo案例相关的源代码下载可参考[《AliOS Things集成开发环境使用说明之创建工程》](https://help.aliyun.com/document_detail/302379.html)。 377 378## 步骤2 添加组件 379 380案例下载完成后，需要在helloworld_demo组件的package.yaml中添加对组件的依赖： 381 382```yaml 383 384depends: 385 - netmgr: master # helloworld_demo中引入netmgr组件，用于WiFi联网 386 - websocket: master # helloworld_demo中引入websocket组件 387 - lwip: master # helloworld_demo中引入lwip组件 388``` 389 390## 步骤3 下载组件 391 392在已安装了 的开发环境工具栏中，选择Terminal -> New Terminal启动终端，并且默认工作路径为当前工程的workspace，此时在终端命令行中输入： 393 394```shell 395 396aos install websocket 397 398``` 399 400上述命令执行成功后，组件源码则被下载到了./components/websocket路径中。 401 402## 步骤4 添加示例 403 404在websocket组件的package.yaml中添加[example示例代码](https://gitee.com/alios-things/http/tree/master/example)： 405 406```yaml 407source_file: 408 - "src/*.c" 409 - "example/*.c" # add websocket_example.c 410``` 411 412## 步骤5 编译固件 413 414在示例代码已经添加至组件的配置文件，并且helloworld_demo已添加了对该组件的依赖后，就可以编译helloworld_demo案例来生成固件了，具体编译方法可参考[《AliOS Things集成开发环境使用说明之编译固件》](https://help.aliyun.com/document_detail/302384.html)。 415 416## 步骤6 烧录固件 417 418helloworld_demo案例的固件生成后，可参考[《AliOS Things集成开发环境使用说明之烧录固件》](https://help.aliyun.com/document_detail/302383.html)来烧录固件。 419 420## 步骤7 打开串口 421 422固件烧录完成后，可以通过串口查看示例的运行结果，打开串口的具体方法可参考[《AliOS Things集成开发环境使用说明之查看日志》](https://help.aliyun.com/document_detail/302382.html)。 423 424当串口终端打开成功后，可在串口中输入help来查看已添加的测试命令。 425 426## 步骤8 websocket测试示例 427> CLI命令行输入初始化netmgr命令： 428 429```shell 430netmgr_example 431``` 432 433> CLI命令行输入联网命令： 434```shell 435netmgr -t wifi -c ssid password 436``` 437 438> 然后，CLI命令行输入： 439```shell 440websocket_example 441``` 442 443**关键日志** 444> CLI日志： 445```shell 446example websocket test success! 447``` 448 449# FAQ 450 451@ref 操作系统内核 452