Netstack
概述
为网络协议栈模块提供C接口。
起始版本： 11
汇总
文件
| 名称 | 描述 |
|---|---|
| net_ssl_c.h | 为SSL/TLS证书链校验模块定义C接口。 |
| net_ssl_c_type.h | 定义SSL/TLS证书链校验模块的C接口需要的数据结构。 |
| net_websocket.h | 为websocket客户端模块定义C接口。 |
| net_websocket_type.h | 定义websocket客户端模块的C接口需要的数据结构。 |
结构体
| 名称 | 描述 |
|---|---|
| NetStack_CertBlob | 证书数据结构体。 |
| WebSocket_CloseResult | websocket客户端来自服务端关闭的参数。 |
| WebSocket_CloseOption | websocket客户端主动关闭的参数。 |
| WebSocket_ErrorResult | websocket客户端来自服务端连接错误的参数。 |
| WebSocket_OpenResult | websocket客户端来自服务端连接成功的参数。 |
| WebSocket_Header | websocket客户端增加header头的链表节点。 |
| WebSocket_RequestOptions | websocket客户端和服务端建立连接的参数。 |
| WebSocket | websocket客户端结构体。 |
类型定义
| 名称 | 描述 |
|---|---|
| (* WebSocket_OnOpenCallback) (struct WebSocket *client, WebSocket_OpenResult openResult) | websocket客户端接收open消息的回调函数定义。 |
| (* WebSocket_OnMessageCallback) (struct WebSocket *client, char *data, uint32_t length) | websocket客户端接收数据的回调函数定义。 |
| (* WebSocket_OnErrorCallback) (struct WebSocket *client, WebSocket_ErrorResult errorResult) | websocket客户端接收error错误消息的回调函数定义。 |
| (* WebSocket_OnCloseCallback) (struct WebSocket *client, WebSocket_CloseResult closeResult) | websocket客户端接收close消息的回调函数定义。 |
枚举
| 名称 | 描述 |
|---|---|
| NetStack_CertType { NetStack_CERT_TYPE_PEM = 0, NetStack_CERT_TYPE_DER = 1, NetStack_CERT_TYPE_INVALID } |
证书类型枚举。 |
| 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错误码。 |
函数
| 名称 | 描述 |
|---|---|
| OH_WebSocketClient_Constructor (WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage, WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose) | Websocket客户端的构造函数。 |
| OH_WebSocketClient_AddHeader (struct WebSocket *client, struct WebSocket_Header header) | 将header头信息添加到client客户端request中。 |
| OH_WebSocketClient_Connect (struct WebSocket *client, const char *url, struct WebSocket_RequestOptions options) | 客户端连接服务端。 |
| OH_WebSocketClient_Send (struct WebSocket *client, char *data, size_t length) | 客户端向服务端发送数据。 |
| OH_WebSocketClient_Close (struct WebSocket *client, struct WebSocket_CloseOption options) | 客户端主动关闭websocket连接。 |
| OH_WebSocketClient_Destroy (struct WebSocket *client) | 释放websocket连接上下文和资源。 |
变量
| 名称 | 描述 |
|---|---|
| NetStack_CertBlob::type | 证书类型。 |
| NetStack_CertBlob::size | 证书内容长度。 |
| NetStack_CertBlob::data | 证书内容。 |
| WebSocket_CloseResult::code | 关闭值。 |
| WebSocket_CloseResult::reason | 关闭原因。 |
| WebSocket_CloseOption::code | 关闭值。 |
| WebSocket_CloseOption::reason | 关闭原因。 |
| WebSocket_ErrorResult::errorCode | 错误码。 |
| WebSocket_ErrorResult::errorMessage | 错误的消息。 |
| WebSocket_OpenResult::code | websocket客户端连接成功码。 |
| WebSocket_OpenResult::reason | websocket客户端连接原因。 |
| WebSocket_Header::fieldName | header头的字段名。 |
| WebSocket_Header::fieldValue | header头的字段内容。 |
| WebSocket_Header * WebSocket_Header::next | header头链表的next指针。 |
| WebSocket_Header * WebSocket_RequestOptions::headers | header头信息。 |
| WebSocket_OnOpenCallback WebSocket::onOpen | 客户端接收连接消息的回调指针。 |
| WebSocket_OnMessageCallback WebSocket::onMessage | 客户端接收消息的回调指针。 |
| WebSocket_OnErrorCallback WebSocket::onError | 客户端接收错误消息的回调指针。 |
| WebSocket_OnCloseCallback WebSocket::onClose | 客户端接收关闭消息的回调指针。 |
| WebSocket_RequestOptions WebSocket::requestOptions | 客户端建立连接请求内容。 |
类型定义说明
WebSocket_OnCloseCallback
typedef void(* WebSocket_OnCloseCallback) (struct WebSocket *client, WebSocket_CloseResult closeResult)
描述 websocket客户端接收close消息的回调函数定义
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | websocket客户端 |
| closeResult | websocket客户端接收关闭消息的内容 |
WebSocket_OnErrorCallback
typedef void(* WebSocket_OnErrorCallback) (struct WebSocket *client, WebSocket_ErrorResult errorResult)
描述 websocket客户端接收error错误消息的回调函数定义
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | websocket客户端 |
| errorResult | websocket客户端接收连接错误消息的内容 |
WebSocket_OnMessageCallback
typedef void(* WebSocket_OnMessageCallback) (struct WebSocket *client, char *data, uint32_t length)
描述 websocket客户端接收数据的回调函数定义
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | websocket客户端 |
| data | websocket客户端接收的数据 |
| length | websocket客户端接收的数据长度 |
WebSocket_OnOpenCallback
typedef void(* WebSocket_OnOpenCallback) (struct WebSocket *client, WebSocket_OpenResult openResult)
描述 websocket客户端接收open消息的回调函数定义
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | websocket客户端 |
| openResult | websocket客户端接收建立连接消息的内容 |
枚举类型说明
NetStack_CertType
enum NetStack_CertType
描述
证书类型枚举。
起始版本： 11
| 枚举值 | 描述 |
|---|---|
| NetStack_CERT_TYPE_PEM | PEM证书类型。 |
| NetStack_CERT_TYPE_DER | DER证书类型。 |
| NetStack_CERT_TYPE_INVALID | 错误证书类型。 |
WebSocket_ErrCode
enum WebSocket_ErrCode
描述 websocket错误码
起始版本： 11
| 枚举值 | 描述 |
|---|---|
| WEBSOCKET_OK | 执行成功。 |
| E_BASE | 异常错误代码的基础。 |
| WEBSOCKET_CLIENT_NULL | websocket为空。 |
| WEBSOCKET_CLIENT_NOT_CREATED | websocket未创建。 |
| WEBSOCKET_CONNECTION_ERROR | websocket客户端连接错误。 |
| WEBSOCKET_CONNECTION_PARSE_URL_ERROR | websocket客户端连接参数解析错误。 |
| WEBSOCKET_CONNECTION_NO_MEMORY | websocket客户端连接时创建上下文无内存。 |
| WEBSOCKET_CONNECTION_CLOSED_BY_PEER | 初始化时候关闭。 |
| WEBSOCKET_DESTROYED | websocket连接被销毁。 |
| WEBSOCKET_PROTOCOL_ERROR | websocket客户端连接时候协议错误。 |
| WEBSOCKET_SEND_NO_MEMORY | websocket客户端发送数据时候没有足够内存。 |
| WEBSOCKET_SEND_DATA_NULL | websocket客户端发送数据为空。 |
| WEBSOCKET_DATA_LENGTH_EXCEEDED | websocket客户端发送数据长度超限制。 |
| WEBSOCKET_QUEUE_LENGTH_EXCEEDED | websocket客户端发送数据队列长度超限制。 |
| WEBSOCKET_NO_CLIENT_CONTEXT | websocket客户端上下文为空。 |
| WEBSOCKET_NO_HEADER_CONTEXT | websocket客户端header头异常。 |
| WEBSOCKET_HEADER_EXCEEDED | websocket客户端header头超过限制。 |
| WEBSOCKET_NO_CONNECTION | websocket客户端没有连接。 |
| WEBSOCKET_NO_CONNECTION_CONTEXT | websocket客户端没有连接上下文。 |
函数说明
OH_NetStack_VerifyCertification()
uint32_t OH_NetStack_VerifyCertification (const struct NetStack_CertBlob * cert, const struct NetStack_CertBlob * caCert )
描述
证书链校验接口。
系统能力： SystemCapability.Communication.NetStack
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| cert | 用户传入的待校验证书。 |
| caCert | 用户指定的证书，若为空则以系统预置证书进行校验。 |
返回：
0 - 成功.
2305001 - 未指定的错误.
2305002 - 无法获取颁发者证书.
2305003 - 无法获取证书吊销列表（CRL）.
2305004 - 无法解密证书签名.
2305005 - 无法解密CRL签名.
2305006 - 无法解码颁发者公钥.
2305007 - 证书签名失败.
2305008 - CRL签名失败.
2305009 - 证书尚未生效.
2305010 - 证书已过期.
2305011 - CRL尚未有效.
2305012 - CRL已过期.
2305023 - 证书已被吊销.
2305024 - 证书颁发机构（CA）无效.
2305027 - 证书不受信任.
OH_WebSocketClient_AddHeader()
int OH_WebSocketClient_AddHeader (struct WebSocket * client, struct WebSocket_Header header )
描述 将header头信息添加到client客户端request中。
系统能力： SystemCapability.Communication.NetStack
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | 客户端指针。 |
| header | header头信息。 |
返回：
返回值为0表示执行成功。返回错细信息可以查看OH_Websocket_ErrCode。
OH_WebSocketClient_Close()
int OH_WebSocketClient_Close (struct WebSocket * client, struct WebSocket_CloseOption options )
描述 客户端主动关闭websocket连接。
系统能力： SystemCapability.Communication.NetStack
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | 客户端。 |
| url | 客户端要连接到服务端的地址。 |
| options | 发起关闭连接的可选参数。 |
返回：
返回值为0表示执行成功。返回错细信息可以查看OH_Websocket_ErrCode。
Permission：
ohos.permission.INTERNET
OH_WebSocketClient_Connect()
int OH_WebSocketClient_Connect (struct WebSocket * client, const char * url, struct WebSocket_RequestOptions options )
描述 客户端连接服务端。
系统能力： SystemCapability.Communication.NetStack
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | 客户端指针。 |
| url | 客户端要连接到服务端的地址。 |
| options | 发起连接的可选参数。 |
返回：
返回值为0表示执行成功。返回错细信息可以查看OH_Websocket_ErrCode。
Permission：
ohos.permission.INTERNET
OH_WebSocketClient_Constructor()
struct WebSocket* OH_WebSocketClient_Constructor (WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage, WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose )
描述 Websocket客户端的构造函数。
系统能力： SystemCapability.Communication.NetStack
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| onMessage | 客户端定义的接收消息的回调函数。 |
| onClose | 客户端定义的关闭消息的回调函数。 |
| onError | 客户端定义的错误消息的回调函数。 |
| onOpen | 客户端定义的建立连接消息的回调函数。 |
返回：
成功返回客户端指针，失败返回为NULL。
OH_WebSocketClient_Destroy()
int OH_WebSocketClient_Destroy (struct WebSocket * client)
描述 释放websocket连接上下文和资源。
系统能力： SystemCapability.Communication.NetStack
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | 客户端。 |
返回：
返回值为0表示执行成功。返回错细信息可以查看OH_Websocket_ErrCode。
Permission：
ohos.permission.INTERNET
OH_WebSocketClient_Send()
int OH_WebSocketClient_Send (struct WebSocket * client, char * data, size_t length )
描述 客户端向服务端发送数据。
系统能力： SystemCapability.Communication.NetStack
起始版本： 11
参数:
| 名称 | 描述 |
|---|---|
| client | 客户端。 |
| data | 客户端发送的数据。 |
| length | 客户端发送的数据长度。 |
返回：
0 - 成功.
返回值为0表示执行成功。返回错细信息可以查看OH_Websocket_ErrCode。
Permission：
ohos.permission.INTERNET
变量说明
data
uint8_t* NetStack_CertBlob::data
描述
证书内容。
size
uint32_t NetStack_CertBlob::size
描述
证书内容长度。
type
enum NetStack_CertType NetStack_CertBlob::type
描述
证书类型。
code [1/3]
uint32_t WebSocket_CloseResult::code
描述
关闭值。
code [2/3]
uint32_t WebSocket_CloseOption::code
描述
关闭值。
code [3/3]
uint32_t WebSocket_OpenResult::code
描述
websocket客户端连接成功码。
errorCode
uint32_t WebSocket_ErrorResult::errorCode
描述
错误码。
errorMessage
const char* WebSocket_ErrorResult::errorMessage
描述
错误的消息。
fieldName
const char* WebSocket_Header::fieldName
描述
header头的字段名。
fieldValue
const char* WebSocket_Header::fieldValue
描述
header头的字段内容。
next
struct WebSocket_Header* WebSocket_Header::next
描述
header头链表的next指针。
onClose
WebSocket_OnCloseCallback WebSocket::onClose
描述
客户端接收关闭消息的回调指针。
onError
WebSocket_OnErrorCallback WebSocket::onError
描述
客户端接收错误消息的回调指针。
onMessage
WebSocket_OnMessageCallback WebSocket::onMessage
描述
客户端接收消息的回调指针。
onOpen
WebSocket_OnOpenCallback WebSocket::onOpen
描述
客户端接收连接消息的回调指针。
reason [1/3]
const char* WebSocket_CloseResult::reason
描述
关闭原因。
reason [2/3]
const char* WebSocket_CloseOption::reason
描述
关闭原因。
reason [3/3]
const char* WebSocket_OpenResult::reason
描述
websocket客户端连接原因。
requestOptions
WebSocket_RequestOptions WebSocket::requestOptions
描述
客户端建立连接请求内容。