获取 SDK 的版本号。
MQTTClient_nameValue* MQTTClient_getVersionInfo();
无。
MQTTClient_nameValue* version = MQTTClient_getVersionInfo();
printf("used:%s, %s\n", version->name, version->value);
用 AppKey 获取注册信息。使用该函数时,每次用户都会获得新的注册信息,包括 Client ID、Username、Password 和 Device ID。
int MQTTClient_setup_with_appkey(char* appkey, REG_info *info)
名称 | 类型 | 说明 |
---|---|---|
appkey | char* | 在云巴 Portal 申请到的应用的 AppKey。 |
info | REG_info* | 保存获取到的注册信息。 |
int res = MQTTClient_setup_with_appkey(appkey, &my_reg_info);
printf("Get reg info: client_id:%s,username:%s,password:%s, devide_id:%s\n", my_reg_info.client_id, my_reg_info.username, my_reg_info.password, my_reg_info.device_id);
用 AppKey 和 Device ID 获取注册信息。
当 deviceid 参数为 NULL 时,云巴会返回一个 deviceid 给用户,用户需自行保存该 deviceid,供下次调用该函数时使用。 用户也可以使用自己的 deviceid,但必须保证其唯一性。
int MQTTClient_setup_with_appkey_and_deviceid(char* appkey, char *deviceid, REG_info *info)
名称 | 类型 | 说明 |
---|---|---|
appkey | char* | 在云巴 Portal 申请到的应用的 AppKey。 |
deviceid | char* | 用户自定义的 Device ID。 |
info | REG_info* | 保存获取到的注册信息。 |
int res = MQTTClient_setup_with_appkey_and_deviceid(appkey, device_id, &my_reg_info);
printf("Get reg info: client_id:%s,username:%s,password:%s, devide_id:%s\n", my_reg_info.client_id, my_reg_info.username, my_reg_info.password, my_reg_info.device_id);
通过 AppKey 获取 host 的信息。
int MQTTClient_get_host(char *appkey, char* url)
名称 | 类型 | 说明 |
---|---|---|
appkey | char* | 在云巴 Portal 申请到的应用的 AppKey。 |
url | char* | 保存获取到的 host 信息。 |
char url[200];
int res = MQTTClient_get_host(appkey, url);
增加订阅一个 频道。成功订阅后,App 可以收到来自该频道的消息。新增订阅不会影响已有的订阅。
int MQTTClient_subscribe(MQTTClient handle, char* topic);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
topic | char* | App 订阅的频道。取值范围详见 参数说明。 |
rc = MQTTClient_subscribe(client, "rocket");
取消对某个 频道 的订阅。成功取消后,就不会再收到来自该频道的消息。
int MQTTClient_unsubscribe(MQTTClient handle, char* topic);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
topic | char* | App 取消订阅的频道。取值范围详见 参数说明。 |
rc = MQTTClient_unsubscribe(client, "rocket");
监听某 频道 下用户行为的事件通知,事件包括上线、下线、订阅频道和取消订阅频道。
参见 云巴的实时在线。
int MQTTClient_presence(MQTTClient handle, char* topic);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
topic | char* | 目标用户所在的频道。取值范围详见 参数说明。 |
rc = MQTTClient_presence(client, "rocket");
取消监听某 频道 下用户行为的事件通知,事件包括上线、下线、订阅频道和取消订阅频道。
参见 云巴的实时在线。
int MQTTClient_unpresence(MQTTClient handle, char* topic);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
topic | char* | App 希望取消订阅的对象所在的频道。取值范围详见 参数说明。 |
rc = MQTTClient_unpresence(client, "rocket");
向某个 频道 发布消息。成功发布后,所有订阅此频道的客户端都会收到消息。
int MQTTCient_publish(MQTTClient handle, char* topicName, int data_len, void *data)
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
topic | char* | 订阅的主题,取值范围详见 参数说明。 |
data_len | int | 消息内容的长度。 |
data | void* | 消息指针。 |
char buf[100] = "Just test";
int data_len = strlen(buf);
rc = MQTTClient_publish(client, topic, data_len, buf);
MQTTClient_publish()
的升级版本,支持更多参数。
int MQTTClient_publish2(MQTTClient handle, const char* topicName, int payloadlen, void* payload, cJSON *opt);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
topic | char* | 订阅的主题,取值范围详见 参数说明。 |
payloadlen | int | payload 的长度。 |
payload | void* | payload 的内容。 |
opt | CJSON * | 扩展参数,可以带 apn_json,time_to_live 等参数。 |
名称 | 类型 | 说明 |
---|---|---|
qos | Number | 服务质量等级。有三种取值:“0”表示最多送达一次;“1”表示最少送达一次;“2”表示保证送达且仅送达一次。默认为“1”。详见 QoS 的说明。 |
apn_json | Dict | 如果不填,则不会发送 APN。 APN 参考:Apple 官方文档 及云巴 相关文档。 |
messageId | String | 消息 ID,64 位整型数转化成 String。发布消息时可以指定,如果不填,则由系统自动生成。 |
time_to_live | Number | 用来设置 离线消息 保留多久。单位为秒(例如,3600 代表 1 小时),默认值为 3 天,最大不超过 15 天。 |
cJSON *apn_json, *aps;
cJSON *Opt = cJSON_CreateObject();
cJSON_AddStringToObject(Opt,"time_to_live", "120");
cJSON_AddStringToObject(Opt,"time_delay", "1100");
cJSON_AddStringToObject(Opt,"apn_json", "{\"aps\":{\"alert\":\"FENCE alarm\", \"sound\":\"alarm.mp3\"}}");
ret = MQTTClient_publish2(client, topic, strlen("test"), "test", Opt);
cJSON_Delete(Opt);
printf("publish2 status:%i\n", ret);
向某个 别名 发布消息。发布成功后,该别名的客户端会收到消息。
int MQTTClient_publish_to_alias(MQTTClient handle, char* alias, int data_len, void* data);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
alias | char* | 目标别名。取值范围详见 参数说明。 |
data_len | int | 消息内容的长度。 |
data | void* | 消息指针。 |
rc = MQTTClient_publish_to_alias(client, "Hello_alias", strlen("test"), "test");
MQTTClient_publish2_to_alias()
的升级版本,支持更多参数。
int MQTTClient_publish2_to_alias(MQTTClient handle, const char* alias, int payloadlen, void* payload, cJSON *opt);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
alias | const char* | 目标别名。取值范围详见 参数说明。 |
payloadlen | int | payload 的长度。 |
payload | void* | payload 内容。 |
opt | CJSON * | 扩展参数,可以带 apn_json,time_to_live 等参数。 |
cJSON *apn_json, *aps;
cJSON *Opt = cJSON_CreateObject();
cJSON_AddStringToObject(Opt,"time_to_live", "120");
cJSON_AddStringToObject(Opt,"time_delay", "1100");
cJSON_AddStringToObject(Opt,"apn_json", "{\"aps\":{\"alert\":\"FENCE alarm\", \"sound\":\"alarm.mp3\"}}");
ret = MQTTClient_publish2_to_alias(client, "Alex", strlen("test"), "test", Opt);
cJSON_Delete(Opt);
printf("publish2_alas status:%i\n", ret);
向某个 频道 发布 JSON 格式的消息。成功发布后,所有订阅此频道的客户端都会收到消息。
int MQTTClient_publish_json(MQTTClient handle, char* topicName, cJSON* data)
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
topic | char* | 目标频道。取值范围详见 参数说明。 |
data | cJSON* | JSON 包。 |
char buf[100] = "{\"num_name\":2}";
cJSON *data = cJSON_Parse(buf);
rc = MQTTClient_publish_json(client, topic, data);
cJSON_Delete(data);
用来设置用户名,即绑定账号。每个用户只能指定一个 别名。
将MQTTClient_set_alias()
的alias
参数设置为空字符串即可取消别名。
int MQTTClient_set_alias(MQTTClient handle, char* alias);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
alias | char* | 用户设置的别名信息,取值范围详见 参数说明。 |
int ret = MQTTClient_set_alias(client, "000000018302");
获取当前用户的 别名。
通过设置MQTTClient_setCallbacks()
的 最后一个参数 ——回调函数MQTTClient_extendedCmdArrive
——来获得相关信息,可能的信息包括:
{command:2, status:0, data:"aliasname"}
{command:2, status:1, data:"server internal error"}
{command:2, status:2, data:"alias not find"}
int MQTTClient_get_alias(MQTTClient handle, char* parameter);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
parameter | char* | 目标别名。 |
int ret = MQTTClient_get_alias(client, "0");
查询目标用户(别名)的在线状态。
通过设置MQTTClient_setCallbacks()
的 最后一个参数 ——回调函数MQTTClient_extendedCmdArrive
——来获得相关信息,可能的信息包括:
{command:10, status:0, data: "online/offline"}
{command:10, status:1, data: "server internal error"}
{command:10, status:2, data: "no operation permission"}
{command:10, status:3, data: "alias not find"}
{command:10, status:4, data: "no status"}
{command:10, status:5, data: "alias is empty"}
int MQTTClient_get_status(MQTTClient handle, char* parameter);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
parameter | char* | 目标别名。 |
int ret = MQTTClient_get_status(client, "000000018302");
查询目标用户(别名)的在线状态。是MQTTClient_get_status()
的升级版本,其返回的状态信息中,会包含目标别名的名称。
通过设置MQTTClient_setCallbacks()
的 最后一个参数 ——回调函数MQTTClient_extendedCmdArrive
——来获得相关信息,可能的信息包括:
{command:20, status:0, data: "{'status': 'online/offline', 'alias': aliasname}"} #aliasname: string
{command:20, status:1, data: "{'msg': 'server internal error'}"}
{command:20, status:2, data: "{'msg': 'no operation permission'}"}
{command:20, status:3, data: "{'msg': 'alias not find'}"}
{command:20, status:4, data: "{'msg': 'no status'}"}
{command:20, status:5, data: "{'msg': 'alias is empty'}"}
int MQTTClient_get_status2(MQTTClient handle, char* parameter);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
parameter | char* | 目标别名。 |
int ret = MQTTClient_get_status2(client, "000000018302");
通过设置MQTTClient_setCallbacks()
的 最后一个参数 ——回调函数MQTTClient_extendedCmdArrive
——来获得相关信息,可能的信息包括:
{command:6, status:0, data: "{'alias':[alias1,alias2,alias3], 'occupancy': alias_length}"}
{command:6, status:1, data: "server internal error"}
{command:6, status:2, data: "no operation permission"}
int MQTTClient_get_aliaslist(MQTTClient handle, char* parameter);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
parameter | char* | 目标频道。 |
int ret = MQTTClient_get_aliaslist(client, "rocket");
获取某 频道 下的所有订阅者的 别名 列表。是MQTTClient_get_aliaslist()
的升级版本,其返回的状态信息中,会包含目标频道的名称。
通过设置MQTTClient_setCallbacks()
的 最后一个参数 ——回调函数MQTTClient_extendedCmdArrive
——来获得相关信息,可能的信息包括:
{command:16, status:0, data: "{'alias':[alias1,alias2,alias3], 'occupancy': alias_length, 'topic': topicname}"} # topicnam2/alias1/alias2...: string, alias_length: int
{command:16, status:1, data: "{'msg': 'server internal error'}"}
{command:16, status:2, data: "{'msg': 'no operation permission'}"}
int MQTTClient_get_aliaslist2(MQTTClient handle, char* parameter);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
parameter | char* | 目标频道。 |
int ret = MQTTClient_get_aliaslist2(client, "mytopic");
获取某个用户所订阅的 频道。
通过设置MQTTClient_setCallbacks()
的 最后一个参数 ——回调函数MQTTClient_extendedCmdArrive
——来获得相关信息,可能的信息包括:
{command:4, status:0, data: "{'topic':[topic1,topic2,...]}"}
{command:4, status:1, data: "server internal error"}
{command:4, status:2, data: "no operation permission"}
{command:4, status:3, data: "alias not find"}
int MQTTClient_get_topic(MQTTClient handle, char* parameter);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
parameter | char* | 目标用户的别名。 |
int ret = MQTTClient_get_topic(client, "000000018302");
获取某个用户所订阅的 频道。
是MQTTClient_get_topic()
的升级版本,其返回的状态信息中,会包含目标
别名 的名称。
int MQTTClient_get_topiclist2(MQTTClient handle, char* parameter);
通过设置MQTTClient_setCallbacks()
的 最后一个参数 ——回调函数MQTTClient_extendedCmdArrive
——来获得相关信息,可能的信息包括:
{command:14, status:0, data: "{'topic':[topic1,topic2,...], 'alias': aliasname}"}
{command:14, status:1, data: "{'msg': 'server internal error'}"}
{command:14, status:2, data: "{'msg': 'no operation permission'}"}
{command:14, status:3, data: "{'msg': 'alias not find'}"}
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
parameter | char* | 目标用户的别名。取值范围详见 参数说明。 |
int ret = MQTTClient_get_topiclist2(client, "000000018302");
暂未支持。 上报客户端的行为。如,打开通知栏次数、按钮点击次数、资源下载成功次数等行为。
int MQTTClient_report(MQTTClient handle, char* action, char* data);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient | 客户端句柄。 |
action | char* | App 需要统计的行为,如打开通知栏,资源下载成功等。 |
data | char* | 对应行为的附加数据,以满足统计相关的其他业务需求。 |
int ret = MQTTClient_report(client, "action", "data");
设置 Broker。
int MQTTClient_set_broker(MQTTClient* handle, char* broker);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient* | 客户端句柄的指针。 |
broker | char* | Broker 域名或者 IP 地址。 |
int ret = MQTTClient_set_broker(client, "192.168.1.100");
获取当前的 Broker。
int MQTTClient_get_broker(MQTTClient* handle, char* broker);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient* | 客户端句柄的指针。 |
broker | char* | 存放 Broker 的指针。 |
char buf[100];
int ret = MQTTClient_set_broker(client, buf);
释放 message 资源。
void MQTTClient_freeMessage(MQTTClient_message** msg);
名称 | 类型 | 说明 |
---|---|---|
msg | MQTTClient_message** | 指向 message 指针的指针。 |
无。
int messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* m) {
MQTTClient_freeMessage(&m);
MQTTClient_free(topicName);
}
释放客户端资源。
void MQTTClient_destroy(MQTTClient* handle);
名称 | 类型 | 说明 |
---|---|---|
handle | MQTTClient* | 客户端句柄的指针。 |
无。
MQTTClient_destroy(&client);