MQTT Client API 参考
API 参考
-
wm_mqtt_client_handle_t wm_mqtt_client_init(wm_mqtt_client_config_t *config)
Creates *MQTT* client handle based on the configuration.
- 参数:
config – *MQTT* configuration structure Notes: protocol prefix in serverURI should be:
tcp:// or mqtt:// - Insecure TCP
ssl:// or mqtts:// - Encrypted SSL/TLS
ws:// - Insecure websockets
wss:// - Secure web sockets
- 返回:
wm_mqtt_client_handle_t if successfully created, WM_INVALID_HANDLE on error
-
int wm_mqtt_client_deinit(wm_mqtt_client_handle_t handle)
Destroys the client handle.
Notes: If the mqtt client is already connected, this call to the API may produce WM_EVENT_MQTT_CLIENT_DISCONNECTED events
- 参数:
handle – *MQTT* client handle
- 返回:
WM_MQTT_CLIENT_ERROR_SUCCESS on success others on other error
-
int wm_mqtt_client_connect(wm_mqtt_client_handle_t handle)
Starts *MQTT* client with already created client handle.
Notes:
1. The API creates an mqtt client task that is not currently supported to be deleted when exiting the mqtt client. Even if there are multiple mqtt clients, only one mqtt task will be created
2. If the mqtt client is already connected, this call to the API may produce WM_EVENT_MQTT_CLIENT_CONNECTED events
- 参数:
handle – *MQTT* client handle
- 返回:
WM_MQTT_CLIENT_ERROR_SUCCESS on success others on other error
-
int wm_mqtt_client_disconnect(wm_mqtt_client_handle_t handle)
Stops *MQTT* client.
Notes: If the mqtt client is already connected, this call to the API may produce WM_EVENT_MQTT_CLIENT_DISCONNECTED events
- 参数:
handle – *MQTT* client handle
- 返回:
WM_MQTT_CLIENT_ERROR_SUCCESS on success others on other error
-
int wm_mqtt_client_reconnect(wm_mqtt_client_handle_t handle)
This api is typically used to force reconnection upon a specific event.
- 参数:
handle – *MQTT* client handle
- 返回:
WM_MQTT_CLIENT_ERROR_SUCCESS on success others on other error
-
int wm_mqtt_client_subscribe(wm_mqtt_client_handle_t handle, const char *topic, uint8_t qos)
Subscribe the client to defined topic with defined qos.
Notes:
1. Client must be connected to send subscribe message
2. This call to the API may produce WM_EVENT_MQTT_CLIENT_PUBLISHED events
- 参数:
handle – *MQTT* client handle
topic – topic string
qos – QoS of subscribe message
- 返回:
message_id of the subscribe message on success <0 on failure
-
int wm_mqtt_client_unsubscribe(wm_mqtt_client_handle_t handle, const char *topic)
Unsubscribe the client from defined topic.
Notes:
1. Client must be connected to send unsubscribe message
2. This call to the API may produce WM_EVENT_MQTT_CLIENT_PUBLISHED events
- 参数:
handle – *MQTT* client handle
topic – topic string
- 返回:
message_id of the subscribe message on success <0 on failure
-
int wm_mqtt_client_publish(wm_mqtt_client_handle_t handle, const char *topic, const char *message, uint16_t msg_len, uint8_t qos, uint8_t retain)
Client to send a publish message to the broker.
Notes:
1. This API might block for several seconds, either due to network timeout(10s)
2. This call to the API may produce WM_EVENT_MQTT_CLIENT_PUBLISHED events
- 参数:
handle – *MQTT* client handle
topic – topic string
message – payload string (set to NULL, sending empty payload message)
msg_len – payload length, if set to 0, length is calculated from payload string
qos – QoS of publish message
retain – retain flag
- 返回:
message_id of the publish message (for QoS 0 message_id will always be zero) on success. -1 on failure.
数据结构参考
-
enum wm_event_mqtt_client
Values:
-
enumerator WM_EVENT_MQTT_CLIENT_CONNECTED
mqtt client connected event
-
enumerator WM_EVENT_MQTT_CLIENT_DISCONNECTED
mqtt client disconnected event
-
enumerator WM_EVENT_MQTT_CLIENT_DATA
mqtt client data event
-
enumerator WM_EVENT_MQTT_CLIENT_PUBLISHED
mqtt client published event
-
enumerator WM_EVENT_MQTT_CLIENT_CONNECTED
-
enum wm_mqtt_client_auth_mode_en
Values:
-
enumerator WM_MQTT_CLIENT_AUTH_MODE_NOT_CERT
No certificate validation.
-
enumerator WM_MQTT_CLIENT_AUTH_MODE_AUTH_SERVER_CERT
Verify the server certificate.
-
enumerator WM_MQTT_CLIENT_AUTH_MODE_PROVIDE_CLIENT_CERT
Verify the server certificate.
-
enumerator WM_MQTT_CLIENT_AUTH_MODE_MUTUAL_AUTH
Verify the server certificate.
-
enumerator WM_MQTT_CLIENT_AUTH_MODE_NOT_CERT
-
enum wm_mqtt_client_error_code_en
Values:
-
enumerator WM_MQTT_CLIENT_ERROR_SUCCESS
No error. Indicates successful completion of an MQTT client operation.
-
enumerator WM_MQTT_CLIENT_ERROR_FAILURE
A generic error code indicating the failure of an MQTT client operation.
-
enumerator WM_MQTT_CLIENT_ERROR_PERSISTENCE_ERROR
Application-specific persistence error.
-
enumerator WM_MQTT_CLIENT_ERROR_DISCONNECTED
The client is disconnected.
-
enumerator WM_MQTT_CLIENT_ERROR_MAX_MESSAGES_INFLIGHT
The maximum number of messages allowed to be simultaneously in-flight has been reached.
-
enumerator WM_MQTT_CLIENT_ERROR_BAD_UTF8_STRING
An invalid UTF-8 string has been detected.
-
enumerator WM_MQTT_CLIENT_ERROR_NULL_PARAMETER
A NULL parameter has been supplied when this is invalid.
-
enumerator WM_MQTT_CLIENT_ERROR_TOPICNAME_TRUNCATED
The topic has been truncated (the topic string includes embedded NULL characters).
-
enumerator WM_MQTT_CLIENT_ERROR_BAD_STRUCTURE
A structure parameter does not have the correct eyecatcher and version number.
-
enumerator WM_MQTT_CLIENT_ERROR_BAD_QOS
A QoS value that falls outside of the acceptable range (0,1,2).
-
enumerator WM_MQTT_CLIENT_ERROR_SSL_NOT_SUPPORTED
Attempting SSL connection using non-SSL version of library.
-
enumerator WM_MQTT_CLIENT_ERROR_BAD_MQTT_VERSION
unrecognized MQTT version.
-
enumerator WM_MQTT_CLIENT_ERROR_BAD_PROTOCOL
protocol prefix invalid.
-
enumerator WM_MQTT_CLIENT_ERROR_BAD_MQTT_OPTION
option not applicable to the requested version of MQTT.
-
enumerator WM_MQTT_CLIENT_ERROR_WRONG_MQTT_VERSION
call not applicable to the requested version of MQTT.
-
enumerator WM_MQTT_CLIENT_ERROR_0_LEN_WILL_TOPIC
0 length will topic on connect.
-
enumerator WM_MQTT_CLIENT_ERROR_SUCCESS
-
typedef enum wm_mqtt_client_auth_mode_en wm_mqtt_client_auth_mode_t
-
typedef enum wm_mqtt_client_error_code_en wm_mqtt_client_error_code_t
-
typedef union wm_mqtt_event_data_un wm_mqtt_event_data_t
-
typedef struct wm_mqtt_client_config_st wm_mqtt_client_config_t
-
typedef struct wm_mqtt_client_handle_st *wm_mqtt_client_handle_t
-
WM_EVENT_DECLARE_GROUP(WM_MQTT_EV)
Declare mqtt event group
-
union wm_mqtt_event_data_un
Public Members
-
char *topic
-
uint16_t topic_len
-
char *payload
-
uint16_t payload_len
-
int msgid
-
uint8_t qos
-
uint8_t dup
-
uint8_t retained
-
void *client_handle
same as wm_mqtt_client_handle_t->client
-
struct wm_mqtt_event_data_un::[anonymous] mqtt_client_data_info
-
int msg_id
-
struct wm_mqtt_event_data_un::[anonymous] mqtt_client_published_info
-
struct wm_mqtt_event_data_un::[anonymous] mqtt_client_disconnect_info
-
char *topic
-
struct wm_mqtt_client_config_st
-
struct wm_mqtt_client_handle_st