本文介绍了CoAP连接物联网平台HAL相关的接口。

HAL_DTLSSession_create

  • 原型:
    DTLSContext *HAL_DTLSSession_create(coap_dtls_options_t  *p_options);
  • 接口说明:调用此接口通过参数p_options指定的证书、服务器地址和端口建立DTLS连接,获取DTLS会话句柄。
  • 参数说明:
    参数 数据类型 方向 说明
    p_options coap_dtls_options_t * 输入 指向coap_dtls_options_t结构体类型选项数据的指针。
    coap_dtls_options_t结构:
    typedef struct {
        unsigned char             *p_ca_cert_pem;       // 指向PEM编码的X.509证书的指针
        char                      *p_host;              // 指向DTLS服务器网络地址的指针
        unsigned short             port;                // DTLS服务器端口
    } coap_dtls_options_t;    
  • 返回结果说明:
    返回结果 说明
    context DTLS会话句柄。

HAL_DTLSSession_read

  • 原型:
    unsigned int HAL_DTLSSession_read(DTLSContext       *context,
                                      unsigned char     *p_data,
                                      unsigned int      *p_datalen,
                                      unsigned int      timeout_ms);
  • 接口说明:调用此接口从指定DTLS连接中读取数据。此接口为同步接口,若超前读取到数据时立即返回,否则在超时时间到时解除阻塞并返回。
  • 参数说明:
    参数 数据类型 方向 说明
    context DTLSContext * 输入 DTLS会话句柄。
    p_data unsigned char * 输出 指向接收缓冲区的指针。
    p_datalen unsigned int * 输出 指向接收数据长度变量的指针。
    timeout_ms unsigned int 输入 超时时间。
  • 返回结果说明:
    返回结果 说明
    =0 操作成功。
    >0 操作失败。

HAL_DTLSSession_write

  • 原型:
    unsigned int HAL_DTLSSession_write(DTLSContext          *context,
                                       const unsigned char  *p_data,
                                       unsigned int         *p_datalen);
  • 接口说明:调用此接口向指定DTLS连接写入数据。
  • 参数说明:
    参数 数据类型 方向 说明
    context DTLSContext * 输入 DTLS会话句柄。
    p_data unsigned char * 输入 指向发送数据缓冲区的指针。
    p_datalen unsigned int * 输入 指向发送数据长度变量的指针,用于指定发送字节长度。
  • 返回结果说明:
    返回结果 说明
    =0 操作成功。
    >0 操作失败。

HAL_UDP_close_without_connect

  • 原型:
    int HAL_UDP_close_without_connect(intptr_t sockfd);
  • 接口说明:调用此接口销毁sockfd指定的UDP socket,释放资源。
  • 参数说明:
    参数 数据类型 方向 说明
    sockfd intptr_t 输入 UDP socket句柄。
  • 返回结果说明:
    返回结果 说明
    <0 操作失败。
    =0 操作成功。

HAL_UDP_create

  • 原型:
    intptr_t HAL_UDP_create(_IN_ char *host, _IN_ unsigned short port);   
  • 接口说明:调用此接口建立指定目的地址和目的端口的UDP连接。
  • 参数说明:
    参数 数据类型 方向 说明
    host const char * 输入 UDP目的地址。
    port unsigned short 输入 UDP目的端口。
  • 返回结果说明:
    返回结果 说明
    <0 创建失败。
    ≥0 创建成功,返回结果为UDP socket句柄。

HAL_UDP_read

  • 原型:
    int HAL_UDP_read(
                _IN_ intptr_t p_socket,
                _IN_ unsigned char *p_data,
                _IN_ unsigned int datalen);    
  • 接口说明:调用此接口从指定UDP连接中读取数据,此接口为阻塞接口。
  • 参数说明:
    参数 数据类型 方向 说明
    p_socket intptr_t 输入 读取数据所用的socket。
    p_data char * 输入 存放结果的指针。
    datalen int 输入 待读取数据的长度。
  • 返回结果说明:
    返回结果 说明
    <0 UDP连接出现错误。
    =0 发送成功。
    >0 读取到的数据字节数。

HAL_UDP_readTimeout

  • 原型:
    int HAL_UDP_readTimeout(
                _IN_ intptr_t p_socket,
                _OU_ unsigned char *p_data,
                _IN_ unsigned int datalen,
                _IN_ unsigned int timeout_ms);
  • 接口说明:调用此接口从指定的UDP句柄读取指定长度数据到缓冲区,阻塞时间不超过指定时长,若读取到指定长度数据完需立即返回。
    注意 调用该接口之前需要调用HAL_UDP_connect()设置好源地址和端口。
  • 参数说明:
    参数 数据类型 方向 说明
    p_socket intptr_t 输入 读取数据所用的socket。
    p_data char * 输出 存放结果的指针。
    datalen int 输入 预期读取数据的长度。
    timeout_ms int 输入 超时时间。
  • 返回结果说明:
    返回结果 说明
    >0 读取数据的长度。
    0 文件末尾。
    -1 无效参数。
    -2 超时时间内未接收到任何数据。
    -3 会话在读取数据前被中断。
    -4 UDP连接错误。

HAL_UDP_recv

  • 原型:
    int HAL_UDP_recv(_IN_ intptr_t sockfd,
                     _OU_ unsigned char *p_data,
                     _IN_ unsigned int datalen,
                     _IN_ unsigned int timeout_ms);
  • 接口说明:调用此接口从指定的UDP句柄接收指定长度数据到缓冲区,阻塞时间不超过指定时长,且指定长度若接收完需提前返回。
    注意 调用该接口之前需要调用HAL_UDP_connect()设置好源地址和端口。
  • 参数说明:
    参数 数据类型 方向 说明
    sockfd intptr_t 输入 UDP socket句柄。
    p_data unsigned char * 输出 指向数据接收缓冲区的指针。
    datalen unsigned int 输入 接收缓冲区的字节大小。
    timeout_ms unsigned int 输入 阻塞的超时时间,单位ms。
  • 返回值说明:
    说明
    <0 接收过程中出现错误或异常。
    =0 在指定的timeout_ms时间内,没有接收到任何数据。
    >0 在指定的timeout_ms时间内,实际接收到的数据字节数。

HAL_UDP_send

  • 原型:
    int HAL_UDP_sendto(_IN_ intptr_t          sockfd,
                       _IN_ const NetworkAddr *p_remote,
                       _IN_ const unsigned char *p_data,
                       _IN_ unsigned int datalen,
                       _IN_ unsigned int timeout_ms);
  • 接口说明:调用此接口向指定的UDP句柄发送指定缓冲区的指定长度,阻塞时间不超过指定时长,且指定长度若发送完需提前返回。
    注意 调用该接口之前需要调用HAL_UDP_connect()设置好目的地址和端口。
  • 参数说明:
    参数 数据类型 方向 说明
    sockfd intptr_t 输入 UDP socket句柄。
    p_data const unsigned char * 输入 指数据发送缓冲区的指针。
    datalen unsigned int 输入 待发送数据的字节长度。
    timeout_ms unsigned int 输入 阻塞的超时时间,单位ms。
  • 返回结果说明:
    返回结果 说明
    <0 发送过程中出现错误或异常。
    =0 在指定的timeout_ms时间内,没有任何数据发送成功。
    >0 在指定的timeout_ms时间内,实际发送的数据字节数。

HAL_UDP_write

  • 原型:
    int HAL_UDP_write(
                _IN_ intptr_t p_socket,
                _IN_ const unsigned char *p_data,
                _IN_ unsigned int datalen);
  • 接口说明:调用此接口向指定UDP句柄写入指定字节长度的数据。
  • 参数说明:
    参数 数据类型 方向 说明
    p_socket intptr_t 输入 用于标识连接的描述符。
    p_data const unsigned char * 输入 指向数据发送缓冲区的指针。
    datalen unsigned int 输入 预计写入数据的字节长度。
  • 返回结果说明:
    返回结果 说明
    <0 UDP连接发生错误。
    =0 EOF,文件已结束。
    >0 实际写入的字节数。