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) | Websocket客户端的构造函数。 | 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 305 306### OH_WebSocketClient_Close() 307 308``` 309int OH_WebSocketClient_Close (struct WebSocket * client, struct WebSocket_CloseOption options ) 310``` 311**描述** 312客户端主动关闭websocket连接。 313 314**系统能力：** SystemCapability.Communication.NetStack 315 316**起始版本：** 11 317 318**参数:** 319 320| 名称 | 描述 | 321| -------- | -------- | 322| client | 客户端。 | 323| url | 客户端要连接到服务端的地址。 | 324| options | 发起关闭连接的可选参数。 | 325 326**返回：** 327 328返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 329 330**Permission：** 331 332ohos.permission.INTERNET 333 334 335### OH_WebSocketClient_Connect() 336 337``` 338int OH_WebSocketClient_Connect (struct WebSocket * client, const char * url, struct WebSocket_RequestOptions options ) 339``` 340**描述** 341客户端连接服务端。 342 343**系统能力：** SystemCapability.Communication.NetStack 344 345**起始版本：** 11 346 347**参数:** 348 349| 名称 | 描述 | 350| -------- | -------- | 351| client | 客户端指针。 | 352| url | 客户端要连接到服务端的地址。 | 353| options | 发起连接的可选参数。 | 354 355**返回：** 356 357返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 358 359**Permission：** 360 361ohos.permission.INTERNET 362 363 364### OH_WebSocketClient_Constructor() 365 366``` 367struct WebSocket* OH_WebSocketClient_Constructor (WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage, WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose ) 368``` 369**描述** 370Websocket客户端的构造函数。 371 372**系统能力：** SystemCapability.Communication.NetStack 373 374**起始版本：** 11 375 376**参数:** 377 378| 名称 | 描述 | 379| -------- | -------- | 380| onMessage | 客户端定义的接收消息的回调函数。 | 381| onClose | 客户端定义的关闭消息的回调函数。 | 382| onError | 客户端定义的错误消息的回调函数。 | 383| onOpen | 客户端定义的建立连接消息的回调函数。 | 384 385**返回：** 386 387成功返回客户端指针，失败返回为NULL。 388 389 390 391### OH_WebSocketClient_Destroy() 392 393``` 394int OH_WebSocketClient_Destroy (struct WebSocket * client) 395``` 396**描述** 397释放websocket连接上下文和资源。 398 399**系统能力：** SystemCapability.Communication.NetStack 400 401**起始版本：** 11 402 403**参数:** 404 405| 名称 | 描述 | 406| -------- | -------- | 407| client | 客户端。 | 408 409**返回：** 410 411返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 412 413**Permission：** 414 415ohos.permission.INTERNET 416 417 418### OH_WebSocketClient_Send() 419 420``` 421int OH_WebSocketClient_Send (struct WebSocket * client, char * data, size_t length ) 422``` 423**描述** 424客户端向服务端发送数据。 425 426**系统能力：** SystemCapability.Communication.NetStack 427 428**起始版本：** 11 429 430**参数:** 431 432| 名称 | 描述 | 433| -------- | -------- | 434| client | 客户端。 | 435| data | 客户端发送的数据。 | 436| length | 客户端发送的数据长度。 | 437 438**返回：** 439 4400 - 成功. 441 442返回值为0表示执行成功。返回错细信息可以查看**OH_Websocket_ErrCode**。 443 444**Permission：** 445 446ohos.permission.INTERNET 447 448## 变量说明 449 450 451### data 452 453``` 454uint8_t* NetStack_CertBlob::data 455``` 456 457**描述** 458 459证书内容。 460 461 462### size 463 464``` 465uint32_t NetStack_CertBlob::size 466``` 467 468**描述** 469 470证书内容长度。 471 472 473### type 474 475``` 476enum NetStack_CertType NetStack_CertBlob::type 477``` 478 479**描述** 480 481证书类型。 482 483 484### code [1/3] 485 486``` 487uint32_t WebSocket_CloseResult::code 488``` 489 490**描述** 491 492关闭值。 493 494 495### code [2/3] 496 497``` 498uint32_t WebSocket_CloseOption::code 499``` 500 501**描述** 502 503关闭值。 504 505 506### code [3/3] 507 508``` 509uint32_t WebSocket_OpenResult::code 510``` 511 512**描述** 513 514websocket客户端连接成功码。 515 516 517### errorCode 518 519``` 520uint32_t WebSocket_ErrorResult::errorCode 521``` 522 523**描述** 524 525错误码。 526 527 528### errorMessage 529 530``` 531const char* WebSocket_ErrorResult::errorMessage 532``` 533 534**描述** 535 536错误的消息。 537 538 539### fieldName 540 541``` 542const char* WebSocket_Header::fieldName 543``` 544 545**描述** 546 547header头的字段名。 548 549 550### fieldValue 551 552``` 553const char* WebSocket_Header::fieldValue 554``` 555 556**描述** 557 558header头的字段内容。 559 560 561### next 562 563``` 564struct WebSocket_Header* WebSocket_Header::next 565``` 566 567**描述** 568 569header头链表的next指针。 570 571 572### onClose 573 574``` 575WebSocket_OnCloseCallback WebSocket::onClose 576``` 577 578**描述** 579 580客户端接收关闭消息的回调指针。 581 582 583### onError 584 585``` 586WebSocket_OnErrorCallback WebSocket::onError 587``` 588 589**描述** 590 591客户端接收错误消息的回调指针。 592 593 594### onMessage 595 596``` 597WebSocket_OnMessageCallback WebSocket::onMessage 598``` 599 600**描述** 601 602客户端接收消息的回调指针。 603 604 605### onOpen 606 607``` 608WebSocket_OnOpenCallback WebSocket::onOpen 609``` 610 611**描述** 612 613客户端接收连接消息的回调指针。 614 615 616### reason [1/3] 617 618``` 619const char* WebSocket_CloseResult::reason 620``` 621 622**描述** 623 624关闭原因。 625 626 627### reason [2/3] 628 629``` 630const char* WebSocket_CloseOption::reason 631``` 632 633**描述** 634 635关闭原因。 636 637 638### reason [3/3] 639 640``` 641const char* WebSocket_OpenResult::reason 642``` 643 644**描述** 645 646websocket客户端连接原因。 647 648 649### requestOptions 650 651``` 652WebSocket_RequestOptions WebSocket::requestOptions 653``` 654 655**描述** 656 657客户端建立连接请求内容。