Netstack
Overview
Provides C APIs for the network protocol stack module.
Since: 11
Summary
File
| Name | Description |
|---|---|
| net_ssl_c.h | Defines C APIs for the SSL/TLS certificate chain verification module. |
| net_ssl_c_type.h | Defines data structures for the C APIs of the SSL/TLS certificate chain verification module. |
| net_websocket.h | Defines C APIs for the WebSocket client module. |
| net_websocket_type.h | Defines data structures for the C APIs of the WebSocket client module. |
Structs
| Name | Description |
|---|---|
| NetStack_CertBlob | Certificate data structure. |
| WebSocket_CloseResult | Parameters for the connection closure received by the WebSocket client. |
| WebSocket_CloseOption | Parameters for the proactive connection closure initiated by the WebSocket client. |
| WebSocket_ErrorResult | Parameters for the connection error received by the WebSocket client. |
| WebSocket_OpenResult | Parameters for the connection success received by the WebSocket client. |
| WebSocket_Header | Header linked list added to the WebSocket client. |
| WebSocket_RequestOptions | Parameters for the connection between the WebSocket client and server. |
| WebSocket | WebSocket client structure. |
Types
| Name | Description |
|---|---|
| (* WebSocket_OnOpenCallback) (struct WebSocket *client, WebSocket_OpenResult openResult) | Callback invoked when the WebSocket client receives an open message. |
| (* WebSocket_OnMessageCallback) (struct WebSocket *client, char *data, uint32_t length) | Callback invoked when the WebSocket client receives data. |
| (* WebSocket_OnErrorCallback) (struct WebSocket *client, WebSocket_ErrorResult errorResult) | Callback invoked when the WebSocket client receives an error message. |
| (* WebSocket_OnCloseCallback) (struct WebSocket *client, WebSocket_CloseResult closeResult) | Callback invoked when the WebSocket client receives a close message. |
Enums
| Name | Description |
|---|---|
| NetStack_CertType { NetStack_CERT_TYPE_PEM = 0, NetStack_CERT_TYPE_DER = 1, NetStack_CERT_TYPE_INVALID } |
Certificate type enums. |
| WebSocket_ErrCode { WEBSOCKET_OK = 0, E_BASE = 1000, WEBSOCKET_CLIENT_NULL = (E_BASE + 1), WEBSOCKET_CLIENT_NOT_CREATED = (E_BASE + 2), WEBSOCKET_CONNECTION_ERROR = (E_BASE + 3), WEBSOCKET_CONNECTION_PARSE_URL_ERROR = (E_BASE + 5), WEBSOCKET_CONNECTION_NO_MEMORY = (E_BASE + 6), WEBSOCKET_CONNECTION_CLOSED_BY_PEER = (E_BASE + 7), WEBSOCKET_DESTROYED = (E_BASE + 8), WEBSOCKET_PROTOCOL_ERROR = (E_BASE + 9), WEBSOCKET_SEND_NO_MEMORY = (E_BASE + 10), WEBSOCKET_SEND_DATA_NULL = (E_BASE + 11), WEBSOCKET_DATA_LENGTH_EXCEEDED = (E_BASE + 12), WEBSOCKET_QUEUE_LENGTH_EXCEEDED = (E_BASE + 13), WEBSOCKET_NO_CLIENT_CONTEXT = (E_BASE + 14), WEBSOCKET_NO_HEADER_CONTEXT = (E_BASE + 15), WEBSOCKET_HEADER_EXCEEDED = (E_BASE + 16), WEBSOCKET_NO_CONNECTION = (E_BASE + 17), WEBSOCKET_NO_CONNECTION_CONTEXT = (E_BASE + 18) } |
WebSocket error codes. |
Functions
| Name | Description |
|---|---|
| OH_WebSocketClient_Constructor (WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage, WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose) | Constructor used to create a WebSocketClient instance. |
| OH_WebSocketClient_AddHeader (struct WebSocket *client, struct WebSocket_Header header) | Adds the header information to the client request. |
| OH_WebSocketClient_Connect (struct WebSocket *client, const char *url, struct WebSocket_RequestOptions options) | Connects the client to the server. |
| OH_WebSocketClient_Send (struct WebSocket *client, char *data, size_t length) | Sends data from the client to the server. |
| OH_WebSocketClient_Close (struct WebSocket *client, struct WebSocket_CloseOption options) | Lets the WebSocket client proactively close the connection. |
| OH_WebSocketClient_Destroy (struct WebSocket *client) | Releases the context and resources of the WebSocket connection. |
Variables
| Name | Description |
|---|---|
| NetStack_CertBlob::type | Certificate type. |
| NetStack_CertBlob::size | Certificate content length. |
| NetStack_CertBlob::data | Certificate content. |
| WebSocket_CloseResult::code | Connection close code. |
| WebSocket_CloseResult::reason | Connection close reason for the WebSocket client. |
| WebSocket_CloseOption::code | Connection close code. |
| WebSocket_CloseOption::reason | Connection close reason for the WebSocket client. |
| WebSocket_ErrorResult::errorCode | Error code. |
| WebSocket_ErrorResult::errorMessage | Error message. |
| WebSocket_OpenResult::code | Connection success code for the WebSocket client. |
| WebSocket_OpenResult::reason | Connection reason for the WebSocket client. |
| WebSocket_Header::fieldName | Header field name. |
| WebSocket_Header::fieldValue | Header field content. |
| WebSocket_Header * WebSocket_Header::next | Next pointer of the header linked list. |
| WebSocket_Header * WebSocket_RequestOptions::headers | Header information. |
| WebSocket_OnOpenCallback WebSocket::onOpen | Pointer to the callback invoked when the WebSocket client receives a connection message. |
| WebSocket_OnMessageCallback WebSocket::onMessage | Pointer to the callback invoked when the WebSocket client receives a message. |
| WebSocket_OnErrorCallback WebSocket::onError | Pointer to the callback invoked when the WebSocket client receives an error message. |
| WebSocket_OnCloseCallback WebSocket::onClose | Pointer to the callback invoked when the WebSocket client receives a close message. |
| WebSocket_RequestOptions WebSocket::requestOptions | Content of the request for establishing a connection on the client. |
Type Description
WebSocket_OnCloseCallback
typedef void(* WebSocket_OnCloseCallback) (struct WebSocket *client, WebSocket_CloseResult closeResult)
Description Callback invoked when the WebSocket client receives a close message.
Since: 11
Parameters
| Name | Description |
|---|---|
| client | WebSocket client. |
| closeResult | Content of the close message received by the WebSocket client. |
WebSocket_OnErrorCallback
typedef void(* WebSocket_OnErrorCallback) (struct WebSocket *client, WebSocket_ErrorResult errorResult)
Description Callback invoked when the WebSocket client receives an error message.
Since: 11
Parameters
| Name | Description |
|---|---|
| client | WebSocket client. |
| errorResult | Content of the error message received by the WebSocket client. |
WebSocket_OnMessageCallback
typedef void(* WebSocket_OnMessageCallback) (struct WebSocket *client, char *data, uint32_t length)
Description Callback invoked when the WebSocket client receives data.
Since: 11
Parameters
| Name | Description |
|---|---|
| client | WebSocket client. |
| data | Data received by the WebSocket client. |
| length | Length of the data received by the WebSocket client. |
WebSocket_OnOpenCallback
typedef void(* WebSocket_OnOpenCallback) (struct WebSocket *client, WebSocket_OpenResult openResult)
Description Callback invoked when the WebSocket client receives an open message.
Since: 11
Parameters
| Name | Description |
|---|---|
| client | WebSocket client. |
| openResult | Content of the connection setup message received by the WebSocket client. |
Enum Description
NetStack_CertType
enum NetStack_CertType
Description
Certificate type enums.
Since: 11
| Value | Description |
|---|---|
| NetStack_CERT_TYPE_PEM | PEM certificate. |
| NetStack_CERT_TYPE_DER | DER certificate. |
| NetStack_CERT_TYPE_INVALID | Invalid certificate. |
WebSocket_ErrCode
enum WebSocket_ErrCode
Description WebSocket error codes.
Since: 11
| Value | Description |
|---|---|
| WEBSOCKET_OK | Execution success. |
| E_BASE | Base error code. |
| WEBSOCKET_CLIENT_NULL | WebSocket is null. |
| WEBSOCKET_CLIENT_NOT_CREATED | WebSocket is not created. |
| WEBSOCKET_CONNECTION_ERROR | An error occurs while connecting the WebSocket client. |
| WEBSOCKET_CONNECTION_PARSE_URL_ERROR | An error occurs while parsing WebSocket connection parameters. |
| WEBSOCKET_CONNECTION_NO_MEMORY | The memory is insufficient for creating a context during WebSocket connection setup. |
| WEBSOCKET_CONNECTION_CLOSED_BY_PEER | The WebSocket connection is closed during initialization. |
| WEBSOCKET_DESTROYED | The WebSocket connection is destroyed. |
| WEBSOCKET_PROTOCOL_ERROR | An incorrect protocol is used for WebSocket connection. |
| WEBSOCKET_SEND_NO_MEMORY | The memory for the WebSocket client to send data is insufficient. |
| WEBSOCKET_SEND_DATA_NULL | The data sent by the WebSocket client is null. |
| WEBSOCKET_DATA_LENGTH_EXCEEDED | The length of the data sent by the WebSocket client exceeds the limit. |
| WEBSOCKET_QUEUE_LENGTH_EXCEEDED | The queue length of the data sent by the WebSocket client exceeds the limit. |
| WEBSOCKET_NO_CLIENT_CONTEXT | The context of the WebSocket client is null. |
| WEBSOCKET_NO_HEADER_CONTEXT | The header of the WebSocket client is abnormal. |
| WEBSOCKET_HEADER_EXCEEDED | The header of the WebSocket client exceeds the limit. |
| WEBSOCKET_NO_CONNECTION | The WebSocket client is not connected. |
| WEBSOCKET_NO_CONNECTION_CONTEXT | The WebSocket client does not have the connection context. |
Function Description
OH_NetStack_VerifyCertification()
uint32_t OH_NetStack_VerifyCertification (const struct NetStack_CertBlob * cert, const struct NetStack_CertBlob * caCert )
Description
Verifies the certificate chain.
System capability: SystemCapability.Communication.NetStack
Since: 11
Parameters
| Name | Description |
|---|---|
| cert | Certificate to be verified. |
| caCert | Certificate specified by the user. If this parameter is left blank, the preset certificate is used for verification. |
Returns
0: success.
2305001: unknown error.
2305002: Failed to obtain the issuer certificate.
2305003: Failed to obtain the certificate revocation list (CRL).
2305004: Failed to decrypt the certificate signature.
2305005: Failed to decrypt the CRL signature.
2305006: Failed to decode the issuer public key.
2305007: Failed to sign the certificate.
2305008: Failed to sign the CRL.
2305009: The certificate has not taken effect.
2305010: The certificate has expired.
2305011: The CRL has not taken effect.
2305012: The CRL has expired.
2305023: The certificate has been revoked.
2305024: The certificate authority (CA) is invalid.
2305027: The certificate is untrusted.
OH_WebSocketClient_AddHeader()
int OH_WebSocketClient_AddHeader (struct WebSocket * client, struct WebSocket_Header header )
Description Adds the header information to the client request.
System capability: SystemCapability.Communication.NetStack
Since: 11
Parameters
| Name | Description |
|---|---|
| client | Pointer to the WebSocket client. |
| header | Header information. |
Returns
Returns 0 if the operation is successful. For details about error codes, see OH_Websocket_ErrCode.
OH_WebSocketClient_Close()
int OH_WebSocketClient_Close (struct WebSocket * client, struct WebSocket_CloseOption options )
Description Lets the WebSocket client proactively close the connection.
System capability: SystemCapability.Communication.NetStack
Since: 11
Parameters
| Name | Description |
|---|---|
| client | WebSocket client. |
| url | IP address for the WebSocket client to connect to the server. |
| options | Optional parameters for the connection closure. |
Returns
Returns 0 if the operation is successful. For details about error codes, see OH_Websocket_ErrCode.
Required Permissions
ohos.permission.INTERNET
OH_WebSocketClient_Connect()
int OH_WebSocketClient_Connect (struct WebSocket * client, const char * url, struct WebSocket_RequestOptions options )
Description Connects the WebSocket client to the server.
System capability: SystemCapability.Communication.NetStack
Since: 11
Parameters
| Name | Description |
|---|---|
| client | Pointer to the WebSocket client. |
| url | IP address for the WebSocket client to connect to the server. |
| options | Optional parameters for connection. |
Returns
Returns 0 if the operation is successful. For details about error codes, see OH_Websocket_ErrCode.
Required Permissions
ohos.permission.INTERNET
OH_WebSocketClient_Constructor()
struct WebSocket* OH_WebSocketClient_Constructor (WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage, WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose )
Description Constructor used to create a WebSocketClient instance.
System capability: SystemCapability.Communication.NetStack
Since: 11
Parameters
| Name | Description |
|---|---|
| onMessage | Callback invoked when the WebSocket client receives a message. |
| onClose | Callback invoked when the WebSocket client receives a close message. |
| onError | Callback invoked when the WebSocket client receives an error message. |
| onOpen | Callback invoked when the WebSocket client receives an open message. |
Returns
Returns the pointer to the WebSocket client if the operation is successful; returns NULL otherwise.
OH_WebSocketClient_Destroy()
int OH_WebSocketClient_Destroy (struct WebSocket * client)
Description Releases the context and resources of the WebSocket connection.
System capability: SystemCapability.Communication.NetStack
Since: 11
Parameters
| Name | Description |
|---|---|
| client | WebSocket client. |
Returns
Returns 0 if the operation is successful. For details about error codes, see OH_Websocket_ErrCode.
Required Permissions
ohos.permission.INTERNET
OH_WebSocketClient_Send()
int OH_WebSocketClient_Send (struct WebSocket * client, char * data, size_t length )
Description Sends data from the WebSocket client to the server.
System capability: SystemCapability.Communication.NetStack
Since: 11
Parameters
| Name | Description |
|---|---|
| client | WebSocket client. |
| data | Data sent by the WebSocket client. |
| length | Length of the data sent by the WebSocket client. |
Returns
Returns 0 if the operation is successful. For details about error codes, see OH_Websocket_ErrCode.
Required Permissions
ohos.permission.INTERNET
Variable Description
data
uint8_t* NetStack_CertBlob::data
Description
Certificate content.
size
uint32_t NetStack_CertBlob::size
Description
Certificate content length.
type
enum NetStack_CertType NetStack_CertBlob::type
Description
Certificate type.
code [1/3]
uint32_t WebSocket_CloseResult::code
Description
Connection close code.
code [2/3]
uint32_t WebSocket_CloseOption::code
Description
Connection close code.
code [3/3]
uint32_t WebSocket_OpenResult::code
Description
Connection success code for the WebSocket client.
errorCode
uint32_t WebSocket_ErrorResult::errorCode
Description
Error code.
errorMessage
const char* WebSocket_ErrorResult::errorMessage
Description
Error message.
fieldName
const char* WebSocket_Header::fieldName
Description
Header field name.
fieldValue
const char* WebSocket_Header::fieldValue
Description
Header field content.
next
struct WebSocket_Header* WebSocket_Header::next
Description
Next pointer of the header linked list.
onClose
WebSocket_OnCloseCallback WebSocket::onClose
Description
Pointer to the callback invoked when the WebSocket client receives a close message.
onError
WebSocket_OnErrorCallback WebSocket::onError
Description
Pointer to the callback invoked when the WebSocket client receives an error message.
onMessage
WebSocket_OnMessageCallback WebSocket::onMessage
Description
Pointer to the callback invoked when the WebSocket client receives a message.
onOpen
WebSocket_OnOpenCallback WebSocket::onOpen
Description
Pointer to the callback invoked when the WebSocket client receives a connection message.
reason [1/3]
const char* WebSocket_CloseResult::reason
Description
Connection close reason for the WebSocket client.
reason [2/3]
const char* WebSocket_CloseOption::reason
Description
Connection close reason for the WebSocket client.
reason [3/3]
const char* WebSocket_OpenResult::reason
Description
Connection reason for the WebSocket client.
requestOptions
WebSocket_RequestOptions WebSocket::requestOptions
Description
Options of the connection request.