1# Netstack 2 3 4## 概述 5 6为网络协议栈模块提供c接口。 7 8**起始版本：** 11 9 10 11## 汇总 12 13 14### 文件 15 16| 名称 | 描述 | 17| -------- | -------- | 18| [net_ssl_c.h](net__ssl__c_8h.md) | 为SSL/TLS证书链校验模块定义C接口。 | 19| [net_ssl_c_type.h](net__ssl__c__type_8h.md) | 定义SSL/TLS证书链校验模块的C接口需要的数据结构。 | 20| [net_websocket.h](net__websocket_8h.md) | 为websocket客户端模块定义C接口。 | 21| [net_websocket_type.h](net__websocket__type_8h.md) | 定义websocket客户端模块的C接口需要的数据结构。 | 22 23 24### 结构体 25 26| 名称 | 描述 | 27| -------- | -------- | 28| [NetStack_CertBlob](_net_stack___cert_blob.md) | 证书数据结构体。 | 29| [WebSocket_CloseResult](_web_socket___close_result.md) | websocket客户端来自服务端关闭的参数。 | 30| [WebSocket_CloseOption](_web_socket___close_option.md) | websocket客户端主动关闭的参数。 | 31| [WebSocket_ErrorResult](_web_socket___error_result.md) | websocket客户端来自服务端连接错误的参数。 | 32| [WebSocket_OpenResult](_web_socket___open_result.md) | websocket客户端来自服务端连接成功的参数。 | 33| [WebSocket_Header](_web_socket___header.md) | websocket客户端增加header头的链表节点。 | 34| [WebSocket_RequestOptions](_web_socket___request_options.md) | websocket客户端和服务端建立连接的参数。 | 35| [WebSocket](_web_socket.md) | websocket客户端结构体。 | 36 37 38### 类型定义 39 40| 名称 | 描述 | 41| -------- | -------- | 42| (\* [WebSocket_OnOpenCallback](#websocket_onopencallback)) (struct [WebSocket](_web_socket.md) \*client, [WebSocket_OpenResult](_web_socket___open_result.md) openResult) | websocket客户端接收open消息的回调函数定义。 | 43| (\* [WebSocket_OnMessageCallback](#websocket_onmessagecallback)) (struct [WebSocket](_web_socket.md) \*client, char \*data, uint32_t length) | websocket客户端接收数据的回调函数定义。 | 44| (\* [WebSocket_OnErrorCallback](#websocket_onerrorcallback)) (struct [WebSocket](_web_socket.md) \*client, [WebSocket_ErrorResult](_web_socket___error_result.md) errorResult) | websocket客户端接收error错误消息的回调函数定义。 | 45| (\* [WebSocket_OnCloseCallback](#websocket_onclosecallback)) (struct [WebSocket](_web_socket.md) \*client, [WebSocket_CloseResult](_web_socket___close_result.md) closeResult) | websocket客户端接收close消息的回调函数定义。 | 46 47### 枚举 48 49| 名称 | 描述 | 50| -------- | -------- | 51| [NetStack_CertType](#netstack_certtype) { <br/>NetStack_CERT_TYPE_PEM = 0, <br/>NetStack_CERT_TYPE_DER = 1, <br/>NetStack_CERT_TYPE_INVALID <br/>} | 证书类型枚举。 | 52| [WebSocket_ErrCode](#websocket_errcode) {<br/>WEBSOCKET_OK = 0, <br/>E_BASE = 1000, <br/>WEBSOCKET_CLIENT_NULL = (E_BASE + 1), <br/>WEBSOCKET_CLIENT_NOT_CREATED = (E_BASE + 2),<br/>WEBSOCKET_CONNECTION_ERROR = (E_BASE + 3), <br/>WEBSOCKET_CONNECTION_PARSE_URL_ERROR = (E_BASE + 5),<br/> WEBSOCKET_CONNECTION_NO_MEMORY = (E_BASE + 6), <br/>WEBSOCKET_CONNECTION_CLOSED_BY_PEER = (E_BASE + 7),<br/>WEBSOCKET_DESTROYED = (E_BASE + 8), <br/>WEBSOCKET_PROTOCOL_ERROR = (E_BASE + 9), <br/>WEBSOCKET_SEND_NO_MEMORY = (E_BASE + 10), <br/>WEBSOCKET_SEND_DATA_NULL = (E_BASE + 11),<br/>WEBSOCKET_DATA_LENGTH_EXCEEDED = (E_BASE + 12), <br/>WEBSOCKET_QUEUE_LENGTH_EXCEEDED = (E_BASE + 13),<br/> WEBSOCKET_NO_CLIENT_CONTEXT = (E_BASE + 14), <br/>WEBSOCKET_NO_HEADER_CONTEXT = (E_BASE + 15),<br/>WEBSOCKET_HEADER_EXCEEDED = (E_BASE + 16), <br/>WEBSOCKET_NO_CONNECTION = (E_BASE + 17), <br/>WEBSOCKET_NO_CONNECTION_CONTEXT = (E_BASE + 18)<br/>} | websocket错误码。 | 53 54### 函数 55 56| 名称 | 描述 | 57| -------- | -------- | 58| [OH_WebSocketClient_Constructor](#oh_websocketclient_constructor) ([WebSocket_OnOpenCallback](#websocket_onopencallback) onOpen, [WebSocket_OnMessageCallback](#websocket_onmessagecallback) onMessage, [WebSocket_OnErrorCallback](#websocket_onerrorcallback) onError, [WebSocket_OnCloseCallback](#websocket_onclosecallback) onclose) | OH_NetStack_WebsocketClient客户端的构造函数。 | 59| [OH_WebSocketClient_AddHeader](#oh_websocketclient_addheader) (struct [WebSocket](_web_socket.md) \*client, struct [WebSocket_Header](_web_socket___header.md) header) | 将header头信息添加到client客户端request中。 | 60| [OH_WebSocketClient_Connect](#oh_websocketclient_connect) (struct [WebSocket](_web_socket.md) \*client, const char \*url, struct [WebSocket_RequestOptions](_web_socket___request_options.md) options) | 客户端连接服务端。 | 61| [OH_WebSocketClient_Send](#oh_websocketclient_send) (struct [WebSocket](_web_socket.md) \*client, char \*data, size_t length) | 客户端向服务端发送数据。 | 62| [OH_WebSocketClient_Close](#oh_websocketclient_close) (struct [WebSocket](_web_socket.md) \*client, struct [WebSocket_CloseOption](_web_socket___close_option.md) options) | 客户端主动关闭websocket连接。 | 63| [OH_WebSocketClient_Destroy](#oh_websocketclient_destroy) (struct [WebSocket](_web_socket.md) \*client) | 释放websocket连接上下文和资源。 | 64 65### 变量 66 67| 名称 | 描述 | 68| -------- | -------- | 69| [NetStack_CertBlob::type](#type) | 证书类型。 | 70| [NetStack_CertBlob::size](#size) | 证书内容长度。 | 71| [NetStack_CertBlob::data](#data) | 证书内容。 | 72| [WebSocket_CloseResult::code](#code-13) | 关闭的错误码。 | 73| [WebSocket_CloseResult::reason](#reason-13) | 关闭的错误原因。 | 74| [WebSocket_CloseOption::code](#code-23) | 关闭的错误码。 | 75| [WebSocket_CloseOption::reason](#reason-23) | 关闭的错误原因。 | 76| [WebSocket_ErrorResult::errorCode](#errorcode) | 错误码。 | 77| [WebSocket_ErrorResult::errorMessage](#errormessage) | 错误的消息。 | 78| [WebSocket_OpenResult::code](#code-33) | websocket客户端连接成功码。 | 79| [WebSocket_OpenResult::reason](#reason-33) | websocket客户端连接原因。 | 80| [WebSocket_Header::fieldName](#fieldname) | header头的字段名。 | 81| [WebSocket_Header::fieldValue](#fieldvalue) | header头的字段内容。 | 82| [WebSocket_Header](_web_socket___header.md) \* [WebSocket_Header::next](#next) | header头链表的next指针。 | 83| [WebSocket_Header](_web_socket___header.md) \* WebSocket_RequestOptions::headers | header头信息。 | 84| [WebSocket_OnOpenCallback](#websocket_onopencallback)[WebSocket::onOpen](#onopen) | 客户端接收连接消息的回调指针。 | 85| [WebSocket_OnMessageCallback](#websocket_onmessagecallback)[WebSocket::onMessage](#onmessage) | 客户端接收消息的回调指针。 | 86| [WebSocket_OnErrorCallback](#websocket_onerrorcallback)[WebSocket::onError](#onerror) | 客户端接收错误消息的回调指针。 | 87| [WebSocket_OnCloseCallback](#websocket_onclosecallback)[WebSocket::onClose](#onclose) | 客户端接收关闭消息的回调指针。 | 88| [WebSocket_RequestOptions](_web_socket___request_options.md)[WebSocket::requestOptions](#requestoptions) | 客户端建立连接请求内容。 | 89 90 91## 类型定义说明 92 93 94### WebSocket_OnCloseCallback 95 96``` 97typedef void(* WebSocket_OnCloseCallback) (struct WebSocket *client, WebSocket_CloseResult closeResult) 98``` 99**描述** 100websocket客户端接收close消息的回调函数定义 101 102**起始版本：** 11 103 104**参数:** 105 106| 名称 | 描述 | 107| -------- | -------- | 108| client | websocket客户端 | 109| closeResult | websocket客户端接收关闭消息的内容 | 110 111 112### WebSocket_OnErrorCallback 113 114``` 115typedef void(* WebSocket_OnErrorCallback) (struct WebSocket *client, WebSocket_ErrorResult errorResult) 116``` 117**描述** 118websocket客户端接收error错误消息的回调函数定义 119 120**起始版本：** 11 121 122**参数:** 123 124| 名称 | 描述 | 125| -------- | -------- | 126| client | websocket客户端 | 127| errorResult | websocket客户端接收连接错误消息的内容 | 128 129 130### WebSocket_OnMessageCallback 131 132``` 133typedef void(* WebSocket_OnMessageCallback) (struct WebSocket *client, char *data, uint32_t length) 134``` 135**描述** 136websocket客户端接收数据的回调函数定义 137 138**起始版本：** 11 139 140**参数:** 141 142| 名称 | 描述 | 143| -------- | -------- | 144| client | websocket客户端 | 145| data | websocket客户端接收的数据 | 146| length | websocket客户端接收的数据长度 | 147 148 149### WebSocket_OnOpenCallback 150 151``` 152typedef void(* WebSocket_OnOpenCallback) (struct WebSocket *client, WebSocket_OpenResult openResult) 153``` 154**描述** 155websocket客户端接收open消息的回调函数定义 156 157**起始版本：** 11 158 159**参数:** 160 161| 名称 | 描述 | 162| -------- | -------- | 163| client | websocket客户端 | 164| openResult | websocket客户端接收建立连接消息的内容 | 165 166 167 168## 枚举类型说明 169 170 171### NetStack_CertType 172 173``` 174enum NetStack_CertType 175``` 176 177**描述** 178 179证书类型枚举。 180 181**起始版本：** 11 182 183| 枚举值 | 描述 | 184| -------- | -------- | 185| NetStack_CERT_TYPE_PEM | PEM证书类型。 | 186| NetStack_CERT_TYPE_DER | DER证书类型。 | 187| NetStack_CERT_TYPE_INVALID | 错误证书类型。 | 188 189 190### WebSocket_ErrCode 191 192``` 193enum WebSocket_ErrCode 194``` 195**描述** 196websocket错误码 197 198**起始版本：** 11 199 200| 枚举值 | 描述 | 201| -------- | -------- | 202| WEBSOCKET_OK | 执行成功。 | 203| E_BASE | 异常错误代码的基础。 | 204| WEBSOCKET_CLIENT_NULL | websocket为空。 | 205| WEBSOCKET_CLIENT_NOT_CREATED | websocket未创建。 | 206| WEBSOCKET_CONNECTION_ERROR | websocket客户端连接错误。 | 207| WEBSOCKET_CONNECTION_PARSE_URL_ERROR | websocket客户端连接参数解析错误。 | 208| WEBSOCKET_CONNECTION_NO_MEMORY | websocket客户端连接时创建上下文无内存。 | 209| WEBSOCKET_CONNECTION_CLOSED_BY_PEER | 初始化时候关闭。 | 210| WEBSOCKET_DESTROYED | websocket连接被销毁。 | 211| WEBSOCKET_PROTOCOL_ERROR | websocket客户端连接时候协议错误。 | 212| WEBSOCKET_SEND_NO_MEMORY | websocket客户端发送数据时候没有足够内存。 | 213| WEBSOCKET_SEND_DATA_NULL | websocket客户端发送数据为空。 | 214| WEBSOCKET_DATA_LENGTH_EXCEEDED | websocket客户端发送数据长度超限制。 | 215| WEBSOCKET_QUEUE_LENGTH_EXCEEDED | websocket客户端发送数据队列长度超限制。 | 216| WEBSOCKET_NO_CLIENT_CONTEXT | websocket客户端上下文为空。 | 217| WEBSOCKET_NO_HEADER_CONTEXT | websocket客户端header头异常。 | 218| WEBSOCKET_HEADER_EXCEEDED | websocket客户端header头超过限制。 | 219| WEBSOCKET_NO_CONNECTION | websocket客户端没有连接。 | 220| WEBSOCKET_NO_CONNECTION_CONTEXT | websocket客户端没有连接上下文。 | 221 222 223## 函数说明 224 225 226### OH_NetStack_VerifyCertification() 227 228``` 229uint32_t OH_NetStack_VerifyCertification (const struct NetStack_CertBlob * cert, const struct NetStack_CertBlob * caCert ) 230``` 231 232**描述** 233 234证书链校验接口。 235 236**系统能力：** SystemCapability.Communication.NetStack 237 238**起始版本：** 11 239 240**参数:** 241 242| 名称 | 描述 | 243| -------- | -------- | 244| cert | 用户传入的待校验证书。 | 245| caCert | 用户指定的证书，若为空则以系统预置证书进行校验。 | 246 247**返回：** 248 2490 - 成功. 250 2512305001 - 未指定的错误. 252 2532305002 - 无法获取颁发者证书. 254 2552305003 - 无法获取证书吊销列表（CRL）. 256 2572305004 - 无法解密证书签名. 258 2592305005 - 无法解密CRL签名. 260 2612305006 - 无法解码颁发者公钥. 262 2632305007 - 证书签名失败. 264 2652305008 - CRL签名失败. 266 2672305009 - 证书尚未生效. 268 2692305010 - 证书已过期. 270 2712305011 - CRL尚未有效. 272 2732305012 - CRL已过期. 274 2752305023 - 证书已被吊销. 276 2772305024 - 证书颁发机构（CA）无效. 278 2792305027 - 证书不受信任. 280 281### OH_WebSocketClient_AddHeader() 282 283``` 284int OH_WebSocketClient_AddHeader (struct WebSocket * client, struct WebSocket_Header header ) 285``` 286**描述** 287将header头信息添加到client客户端request中。 288 289**系统能力：** SystemCapability.Communication.NetStack 290 291**起始版本：** 11 292 293**参数:** 294 295| 名称 | 描述 | 296| -------- | -------- | 297| client | 客户端指针。 | 298| header | header头信息。 | 299 300**返回：** 301 302返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 303 304**Permission：** 305 306ohos.permission.INTERNET 307 308 309### OH_WebSocketClient_Close() 310 311``` 312int OH_WebSocketClient_Close (struct WebSocket * client, struct WebSocket_CloseOption options ) 313``` 314**描述** 315客户端主动关闭websocket连接。 316 317**系统能力：** SystemCapability.Communication.NetStack 318 319**起始版本：** 11 320 321**参数:** 322 323| 名称 | 描述 | 324| -------- | -------- | 325| client | 客户端。 | 326| url | 客户端要连接到服务端的地址。 | 327| options | 发起关闭连接的可选参数。 | 328 329**返回：** 330 331返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 332 333**Permission：** 334 335ohos.permission.INTERNET 336 337 338### OH_WebSocketClient_Connect() 339 340``` 341int OH_WebSocketClient_Connect (struct WebSocket * client, const char * url, struct WebSocket_RequestOptions options ) 342``` 343**描述** 344客户端连接服务端。 345 346**系统能力：** SystemCapability.Communication.NetStack 347 348**起始版本：** 11 349 350**参数:** 351 352| 名称 | 描述 | 353| -------- | -------- | 354| client | 客户端指针。 | 355| url | 客户端要连接到服务端的地址。 | 356| options | 发起连接的可选参数。 | 357 358**返回：** 359 360返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 361 362**Permission：** 363 364ohos.permission.INTERNET 365 366 367### OH_WebSocketClient_Constructor() 368 369``` 370struct WebSocket* OH_WebSocketClient_Constructor (WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage, WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose ) 371``` 372**描述** 373OH_NetStack_WebsocketClient客户端的构造函数。 374 375**系统能力：** SystemCapability.Communication.NetStack 376 377**起始版本：** 11 378 379**参数:** 380 381| 名称 | 描述 | 382| -------- | -------- | 383| onMessage | 客户端定义的接收消息的回调函数。 | 384| onClose | 客户端定义的关闭消息的回调函数。 | 385| onError | 客户端定义的错误消息的回调函数。 | 386| onOpen | 客户端定义的建立连接消息的回调函数。 | 387 388**返回：** 389 390成功返回客户端指针，失败返回为NULL。 391 392**Permission：** 393 394ohos.permission.INTERNET 395 396 397### OH_WebSocketClient_Destroy() 398 399``` 400int OH_WebSocketClient_Destroy (struct WebSocket * client) 401``` 402**描述** 403释放websocket连接上下文和资源。 404 405**系统能力：** SystemCapability.Communication.NetStack 406 407**起始版本：** 11 408 409**参数:** 410 411| 名称 | 描述 | 412| -------- | -------- | 413| client | 客户端。 | 414 415**返回：** 416 417返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 418 419**Permission：** 420 421ohos.permission.INTERNET 422 423 424### OH_WebSocketClient_Send() 425 426``` 427int OH_WebSocketClient_Send (struct WebSocket * client, char * data, size_t length ) 428``` 429**描述** 430客户端向服务端发送数据。 431 432**系统能力：** SystemCapability.Communication.NetStack 433 434**起始版本：** 11 435 436**参数:** 437 438| 名称 | 描述 | 439| -------- | -------- | 440| client | 客户端。 | 441| data | 客户端发送的数据。 | 442| length | 客户端发送的数据长度。 | 443 444**返回：** 445 4460 - 成功. 447 448返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 449 450**Permission：** 451 452ohos.permission.INTERNET 453 454## 变量说明 455 456 457### data 458 459``` 460uint8_t* NetStack_CertBlob::data 461``` 462 463**描述** 464 465证书内容。 466 467 468### size 469 470``` 471uint32_t NetStack_CertBlob::size 472``` 473 474**描述** 475 476证书内容长度。 477 478 479### type 480 481``` 482enum NetStack_CertType NetStack_CertBlob::type 483``` 484 485**描述** 486 487证书类型。 488 489 490### code [1/3] 491 492``` 493uint32_t WebSocket_CloseResult::code 494``` 495 496**描述** 497 498关闭的错误码。 499 500 501### code [2/3] 502 503``` 504uint32_t WebSocket_CloseOption::code 505``` 506 507**描述** 508 509关闭的错误码。 510 511 512### code [3/3] 513 514``` 515uint32_t WebSocket_OpenResult::code 516``` 517 518**描述** 519 520websocket客户端连接成功码。 521 522 523### errorCode 524 525``` 526uint32_t WebSocket_ErrorResult::errorCode 527``` 528 529**描述** 530 531错误码。 532 533 534### errorMessage 535 536``` 537const char* WebSocket_ErrorResult::errorMessage 538``` 539 540**描述** 541 542错误的消息。 543 544 545### fieldName 546 547``` 548const char* WebSocket_Header::fieldName 549``` 550 551**描述** 552 553header头的字段名。 554 555 556### fieldValue 557 558``` 559const char* WebSocket_Header::fieldValue 560``` 561 562**描述** 563 564header头的字段内容。 565 566 567### next 568 569``` 570struct WebSocket_Header* WebSocket_Header::next 571``` 572 573**描述** 574 575header头链表的next指针。 576 577 578### onClose 579 580``` 581WebSocket_OnCloseCallback WebSocket::onClose 582``` 583 584**描述** 585 586客户端接收关闭消息的回调指针。 587 588 589### onError 590 591``` 592WebSocket_OnErrorCallback WebSocket::onError 593``` 594 595**描述** 596 597客户端接收错误消息的回调指针。 598 599 600### onMessage 601 602``` 603WebSocket_OnMessageCallback WebSocket::onMessage 604``` 605 606**描述** 607 608客户端接收消息的回调指针。 609 610 611### onOpen 612 613``` 614WebSocket_OnOpenCallback WebSocket::onOpen 615``` 616 617**描述** 618 619客户端接收连接消息的回调指针。 620 621 622### reason [1/3] 623 624``` 625const char* WebSocket_CloseResult::reason 626``` 627 628**描述** 629 630关闭的错误原因。 631 632 633### reason [2/3] 634 635``` 636const char* WebSocket_CloseOption::reason 637``` 638 639**描述** 640 641关闭的错误原因。 642 643 644### reason [3/3] 645 646``` 647const char* WebSocket_OpenResult::reason 648``` 649 650**描述** 651 652websocket客户端连接原因。 653 654 655### requestOptions 656 657``` 658WebSocket_RequestOptions WebSocket::requestOptions 659``` 660 661**描述** 662 663客户端建立连接请求内容。