1# Netstack 2 3 4## Overview 5 6Provides C APIs for the network protocol stack module. 7 8**Since**: 11 9 10 11## Summary 12 13 14### File 15 16| Name| Description| 17| -------- | -------- | 18| [net_ssl_c.h](net__ssl__c_8h.md) | Defines C APIs for the SSL/TLS certificate chain verification module.| 19| [net_ssl_c_type.h](net__ssl__c__type_8h.md) | Defines data structures for the C APIs of the SSL/TLS certificate chain verification module.| 20| [net_websocket.h](net__websocket_8h.md) | Defines C APIs for the WebSocket client module.| 21| [net_websocket_type.h](net__websocket__type_8h.md) | Defines data structures for the C APIs of the WebSocket client module.| 22 23 24### Structs 25 26| Name| Description| 27| -------- | -------- | 28| [NetStack_CertBlob](_net_stack___cert_blob.md) | Certificate data structure.| 29| [WebSocket_CloseResult](_web_socket___close_result.md) | Parameters for the connection closure received by the WebSocket client. | 30| [WebSocket_CloseOption](_web_socket___close_option.md) | Parameters for the proactive connection closure initiated by the WebSocket client. | 31| [WebSocket_ErrorResult](_web_socket___error_result.md) | Parameters for the connection error received by the WebSocket client. | 32| [WebSocket_OpenResult](_web_socket___open_result.md) | Parameters for the connection success received by the WebSocket client. | 33| [WebSocket_Header](_web_socket___header.md) | Header linked list added to the WebSocket client. | 34| [WebSocket_RequestOptions](_web_socket___request_options.md) | Parameters for the connection between the WebSocket client and server. | 35| [WebSocket](_web_socket.md) | WebSocket client structure. | 36 37 38### Types 39 40| Name| Description| 41| -------- | -------- | 42| (\* [WebSocket_OnOpenCallback](#websocket_onopencallback)) (struct [WebSocket](_web_socket.md) \*client, [WebSocket_OpenResult](_web_socket___open_result.md) openResult) | Callback invoked when the WebSocket client receives an **open** message. | 43| (\* [WebSocket_OnMessageCallback](#websocket_onmessagecallback)) (struct [WebSocket](_web_socket.md) \*client, char \*data, uint32_t length) | Callback invoked when the WebSocket client receives data. | 44| (\* [WebSocket_OnErrorCallback](#websocket_onerrorcallback)) (struct [WebSocket](_web_socket.md) \*client, [WebSocket_ErrorResult](_web_socket___error_result.md) errorResult) | Callback invoked when the WebSocket client receives an error message. | 45| (\* [WebSocket_OnCloseCallback](#websocket_onclosecallback)) (struct [WebSocket](_web_socket.md) \*client, [WebSocket_CloseResult](_web_socket___close_result.md) closeResult) | Callback invoked when the WebSocket client receives a **close** message. | 46 47### Enums 48 49| Name| Description| 50| -------- | -------- | 51| [NetStack_CertType](#netstack_certtype) { <br>NetStack_CERT_TYPE_PEM = 0, <br>NetStack_CERT_TYPE_DER = 1, <br>NetStack_CERT_TYPE_INVALID <br>} | Certificate type enums.| 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 error codes. | 53 54### Functions 55 56| Name| Description| 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) | Constructor used to create an OH_NetStack_WebsocketClient instance. | 59| [OH_WebSocketClient_AddHeader](#oh_websocketclient_addheader) (struct [WebSocket](_web_socket.md) \*client, struct [WebSocket_Header](_web_socket___header.md) header) | Adds the header information to the 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) | Connects the client to the server. | 61| [OH_WebSocketClient_Send](#oh_websocketclient_send) (struct [WebSocket](_web_socket.md) \*client, char \*data, size_t length) | Sends data from the client to the server. | 62| [OH_WebSocketClient_Close](#oh_websocketclient_close) (struct [WebSocket](_web_socket.md) \*client, struct [WebSocket_CloseOption](_web_socket___close_option.md) options) | Lets the WebSocket client proactively close the connection. | 63| [OH_WebSocketClient_Destroy](#oh_websocketclient_destroy) (struct [WebSocket](_web_socket.md) \*client) | Releases the context and resources of the WebSocket connection. | 64 65### Variables 66 67| Name| Description| 68| -------- | -------- | 69| [NetStack_CertBlob::type](#type) | Certificate type.| 70| [NetStack_CertBlob::size](#size) | Certificate content length.| 71| [NetStack_CertBlob::data](#data) | Certificate content.| 72| [WebSocket_CloseResult::code](#code-13) | Error code for the connection closure. | 73| [WebSocket_CloseResult::reason](#reason-13) | Error cause for the connection closure. | 74| [WebSocket_CloseOption::code](#code-23) | Error code for the connection closure. | 75| [WebSocket_CloseOption::reason](#reason-23) | Error cause for the connection closure. | 76| [WebSocket_ErrorResult::errorCode](#errorcode) | Error code. | 77| [WebSocket_ErrorResult::errorMessage](#errormessage) | Error message. | 78| [WebSocket_OpenResult::code](#code-33) | Connection success code for the WebSocket client. | 79| [WebSocket_OpenResult::reason](#reason-33) | Connection reason for the WebSocket client. | 80| [WebSocket_Header::fieldName](#fieldname) | Header field name. | 81| [WebSocket_Header::fieldValue](#fieldvalue) | Header field content. | 82| [WebSocket_Header](_web_socket___header.md) \* [WebSocket_Header::next](#next) | Next pointer of the header linked list. | 83| [WebSocket_Header](_web_socket___header.md) \* WebSocket_RequestOptions::headers | Header information.| 84| [WebSocket_OnOpenCallback](#websocket_onopencallback)[WebSocket::onOpen](#onopen) | Pointer to the callback invoked when the WebSocket client receives a connection message. | 85| [WebSocket_OnMessageCallback](#websocket_onmessagecallback)[WebSocket::onMessage](#onmessage) | Pointer to the callback invoked when the WebSocket client receives a message. | 86| [WebSocket_OnErrorCallback](#websocket_onerrorcallback)[WebSocket::onError](#onerror) | Pointer to the callback invoked when the WebSocket client receives an error message. | 87| [WebSocket_OnCloseCallback](#websocket_onclosecallback)[WebSocket::onClose](#onclose) | Pointer to the callback invoked when the WebSocket client receives a **close** message. | 88| [WebSocket_RequestOptions](_web_socket___request_options.md)[WebSocket::requestOptions](#requestoptions) | Content of the request for establishing a connection on the client.| 89 90 91## Type Description 92 93 94### WebSocket_OnCloseCallback 95 96``` 97typedef void(* WebSocket_OnCloseCallback) (struct WebSocket *client, WebSocket_CloseResult closeResult) 98``` 99**Description** 100Callback invoked when the WebSocket client receives a **close** message. 101 102**Since**: 11 103 104**Parameters** 105 106| Name| Description| 107| -------- | -------- | 108| client | WebSocket client. | 109| closeResult | Content of the close message received by the WebSocket client. | 110 111 112### WebSocket_OnErrorCallback 113 114``` 115typedef void(* WebSocket_OnErrorCallback) (struct WebSocket *client, WebSocket_ErrorResult errorResult) 116``` 117**Description** 118Callback invoked when the WebSocket client receives an error message. 119 120**Since**: 11 121 122**Parameters** 123 124| Name| Description| 125| -------- | -------- | 126| client | WebSocket client. | 127| errorResult | Content of the error message received by the WebSocket client. | 128 129 130### WebSocket_OnMessageCallback 131 132``` 133typedef void(* WebSocket_OnMessageCallback) (struct WebSocket *client, char *data, uint32_t length) 134``` 135**Description** 136Callback invoked when the WebSocket client receives data. 137 138**Since**: 11 139 140**Parameters** 141 142| Name| Description| 143| -------- | -------- | 144| client | WebSocket client. | 145| data | Data received by the WebSocket client. | 146| length | Length of the data received by the WebSocket client. | 147 148 149### WebSocket_OnOpenCallback 150 151``` 152typedef void(* WebSocket_OnOpenCallback) (struct WebSocket *client, WebSocket_OpenResult openResult) 153``` 154**Description** 155Callback invoked when the WebSocket client receives an **open** message. 156 157**Since**: 11 158 159**Parameters** 160 161| Name| Description| 162| -------- | -------- | 163| client | WebSocket client. | 164| openResult | Content of the connection setup message received by the WebSocket client. | 165 166 167 168## Enum Description 169 170 171### NetStack_CertType 172 173``` 174enum NetStack_CertType 175``` 176 177**Description** 178 179Certificate type enums. 180 181**Since**: 11 182 183| Value| Description| 184| -------- | -------- | 185| NetStack_CERT_TYPE_PEM | PEM certificate.| 186| NetStack_CERT_TYPE_DER | DER certificate.| 187| NetStack_CERT_TYPE_INVALID | Invalid certificate.| 188 189 190### WebSocket_ErrCode 191 192``` 193enum WebSocket_ErrCode 194``` 195**Description** 196WebSocket error codes. 197 198**Since**: 11 199 200| Value| Description| 201| -------- | -------- | 202| WEBSOCKET_OK | Execution success.| 203| E_BASE | Base error code.| 204| WEBSOCKET_CLIENT_NULL | WebSocket is null.| 205| WEBSOCKET_CLIENT_NOT_CREATED | WebSocket is not created.| 206| WEBSOCKET_CONNECTION_ERROR | An error occurs while connecting the WebSocket client.| 207| WEBSOCKET_CONNECTION_PARSE_URL_ERROR | An error occurs while parsing WebSocket connection parameters.| 208| WEBSOCKET_CONNECTION_NO_MEMORY | The memory is insufficient for creating a context during WebSocket connection setup.| 209| WEBSOCKET_CONNECTION_CLOSED_BY_PEER | The WebSocket connection is closed during initialization.| 210| WEBSOCKET_DESTROYED | The WebSocket connection is destroyed.| 211| WEBSOCKET_PROTOCOL_ERROR | An incorrect protocol is used for WebSocket connection.| 212| WEBSOCKET_SEND_NO_MEMORY | The memory for the WebSocket client to send data is insufficient.| 213| WEBSOCKET_SEND_DATA_NULL | The data sent by the WebSocket client is null.| 214| WEBSOCKET_DATA_LENGTH_EXCEEDED | The length of the data sent by the WebSocket client exceeds the limit.| 215| WEBSOCKET_QUEUE_LENGTH_EXCEEDED | The queue length of the data sent by the WebSocket client exceeds the limit.| 216| WEBSOCKET_NO_CLIENT_CONTEXT | The context of the WebSocket client is null.| 217| WEBSOCKET_NO_HEADER_CONTEXT | The header of the WebSocket client is abnormal.| 218| WEBSOCKET_HEADER_EXCEEDED | The header of the WebSocket client exceeds the limit.| 219| WEBSOCKET_NO_CONNECTION | The WebSocket client is not connected.| 220| WEBSOCKET_NO_CONNECTION_CONTEXT | The WebSocket client does not have the connection context.| 221 222 223## Function Description 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**Description** 233 234Verifies the certificate chain. 235 236**System capability**: SystemCapability.Communication.NetStack 237 238**Since**: 11 239 240**Parameters** 241 242| Name| Description| 243| -------- | -------- | 244| cert | Certificate to be verified.| 245| caCert | Certificate specified by the user. If this parameter is left blank, the preset certificate is used for verification.| 246 247**Returns** 248 249**0**: success. 250 251**2305001**: unknown error. 252 253**2305002**: Failed to obtain the issuer certificate. 254 255**2305003**: Failed to obtain the certificate revocation list (CRL). 256 257**2305004**: Failed to decrypt the certificate signature. 258 259**2305005**: Failed to decrypt the CRL signature. 260 261**2305006**: Failed to decode the issuer public key. 262 263**2305007**: Failed to sign the certificate. 264 265**2305008**: Failed to sign the CRL. 266 267**2305009**: The certificate has not taken effect. 268 269**2305010**: The certificate has expired. 270 271**2305011**: The CRL has not taken effect. 272 273**2305012**: The CRL has expired. 274 275**2305023**: The certificate has been revoked. 276 277**2305024**: The certificate authority (CA) is invalid. 278 279**2305027**: The certificate is untrusted. 280 281### OH_WebSocketClient_AddHeader() 282 283``` 284int OH_WebSocketClient_AddHeader (struct WebSocket * client, struct WebSocket_Header header ) 285``` 286**Description** 287Adds the header information to the client request. 288 289**System capability**: SystemCapability.Communication.NetStack 290 291**Since**: 11 292 293**Parameters** 294 295| Name| Description| 296| -------- | -------- | 297| client | Pointer to the WebSocket client. | 298| header | Header information. | 299 300**Returns** 301 302Returns **0** if the operation is successful. For details about error codes, see **OH_Websocket_ErrCode**. 303 304**Required Permissions** 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**Description** 315Lets the WebSocket client proactively close the connection. 316 317**System capability**: SystemCapability.Communication.NetStack 318 319**Since**: 11 320 321**Parameters** 322 323| Name| Description| 324| -------- | -------- | 325| client | WebSocket client. | 326| url | IP address for the WebSocket client to connect to the server. | 327| options | Optional parameters for the connection closure. | 328 329**Returns** 330 331Returns **0** if the operation is successful. For details about error codes, see **OH_Websocket_ErrCode**. 332 333**Required Permissions** 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**Description** 344Connects the WebSocket client to the server. 345 346**System capability**: SystemCapability.Communication.NetStack 347 348**Since**: 11 349 350**Parameters** 351 352| Name| Description| 353| -------- | -------- | 354| client | Pointer to the WebSocket client. | 355| url | IP address for the WebSocket client to connect to the server. | 356| options | Optional parameters for connection. | 357 358**Returns** 359 360Returns **0** if the operation is successful. For details about error codes, see **OH_Websocket_ErrCode**. 361 362**Required Permissions** 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**Description** 373Constructor used to create an **OH_NetStack_WebsocketClient** instance. 374 375**System capability**: SystemCapability.Communication.NetStack 376 377**Since**: 11 378 379**Parameters** 380 381| Name| Description| 382| -------- | -------- | 383| onMessage | Callback invoked when the WebSocket client receives a message. | 384| onClose | Callback invoked when the WebSocket client receives a **close** message. | 385| onError | Callback invoked when the WebSocket client receives an **error** message. | 386| onOpen | Callback invoked when the WebSocket client receives an **open** message. | 387 388**Returns** 389 390Returns the pointer to the WebSocket client if the operation is successful; returns NULL otherwise. 391 392**Required Permissions** 393 394ohos.permission.INTERNET 395 396 397### OH_WebSocketClient_Destroy() 398 399``` 400int OH_WebSocketClient_Destroy (struct WebSocket * client) 401``` 402**Description** 403Releases the context and resources of the WebSocket connection. 404 405**System capability**: SystemCapability.Communication.NetStack 406 407**Since**: 11 408 409**Parameters** 410 411| Name| Description| 412| -------- | -------- | 413| client | WebSocket client. | 414 415**Returns** 416 417Returns **0** if the operation is successful. For details about error codes, see **OH_Websocket_ErrCode**. 418 419**Required Permissions** 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**Description** 430Sends data from the WebSocket client to the server. 431 432**System capability**: SystemCapability.Communication.NetStack 433 434**Since**: 11 435 436**Parameters** 437 438| Name| Description| 439| -------- | -------- | 440| client | WebSocket client. | 441| data | Data sent by the WebSocket client. | 442| length | Length of the data sent by the WebSocket client. | 443 444**Returns** 445 446Returns **0** if the operation is successful. For details about error codes, see **OH_Websocket_ErrCode**. 447 448**Required Permissions** 449 450ohos.permission.INTERNET 451 452## Variable Description 453 454 455### data 456 457``` 458uint8_t* NetStack_CertBlob::data 459``` 460 461**Description** 462 463Certificate content. 464 465 466### size 467 468``` 469uint32_t NetStack_CertBlob::size 470``` 471 472**Description** 473 474Certificate content length. 475 476 477### type 478 479``` 480enum NetStack_CertType NetStack_CertBlob::type 481``` 482 483**Description** 484 485Certificate type. 486 487 488### code [1/3] 489 490``` 491uint32_t WebSocket_CloseResult::code 492``` 493 494**Description** 495 496Error code for the connection closure. 497 498 499### code [2/3] 500 501``` 502uint32_t WebSocket_CloseOption::code 503``` 504 505**Description** 506 507Error code for the connection closure. 508 509 510### code [3/3] 511 512``` 513uint32_t WebSocket_OpenResult::code 514``` 515 516**Description** 517 518Connection success code for the WebSocket client. 519 520 521### errorCode 522 523``` 524uint32_t WebSocket_ErrorResult::errorCode 525``` 526 527**Description** 528 529Error code. 530 531 532### errorMessage 533 534``` 535const char* WebSocket_ErrorResult::errorMessage 536``` 537 538**Description** 539 540Error message. 541 542 543### fieldName 544 545``` 546const char* WebSocket_Header::fieldName 547``` 548 549**Description** 550 551Header field name. 552 553 554### fieldValue 555 556``` 557const char* WebSocket_Header::fieldValue 558``` 559 560**Description** 561 562Header field content. 563 564 565### next 566 567``` 568struct WebSocket_Header* WebSocket_Header::next 569``` 570 571**Description** 572 573Next pointer of the header linked list. 574 575 576### onClose 577 578``` 579WebSocket_OnCloseCallback WebSocket::onClose 580``` 581 582**Description** 583 584Pointer to the callback invoked when the WebSocket client receives a close message. 585 586 587### onError 588 589``` 590WebSocket_OnErrorCallback WebSocket::onError 591``` 592 593**Description** 594 595Pointer to the callback invoked when the WebSocket client receives an error message. 596 597 598### onMessage 599 600``` 601WebSocket_OnMessageCallback WebSocket::onMessage 602``` 603 604**Description** 605 606Pointer to the callback invoked when the WebSocket client receives a message. 607 608 609### onOpen 610 611``` 612WebSocket_OnOpenCallback WebSocket::onOpen 613``` 614 615**Description** 616 617Pointer to the callback invoked when the WebSocket client receives a connection message. 618 619 620### reason [1/3] 621 622``` 623const char* WebSocket_CloseResult::reason 624``` 625 626**Description** 627 628Error cause for the connection closure. 629 630 631### reason [2/3] 632 633``` 634const char* WebSocket_CloseOption::reason 635``` 636 637**Description** 638 639Error cause for the connection closure. 640 641 642### reason [3/3] 643 644``` 645const char* WebSocket_OpenResult::reason 646``` 647 648**Description** 649 650Connection reason for the WebSocket client. 651 652 653### requestOptions 654 655``` 656WebSocket_RequestOptions WebSocket::requestOptions 657``` 658 659**Description** 660 661Options of the connection request. 662