第 3 章 - Azure RTOS NetX Duo MQTT 客户端服务说明

本章按字母顺序介绍了所有 Azure RTOS NetX Duo MQTT 客户端服务(如下所列)。

在以下 API 说明的“返回值”部分中,以粗体显示的值不受定义用于禁用 API 错误检查的 NX_DISABLE_ERROR_CHECKING 影响,而不以粗体显示的值则完全禁用。

nxd_mqtt_client_create

创建 MQTT 客户端实例

原型

UINT nxd_mqtt_client_create(
    NXD_MQTT_CLIENT *client_ptr,
    CHAR *client_name,
    CHAR *client_id,
    UINT client_id_length,
    NX_IP *ip_ptr,
    NX_PACKET_POOL
    *pool_ptr,
    VOID *stack_ptr,
    ULONG stack_size, UINT
    mqtt_thread_priority,
    VOID *memory_ptr,
    ULONG memory_size);

说明

此服务用于在指定的 IP 实例上创建 MQTT 客户端实例。 在 MQTT 连接阶段中,client_id 字符串作为客户端标识符 (ClientId) 传递给服务器。 它还创建必要的 ThreadX 资源(MQTT 客户端任务线程、互斥、事件标志组和 TCP 套接字)。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • client_name:客户端名称字符串。
  • client_id:在连接阶段中使用的客户端 ID 字符串。 MQTT 代理使用此 client_id 来唯一标识客户端。
  • client_id_length:客户端 ID 字符串的长度(以字节为单位)。
  • ip_ptr:指向 IP 实例的指针。
  • pool_ptr:指向 MQTT 客户端用于其操作的数据包池的指针。
  • stack_ptr:MQTT 客户端线程的堆栈区域。
  • stack_size:堆栈区域大小(以字节为单位)。
  • mqtt_thread_priority:MQTT 线程优先级。
  • memory_ptr:已弃用。 不再使用。
  • memory_size:已弃用。 不再使用。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功创建 MQTT 客户端。
  • NXD_MQTT_INTERNAL_ERROR (0x10004):内部逻辑错误
  • NX_PTR_ERROR (0x07):MQTT 控制块、ip_ptr 或数据包池指针无效。
  • NXD_MQTT_INVALID_PARAMETER (0x10009):will 主题字符串、will_retrain_flag 或 will_QoS 值无效。

允许调用自

线程数

示例

#define CLIENT_ID_STRING "My Test Client"

#define MQTT_THREAD_PRIORITY 2

NXD_MQTT_CLIENT my_client;
NX_IP ip_0; /* Assume ip_0 is created prior to MQTT client creation. */
NX_PACKET_POOL pool_0;/* Assume pool_0 is created prior to MQTT client creation. */
UCHAR mqtt_thread_stack[STACK_SIZE];

/* Create the MQTT Client instance on "ip_0". */
status = **nxd_mqtt_client_create**(&my_client, "my client",
    CLIENT_ID_STRING, stlren(CLIENT_ID_STRING),
    &ip_0, &pool_0, (VOID*)mqtt_thread_stack, STACK_SIZE,
    MQTT_THREAD_PRIORITY, NX_NULL, 0);

/* If status is NXD_MQTT_SUCCESS an MQTT Client instance was successfully created. */

nxd_mqtt_client_will_message_set

设置 will 消息

原型

UINT nxd_mqtt_client_will_message_set(
    NXD_MQTT_CLIENT *client_ptr,
    Const UCHAR *will_topic,
    UINT will_topic_length
    Const UCHAR *will_message,
    UINT will_message_length,
    UINT will_retain_flag,
    UINT will_QoS);

说明

此服务用于在客户端连接到服务器之前设置可选的 will 主题和 will 消息。 will 主题必须是采用 UTF-8 编码的字符串。

如果设置了 will 消息,则它会作为 CONNECT 消息的一部分传输到代理。 因此,希望使用 will 消息的应用程序必须在建立 MQTT 连接之前使用此服务。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • will_topic:采用 UTF-8 编码的 will 主题字符串。 will 主题必须存在。 调用方必须在调用 nx_mqtt_client_connect 之前保持 will_topic 字符串有效。
  • will_topic_length:will 主题字符串的字节数
  • will_message:应用程序定义的 will 消息。 如果 will 消息不是必需的,那么应用程序可以将此字段设置为 NX_NULL。
  • will_message_length:will 消息字符串的字节数。 如果 will_message 设置为 NULL,则 will_message_length 必须设置为 0。
  • will_retain_flag:服务器是否将 will 消息作为保留的消息发布。 有效值为 NX_TRUE 或 NX_FALSE。
  • will_QoS:服务器在发送 will 消息时使用的 QoS 值。 有效值为 0 或 1。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功设置 will 消息。
  • NXD_MQTT_QOS2_NOT_SUPPORTED (0x1000C):QoS 级别 2 消息不受支持。
  • NX_PTR_ERROR (0x07):MQTT 控制块无效。
  • NXD_MQTT_INVALID_PARAMETER (0x10009):will 主题字符串、will_retrain_flag 或 will_QoS 值无效。

允许调用自

线程数

示例

#define WILL_TOPIC "my_will_topic"

#define WILL_MESSAGE "my will message"

/* Create the MQTT Client instance "my_client" on "ip_0". */
status = nxd_mqtt_client_will_message_set(&my_client,
    WILL_TOPIC, STRLEN(WILL_TOPIC),
    WILL_MESSAGE, STRLEN(WILL_MESSAGE),
    NX_TRUE, 0);

/* If status is NXD_MQTT_SUCCESS the will message is properly
configured for the session. It will be transmitted to the server
during MQTT connection. */

nxd_mqtt_client_login_set

设置 MQTT 客户端登录用户名和密码

原型

UINT nxd_mqtt_client_login_set(
    NXD_MQTT_CLIENT *client_ptr,
    Const UCHAR *username,
    UINT username_length
    Const UCHAR *password,
    UINT password_length);

说明

此服务用于设置在 MQTT 连接阶段中用于登录身份验证的用户名和密码。

使用用户名和密码的 MQTT 客户端登录是可选的。 在服务器需要用户名和密码的情况下,必须在建立连接之前设置用户名和密码。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • username:采用 UTF-8 编码的用户名字符串。 调用方必须在调用 nx_mqtt_client_connect 之前保持用户名字符串有效。
  • username_length:用户名字符串的字节数
  • password:密码字符串。 如果密码不是必需的,那么可以将此字段设置为 NX_NULL。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功设置 will 消息。
  • NX_PTR_ERROR (0x07):MQTT 控制块无效。
  • NXD_MQTT_INVALID_PARAMETER (0x10009):用户名字符串或密码字符串无效。

允许调用自

线程数

示例

#define USERNAME "MY_NAME"

#define PASSWORD "MY_LOGIN_SECRET"

/* Create the MQTT Client instance "my_client" on "ip_0". */
status = nxd_mqtt_client_login_set(&my_client,
    USERNAME, STRLEN(USERNAME),
    PASSWORD, STRLEN(PASSWORD));

/* If status is NXD_MQTT_SUCCESS the username and the password 
are set for the session. This information will be 
transmitted to the server during MQTT connection. */

nxd_mqtt_client_connect

将 MQTT 客户端连接到代理

原型

UINT nxd_mqtt_client_connect(
    NXD_MQTT_CLIENT *client_ptr,
    NXD_ADDRESS *server_ip,
    UINT server_port,
    UINT keepalive, UINT clean_session,
    ULONG wait_option));

说明

此服务用于发起与代理的连接。 它首先绑定 TCP 套接字,然后建立 TCP 连接。 假定成功了,则会在启用了 MQTT“保持连接”功能的情况下创建计时器。 然后,它与 MQTT 服务器(代理)连接。

请注意,此服务创建的 MQTT 连接没有 TLS 安全保护。 若要建立安全的 MQTT 连接,应用程序应使用服务 nxd_mqtt_client_secure_connect

在连接后,如果客户端将 clean_session 设置为 NX_FALSE,那么客户端会重新传输任何存储的尚未确认的消息。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • server_ip:代理 IP 地址。
  • server_port:代理端口号。 MQTT 的默认端口定义为 NXD_MQTT_PORT (1883)。
  • keep_alive:在会话期间使用的“保持连接”值(以秒为单位)。 此值指明在代理使此客户端超时之前发送到代理的两个 MQTT 控制消息间隔的最长时间。 如果值为 0,则会禁用“保持连接”功能。
  • clean_session:服务器是否应启动此会话清理。 有效选项为 NX_TRUE 或 NX_FALSE。
  • wait_option:连接等待时间。

返回值

  • NXD_MQTT_SUCCESS (0x00):MQTT 连接成功
  • NXD_MQTT_ALREADY_CONNECTED (0x10001):客户端已连接到代理。
  • NXD_MQTT_MUTEX_FAILURE (0x10003):无法获取 MQTT 互斥
  • NXD_MQTT_INTERNAL_ERROR (0x10004):内部逻辑错误
  • NXD_MQTT_CONNECT_FAILURE (0x10005):无法连接到代理。
  • NXD_MQTT_COMMUNICATION_FAILURE (0x10007):无法向代理发送消息。
  • NXD_MQTT_SERVER_MESSAGE_FAILURE (0x10008):服务器虽然响应了但出错
  • NXD_MQTT_ERROR_UNACCEPTABLE_PROTOCOL (0x10081):服务器响应代码
  • NXD_MQTT_ERROR_IDENTIFYIER_REJECTED (0x10082):服务器响应代码
  • NXD_MQTT_ERROR_SERVER_UNAVAILABLE (0x10083):服务器响应代码
  • NXD_MQTT_ERROR_BAD_USERNAME_PASSWORD (0x10084):服务器响应代码
  • NXD_MQTT_ERROR_NOT_AUTHORIZED (0x10085):服务器响应代码
  • NX_PTR_ERROR (0x07):MQTT 控制块、ip_ptr 或数据包池指针无效

允许调用自

线程数

示例

NXD_ADDRESS broker_address;

/* Set up broker IP address */
broker_address.nxd_ip_version = 4;
broker_address.nxd_ip_address.v4 = MQTT_BROKER_ADDRESS;

/* Create the MQTT Client instance "my_client" on "ip_0". */
status = nxd_mqtt_client_connect(&my_client, &broker_address,
    NXD_MQTT_PORT,
    0, /* Turn off keepalive */
    NX_TRUE, /* Clean session flag set */
    NX_WAIT_FOREVER);

/* If status is NXD_MQTT_SUCCESS a connection to the broker is successfully established. */

nxd_mqtt_client_secure_connect

在有 TLS 安全保护的情况下将 MQTT 客户端连接到代理

原型

UINT nxd_mqtt_client_secure_connect(
    NXD_MQTT_CLIENT *client_ptr,
    NXD_ADDRESS *server_ip,
    UINT server_port,
    UINT (*tls_setup)(
        NXD_MQTT_CLIENT *,
        NX_SECURE_TLS_SESISON *,
        NX_SECURE_TLS_CERTIFICATE *,
        NX_SECURE_TLS_CERTIFICATE *),
    UINT keepalive,
    UINT connection_flag,
    UINT clean_session,
    ULONG wait_option));

说明

此服务与 nxd_mqtt_client_connect 完全相同,除了连接是通过 TLS 层(而不是 TCP)建立的。 因此,客户端与代理之间的通信是安全的。

用户定义的 tls_setup 是 MQTT 客户端在建立 MQTT 客户端连接之前使用的回叫函数。 应用程序应初始化 NetX Secure TLS,配置安全参数,并加载 TLS 握手期间使用的相关证书。 在代理的 MQTT TLS 端口(默认 TCP 端口 8883)上建立 TCP 连接后,就会发生实际的 TLS 握手。 在 TLS 握手成功后,就会通过 TLS 发送 MQTT CONNECT 控制数据包。

若要建立安全连接,则 NetX 安全 TLS 库必须可用,且 NetX Duo MQTT 客户端必须使用定义的 NX_SECURE_ENABLE 生成。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • server_ip:代理 IP 地址。
  • server_port:代理端口号。 MQTT 的默认端口定义为 NXD_MQTT_TLS_PORT (8883)。
  • tls_setup:用户提供的 TLS 设置回调函数。 调用此回叫函数可以设置 TLS 客户端连接参数。
  • keep_alive:在会话期间使用的“保持连接”值。 如果值为 0,则会禁用“保持连接”功能。
  • clean_session:服务器是否应启动此会话清理。 有效选项为 NX_TRUE 或 NX_FALSE。
  • wait_option:连接等待时间。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功通过 TLS 建立 MQTT 客户端连接。
  • NXD_MQTT_ALREADY_CONNECTED (0x10001):客户端已连接到代理。
  • NXD_MQTT_MUTEX_FAILURE (0x10003):无法获取 MQTT 互斥
  • NXD_MQTT_INTERNAL_ERROR (0x10004):内部逻辑错误
  • NXD_MQTT_CONNECT_FAILURE (0x10005):无法连接到代理。
  • NXD_MQTT_COMMUNICATION_FAILURE (0x10007):无法向代理发送消息。
  • NXD_MQTT_SERVER_MESSAGE_FAILURE (0x10008):服务器虽然响应了但显示错误消息。
  • NXD_MQTT_ERROR_UNACCEPTABLE_PROTOCOL (0x10081):服务器响应代码
  • NXD_MQTT_ERROR_IDENTIFYIER_REJECTED (0x10082):服务器响应代码
  • NXD_MQTT_ERROR_SERVER_UNAVAILABLE (0x10083):服务器响应代码
  • NXD_MQTT_ERROR_BAD_USERNAME_PASSWORD (0x10084):服务器响应代码
  • NXD_MQTT_ERROR_NOT_AUTHORIZED (0x10085):服务器响应代码
  • NX_PTR_ERROR (0x07):MQTT 控制块或服务器地址结构无效。
  • NX_INVALID_PORT (0x46):服务器端口不得为 0。
  • NXD_MQTT_INVALID_PARAMETER (0x10009):输入参数错误
  • NXD_MQTT_CLIENT_NOT_RUNNING (0x1000E):MQTT 线程还没有开始运行。

允许调用自

线程数

示例

/* TLS setup routine. This function is responsible for setting up TLS parameters.*/
UINT tls_setup_callback(NXD_MQTT_CLIENT *client_ptr,
    NX_SECURE_TLS_SESSION *session_ptr,
    NX_SECURE_TLS_CERTIFICATE *certificate_ptr,
    NX_SECURE_TLS_CERTIFICATE *trusted_certificate,
    UINT timeout)
{
/* Note this routine is simplified to highlight the
necessary steps to setup a TLS session. Each
application may employ different procedures suitable for
its TLS settings, such as cipher suite, certificates. */

/* Create a TLS session for the MQTT connection, and pass
in various crypto methods this session can use for the
initial TLS handshake. */

/* Load appropriate certificates, or set up session key for Pre-share key operation. */

/* Start the TLS session */

/* Return NX_SUCCESS if the TLS session is established. */
    return(NX_SUCCESS);
}

NXD_ADDRESS broker_address;

/* Set up broker IP address */
broker_address.nxd_ip_version = 4;
broker_address.nxd_ip_address.v4 = MQTT_BROKER_ADDRESS;

/* Create the MQTT Client instance "my_client" on "ip_0". */
status = nxd_mqtt_client_secure_connect(&my_client,
    &server_address, NXD_MQTT_TLS_PORT, tls_setup_callback,
    0, /* Turn off keepalive */
    NX_TRUE, /* Clean session set */
    NX_WAIT_FOREVER);

/* If status is NXD_MQTT_SUCCESS the MQTT Client was successfully connected to the broker via TLS. */

nxd_mqtt_client_publish

通过代理发布消息

原型

UINT nxd_mqtt_client_publish(
    NXD_MQTT_CLIENT *client_ptr,
    CHAR *topic_name,
    UINT topic_name_length,
    CHAR *message, UINT
    message_length,
    UINT retain,
    UINT QoS,
    ULONG timeout);

说明

此服务用于通过代理发布消息。 尚不支持发布 QoS 级别 2 消息。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • topic_name:要将消息发布到的主题。
  • topic_name_length:主题长度(以字节为单位)。
  • message:指向消息缓冲区的指针。
  • message_length:消息大小(以字节为单位)
  • retain:确定代理是否应保留消息。
  • QoS:所需的 QoS 值:0 或 1。
  • timeout:超时值

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功创建 MQTT 客户端
  • NXD_MQTT_INTERNAL_ERROR (0x10004):内部逻辑错误。
  • NXD_MQTT_PACKET_POOL_FAILURE (0x10006):无法从数据包池获取数据包。
  • NXD_MQTT_COMMUNICATION_FAILURE (0x10007):无法与代理通信。
  • NXD_MQTT_QOS2_NOT_SUPPORTED (0x1000C):QoS 级别 2 消息不受支持。
  • NX_PTR_ERROR (0x07):MQTT 控制块、ip_ptr 或数据包池指针无效
  • NXD_MQTT_INVALID_PARAMETER (0x10009):输入参数错误

允许调用自

线程数

示例

CHAR *topic = "temperature";
CHAR *message = "100";

/* Publish the temperature value. */
status = nxd_mqtt_client_publish(&my_client,
    topic, STRLEN(topic),
    message, STRLEN(message),
    NX_TRUE, /* Server retains message. */);
    0, /* QOS */
    NX_WAIT_FOREVER);

/* If status is NXD_MQTT_SUCCESS the message has been 
successfully sent to the broker. */

nxd_mqtt_client_subscribe

订阅主题

原型

UINT nxd_mqtt_client_subscribe(
    NXD_MQTT_CLIENT *mqtt_client_ptr,
    CHAR *topic_name,
    UINT topic_name_length,
    UINT QoS);

说明

此服务用于订阅特定主题。 尚不支持订阅 QoS 级别 2 消息。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • topic_name:要将消息发布到的主题。
  • topic_name_length:主题长度(以字节为单位)。
  • Qos:所需的 QoS 级别:0 或 1。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功订阅主题。
  • NXD_MQTT_NOT_CONNECTED (0x10002):客户端没有连接到代理。
  • NXD_MQTT_MUTEX_FAILURE (0x10003):无法获取 MQTT 互斥
  • NXD_MQTT_INTERNAL_ERROR (0x10004):内部逻辑错误
  • NXD_MQTT_COMMUNICATION_FAILURE (0x10007):无法向代理发送消息。
  • NXD_MQTT_QOS2_NOT_SUPPORTED (0x1000C):QoS 级别 2 消息不受支持。
  • NX_PTR_ERROR (0x07):MQTT 控制块、ip_ptr 或数据包池指针无效
  • NXD_MQTT_INVALID_PARAMETER (0x10009):未设置 topic_name、topic_name_length 为 0,或 QoS 值无效。

允许调用自

线程数

示例

/* Subscribe to the topic "temperature" with QoS level 0 */
CHAR *topic = "temperature";

status = nxd_mqtt_client_subscribe(&my_client, topic,
    STRLEN(topic), 0);

/* If status is NXD_MQTT_SUCCESS, the client successfully
subscribes to the topic "temperate". At this point the client
is ready for receiving messages from the broker. */

nxd_mqtt_client_unsubscribe

取消订阅主题

原型

UINT nxd_mqtt_client_unsubscribe(
    NXD_MQTT_CLIENT *mqtt_client_pr,
    CHAR *topic_name,
    UINT topic_name_length);

说明

此服务用于取消订阅主题。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • topic_name:要取消订阅的主题。
  • topic_name_length:主题长度(以字节为单位)。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功取消订阅主题。
  • NXD_MQTT_NOT_CONNECTED (0x10002):客户端没有连接到代理。
  • NXD_MQTT_MUTEX_FAILURE (0x10003):无法获取 MQTT 互斥。
  • NXD_MQTT_INTERNAL_ERROR (0x10004):内部逻辑错误
  • NXD_MQTT_COMMUNICATION_FAILURE (0x10007):无法向代理发送消息。
  • NX_PTR_ERROR (0x07):MQTT 控制块指针无效
  • NXD_MQTT_INVALID_PARAMETER (0x10009):未设置 topic_name,或 topic_name_length 为 0。

允许调用自

线程数

示例

/* Subscribe to the topic "temperature" with QoS level 0 */
CHAR *topic = "temperature";

status = nxd_mqtt_client_unsubscribe(&my_client, topic,
    STRLEN(topic));

/* If status is NXD_MQTT_SUCCESS, the client successfully
unsubscribes the topic "temperate". */

nxd_mqtt_client_receive_notify_set

设置 MQTT 消息接收通知回叫函数

原型

UINT nxd_mqtt_client_receive_notify_set(
    NXD_MQTT_CLIENT *client_ptr,
    VOID(*receive_notify)(
        NXD_MQTT_CLIENT* client_ptr,
        UINT message_count));

说明

此服务用于向 MQTT 客户端注册回叫函数。 在收到由代理发布的消息后,MQTT 客户端就会将消息存储在接收队列中。 如果设置了回叫函数,就会调用回叫函数来通知应用程序可以检索消息了。 接收通知函数需要使用指向 MQTT 客户端控制块的指针,以及指明接收队列中可用消息数的 message_count。 请注意,在接收通知与应用程序检索这些消息的间隔期间,数量可能会发生变化,因为在此间隔内可能会有新消息到达。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • receive_notify:在收到消息时调用的用户提供的回调函数。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功设置接收通知函数。
  • NX_PTR_ERROR (0x07):MQTT 控制块无效。

允许调用自

线程数

示例

/* Sample MQTT receive notify function. */

VOID my_notify_func(NXD_MQTT_CLIENT* client_ptr,
    UINT message_count)
{

/* On receiving a message, set an event flag to wake up the
application thread. The message will be received and
processed in the application thread. */
tx_event_flags_set(&mqtt_app_flag,
    MESSAGE_RECEIVED_EVENT, TX_OR);

/* All done. Return to the caller. */
    return;
}

/* Set the receive callback function. */
status = **nxd_mqtt_client_receive_notify_set**(&my_client,
    my_notify_func);

/* If status is NXD_MQTT_SUCCESS the notify function is properly set. */

nxd_mqtt_client_message_get

从代理中检索消息

原型

UINT nxd_mqtt_client_message_get(
    NXD_MQTT_CLIENT *client_ptr,
    UCHAR *topic_buffer,
    UINT topic_buffer_size,
    UINT *actual_topic_length,
    UCHAR *message_buffer,
    UINT message_buffer_size,
    UINT *actual_message_length);

说明

此服务用于检索由代理发布的消息。 所有传入消息都存储在接收队列中。 应用程序使用此服务来检索这些消息。 此调用是非阻塞性的。 如果接收队列是空的,那么此服务返回 NXD_MQTT_NO_MESSAGE。 希望收到传入消息通知的应用程序可以调用服务 nxd_mqtt_client_receive_notify_set 来注册接收回调函数。

调用方需要为主题字符串和消息正文提供内存空间。 这两个缓冲区的大小使用 topic_buffer_size 和 message_buffer_size 传入。 主题字符串和消息正文的实际字节数在 actual_topic_length 和 actual_message_length 中返回。 如果主题长度或消息长度大于所提供的缓冲区空间,则此服务返回错误代码 NXD_MQTT_INSUFFICIENT_BUFFER_SIZE。

应用程序应分配更大的缓冲区,然后重试。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • topic_buffer:指向将主题字符串复制到的内存位置的指针。
  • topic_buffer_size:主题缓冲区大小。
  • actual_topic_length:指向实际主题长度返回到的内存位置的指针。
  • message_buffer:指向将消息字符串复制到的内存位置的指针。
  • message_buffer_size:消息缓冲区大小。
  • actual_message_length:指向消息长度返回到的内存位置的指针。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功检索消息。
  • NXD_MQTT_INTERNAL_ERROR (0x10004):内部逻辑错误
  • NXD_MQTT_NO_MESSAGE (0x1000A):接收队列是空的。
  • NXD_MQTT_INSUFFICIENT_BUFFER_SIZE (0x1000D):对于主题或消息来说,主题缓冲区或消息缓冲区太小。
  • NX_PTR_ERROR (0x07):MQTT 控制块、ip_ptr 或数据包池指针无效
  • NXD_MQTT_INVALID_PARAMETER (0x10009):message_buffer 或 topic_buffer 指针为 NULL

允许调用自

线程数

示例

UCHAR topic[MAX_TOPIC_SIZE];
UCHAR message[MAX_TOPIC_SIZE];
UINT topic_length;
UINT message_length;

/* Retrieve a message from MQTT client receive queue. */
status = nxd_mqtt_client_message_get(&my_client, topic,
    sizeof(topic), &topic_length, message, sizeof(message),
    &message_length);

/* Check the return value. */
if(status == NXD_MQTT_SUCCESS)
{
/* A message is received. All done. */
}
else if (status == NXD_MQTT_NO_MESSAGE)
{
/* No more messages in the receive queue. All done. */
}
else
{
/* Receive error. */
}

nxd_mqtt_client_disconnect_notify_set

设置 MQTT 消息断开连接通知回叫函数

原型

UINT nxd_mqtt_client_disconnect_notify_set(
    NXD_MQTT_CLIENT *client_ptr,
    VOID(*disconnect_notify)(NXD_MQTT_CLIENT* client_ptr));

说明

此服务用于向 MQTT 客户端注册回叫函数。 当 MQTT 检测到与代理的连接断开时,它会调用此通知函数来向应用程序发出警报。 所以,应用程序可以使用此回叫函数来检测断开的连接,并能够重新建立与代理的连接。

VOID callback_func(NXD_MQTT_CLIENT *client_ptr);

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。
  • disconnect_notify:在 MQTT 检测到与代理的连接断开时调用的用户提供的回调函数。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功设置断开连接通知函数。
  • NX_PTR_ERROR (0x07):MQTT 控制块无效。

允许调用自

线程数

示例

VOID disconnect_notify(NXD_MQTT_CLIENT *client_ptr)
{
/* MQTT client is disconnected from the broker. Notify the application so it can re-connect to the broker. */
}

status = nxd_mqtt_client_disconnect_notify_set(client_ptr,
    disconnect_notify);

nxd_mqtt_client_disconnect

断开 MQTT 客户端与代理的连接

原型

UINT nxd_mqtt_client_disconnect(NXD_MQTT_CLIENT *client_ptr);

说明

此服务用于断开客户端与代理的连接。 请注意,接收队列中的消息会被释放。 传输队列中的 QoS 1 消息不会被释放。 在客户端重新连接到服务器后,可以处理 QoS 1 消息,除非客户端在重新连接到服务器时将 clean_session 标志设置为 NX_TRUE。

如果建立的连接有 TLS 安全保护,则此服务会在断开 TCP 连接之前关闭 TLS 会话。

实际 TCP 套接字断开连接调用有一个由 NXD_MQTT_SOCKET_TIMEOUT(计时器刻度数)定义的等待选项。 默认值为 NX_WAIT_FOREVER。 为了避免在网络连接断开或服务器没有响应的情况下无限期暂停,请将此选项设置为一个有限值。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功断开与代理的连接
  • NXD_MQTT_MUTEX_FAILURE (0x10003):无法获取 MQTT 互斥。
  • NX_PTR_ERROR (0x07):MQTT 控制块无效

允许调用自

线程数

示例

/* Disconnect from the broker. */
status = nxd_mqtt_client_disconnect(&my_client);

/* If status is NXD_MQTT_SUCCESS the client is successfully
disconnected from the broker. */

nxd_mqtt_client_delete

删除 MQTT 客户端实例

原型

UINT nxd_mqtt_client_delete(NXD_MQTT_CLIENT *client_ptr);

说明

此服务用于删除 MQTT 客户端实例,并释放内部资源。 此服务会自动断开客户端与代理的连接(如果仍连接的话)。 未传输或未被确认的消息会被释放。 应用程序收到但没有检索到的消息也会被释放。

如果建立的连接有 TLS 安全保护,则此服务会在断开 TCP 连接之前关闭 TLS 会话。

在删除客户端后,希望使用 MQTT 服务的应用程序需要新建实例。

输入参数

  • client_ptr:指向 MQTT 客户端控制块的指针。

返回值

  • NXD_MQTT_SUCCESS (0x00):已成功删除 MQTT 客户端。
  • NX_PTR_ERROR (0x07):MQTT 控制块无效

允许调用自

线程数

示例

/* Delete the MQTT client instance. */
status = nxd_mqtt_client_delete(&my_client);

/* If status is NXD_MQTT_SUCCESS the client is successfully
deleted from the system. */