![]() |
Thingstream Client Library
BLD4131-v2.13
|
The Thingstream Client API. More...
#include <stdint.h>
#include <stdbool.h>
#include "transport_api.h"
#include "sdk_data.h"
#include "thingstream_result.h"
#include "client_set_callback.h"
#include "thingstream_deprecated_client_short_names.h"
Data Structures | |
struct | ThingstreamTopic |
Macros | |
#define | MAKE_PREDEFINED_TOPIC(id) |
#define | MAKE_SHORT_TOPIC(first, second) |
#define | THINGSTREAM_DEFAULT_CONNECT_KEEPALIVE 360 |
#define | Thingstream_Client_destroy(client) ((void)(client), CLIENT_SUCCESS) |
#define | Thingstream_Client_messageWaiting(client) ((ThingstreamClientResult)SDK_DATA_INBOUND_QUEUE(size)) |
Typedefs | |
typedef ThingstreamResult | ThingstreamClientResult |
typedef struct ThingstreamClient_s | ThingstreamClient |
Enumerations | |
enum | TopicType { topicTypeNormal, topicTypePredefined, topicTypeShort } |
enum | ThingstreamQualityOfService_t { ThingstreamQOSM1 = -1, ThingstreamQOS0 = 0, ThingstreamQOS1 = 1, ThingstreamQOS2 = 2 } |
Variables | |
const char | Thingstream_Client_versionString [] |
The Thingstream Client API.
#define MAKE_PREDEFINED_TOPIC | ( | id | ) |
Initialise predefined ThingstreamTopic with given Id
Usage: Topic my_topic = MAKE_PREDEFINED_TOPIC(id)
On gcc, it can also be used as a literal, with a cast. Eg Thingstream_Client_publish(client, (ThingstreamTopic)MAKE_PREDEFINED_TOPIC(id), ...)
#define MAKE_SHORT_TOPIC | ( | first, | |
second | |||
) |
Initialise short ThingstreamTopic with given character pair. Usage: Topic my_topic = MAKE_SHORT_TOPIC('x', 'y')
On gcc, it can also be used as a literal, with a cast. Eg Thingstream_Client_publish(client, (ThingstreamTopic)MAKE_SHORT_TOPIC('x', 'y'), ...)
#define Thingstream_Client_destroy | ( | client | ) | ((void)(client), CLIENT_SUCCESS) |
Destroy the client
Currently a no-op implemented as a macro.
client | the ThingstreamClient instance |
#define Thingstream_Client_messageWaiting | ( | client | ) | ((ThingstreamClientResult)SDK_DATA_INBOUND_QUEUE(size)) |
Test if the server has indicated that there are queued messages waiting on the server for this device.
The server sends extra data when executing the APIs Thingstream_Client_publish(), Thingstream_Client_connect(), or Thingstream_Client_ping() and this is remembered by the Client SDK. The extra data is sent by the server at the start of the publish and at the end of the connect or the ping.
This stored number of queued messages can be queried using Thingstream_Client_messageWaiting()
Note that this is currently implemented as a macro accessing a global variable but the implementation may change in the future.
client | the ThingstreamClient instance (not currently used, but may be required in future). |
#define THINGSTREAM_DEFAULT_CONNECT_KEEPALIVE 360 |
The default connection timeout used by Thingstream_Client_connect() when 0 is passed as the keepAlive value.
typedef struct ThingstreamClient_s ThingstreamClient |
Opaque type definition for a client instance.
The subset of ThingstreamResult values that start with CLIENT_
See ThingstreamResult for details of individual values.
The quality of service (QoS) assigned to a message. There are three levels of QoS (0, 1, 2) which can be used while connected for subscribe or publish. In addition, QoS -1 is available and is equivalent to QoS 0, but can be used to publish messages with topicTypeShort or topicTypePredefined without connecting.
enum TopicType |
The MQTTSN type of a topic defines the interpretation of the 16-bit topicId field in the ThingstreamTopic structure.
Enumerator | |
---|---|
topicTypeNormal | a normal topic type uses a 16-bit topicId which is obtained by converting the topic name with the Thingstream_Client_register() API. |
topicTypePredefined | a predefined topic type uses a 16-bit topicId which has been defined via the Thingstream Management Console Topics page. |
topicTypeShort | a short topic type uses a two character name stored in the 16-bits of the topicId. |
ThingstreamClientResult Thingstream_Client_connect | ( | ThingstreamClient * | client, |
bool | cleanSession, | ||
uint16_t | keepAlive, | ||
const char * | domainKey | ||
) |
Connect to the server.
client | the ThingstreamClient instance |
cleanSession | set non-zero if the client wants a clean MQTT session |
keepAlive | the duration (in minutes) that the server will keep the connection active after receiving a message from the client. A value of zero selects THINGSTREAM_DEFAULT_CONNECT_KEEPALIVE. |
domainKey | a unique identifier for the client (use NULL to obtain a value from the transport layer). |
ThingstreamClientResult Thingstream_Client_disconnect | ( | ThingstreamClient * | client, |
uint16_t | duration | ||
) |
Either enter a sleeping state, or disconnect from the server. The server will persist all current subscriptions, which may then be cleared out by the server on the next "cleanSession" connect.
client | the ThingstreamClient instance |
duration | if non-zero the number of minutes that the server should treat the client as sleeping. During this time, Thingstream_Client_ping() can be used to retrieve messages and refresh the timeout. |
const char* Thingstream_Client_getErrorText | ( | ThingstreamClientResult | result | ) |
Translate an error code into a concise representative string.
result | a ThingstreamClientResult code |
ThingstreamClientResult Thingstream_Client_init | ( | ThingstreamClient * | client | ) |
Initialise anything that needs initialising, etc
client | the ThingstreamClient instance |
ThingstreamClientResult Thingstream_Client_ping | ( | ThingstreamClient * | client | ) |
Perform an MQTT-SN ping refreshing the keepAlive or sleep timer and flushing pending subscribed messages (each message will be delivered via the Thingstream_Application_subscribeCallback()).
The Ping Flush setting on the Thingstream Management Console may cause the server to complete the ping request before all pending messages have been sent to the device. If this is important to the application then the Thingstream_Client_messageWaiting() API can be used to identify this early return case.
client | the ThingstreamClient instance |
other negative results indicate some other error condition.
ThingstreamClientResult Thingstream_Client_publish | ( | ThingstreamClient * | client, |
ThingstreamTopic | topic, | ||
ThingstreamQualityOfService_t | qos, | ||
bool | retained, | ||
uint8_t * | payload, | ||
uint16_t | payloadlen | ||
) |
Send a message to the given topic.
client | the ThingstreamClient instance |
topic | the ThingstreamTopic (type and id) to publish onto |
qos | the ThingstreamQualityOfService_t required |
retained | if true, server will keep message for future subscribers |
payload | a pointer to the payload |
payloadlen | the length of the payload |
ThingstreamClientResult Thingstream_Client_register | ( | ThingstreamClient * | client, |
const char * | topicName, | ||
ThingstreamTopic * | pOutTopic | ||
) |
Register the named topic by asking the gateway for the topicId
client | the ThingstreamClient instance |
topicName | the name of the topic to be registered |
pOutTopic | a pointer to the ThingstreamTopic to receive the topic type and id. |
ThingstreamClientResult Thingstream_Client_run | ( | ThingstreamClient * | client, |
uint32_t | waitMs | ||
) |
Process any outstanding tasks that are waiting.
While the application is connected to the server (i.e. has successfully done a Thingstream_Client_connect() but not yet done a Thingstream_Client_disconnect()) the application is expected to periodically call Thingstream_Client_run().
If the server has sent a message to this device then Thingstream_Application_subscribeCallback() will called from within this function to deliver the message to the application.
client | the ThingstreamClient instance |
waitMs | the time in milliseconds to wait for things to happen, treat zero as "the smallest time that allows pending things to happen" |
ThingstreamClientResult Thingstream_Client_shutdown | ( | ThingstreamClient * | client | ) |
Shut down the client, free any resources etc. After this call the application is free to turn off the modem. Before using any more Thingstream_Client_xxx() APIs, the application must call Thingstream_Client_init() again to re-initialise the ThingstreamTransport stack.
client | the ThingstreamClient instance |
ThingstreamClientResult Thingstream_Client_subscribeName | ( | ThingstreamClient * | client, |
const char * | topicName, | ||
ThingstreamQualityOfService_t | qos, | ||
ThingstreamTopic * | pOutTopic | ||
) |
Subscribe to receive messages that are published on the named topic. When messages arrive the Thingstream_Application_subscribeCallback() will be called with the topic, QoS, and message payload.
client | the ThingstreamClient instance |
topicName | the name of the topic to subscribe to (can be wild-carded) |
qos | the ThingstreamQualityOfService_t required |
pOutTopic | a pointer (may be NULL) to the ThingstreamTopic to receive the topic type and id of the named topic. |
ThingstreamClientResult Thingstream_Client_subscribeTopic | ( | ThingstreamClient * | client, |
ThingstreamTopic | topic, | ||
ThingstreamQualityOfService_t | qos | ||
) |
Subscribe to receive messages that are published on a topic. When messages arrive the Thingstream_Application_subscribeCallback() will be called with the topic, QoS, and message payload.
client | the ThingstreamClient instance |
topic | the type and id of the ThingstreamTopic to subscribe to |
qos | the ThingstreamQualityOfService_t required |
ThingstreamClientResult Thingstream_Client_unsubscribeName | ( | ThingstreamClient * | client, |
const char * | topicName | ||
) |
Unsubscribe and stop receiving messages published to a topic.
client | the ThingstreamClient instance |
topicName | the name of the topic to unsubscribe from |
ThingstreamClientResult Thingstream_Client_unsubscribeTopic | ( | ThingstreamClient * | client, |
ThingstreamTopic | topic | ||
) |
Unsubscribe and stop receiving messages published to a topic.
client | the ThingstreamClient instance |
topic | the type and id of the ThingstreamTopic to unsubscribe from |
ThingstreamClient* Thingstream_createClient | ( | ThingstreamTransport * | transport | ) |
Create a new client
transport | the ThingstreamTransport instance |
|
extern |
This string matches the Thingstream version e.g. BLD1234-v5.6