Thingstream Client Library  BLD4131-v2.13
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
client_api.h File Reference

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
}
 

Functions

void Thingstream_Application_subscribeCallback (ThingstreamTopic topic, ThingstreamQualityOfService_t qos, uint8_t *payload, uint16_t payloadlen)
 
void Thingstream_Application_registerCallback (const char *topicName, ThingstreamTopic topic)
 
void Thingstream_Application_disconnectCallback (void)
 
ThingstreamClientThingstream_createClient (ThingstreamTransport *transport)
 
ThingstreamClientResult Thingstream_Client_init (ThingstreamClient *client)
 
ThingstreamClientResult Thingstream_Client_shutdown (ThingstreamClient *client)
 
ThingstreamClientResult Thingstream_Client_connect (ThingstreamClient *client, bool cleanSession, uint16_t keepAlive, const char *domainKey)
 
ThingstreamClientResult Thingstream_Client_disconnect (ThingstreamClient *client, uint16_t duration)
 
ThingstreamClientResult Thingstream_Client_ping (ThingstreamClient *client)
 
ThingstreamClientResult Thingstream_Client_register (ThingstreamClient *client, const char *topicName, ThingstreamTopic *pOutTopic)
 
ThingstreamClientResult Thingstream_Client_publish (ThingstreamClient *client, ThingstreamTopic topic, ThingstreamQualityOfService_t qos, bool retained, uint8_t *payload, uint16_t payloadlen)
 
ThingstreamClientResult Thingstream_Client_subscribeName (ThingstreamClient *client, const char *topicName, ThingstreamQualityOfService_t qos, ThingstreamTopic *pOutTopic)
 
ThingstreamClientResult Thingstream_Client_subscribeTopic (ThingstreamClient *client, ThingstreamTopic topic, ThingstreamQualityOfService_t qos)
 
ThingstreamClientResult Thingstream_Client_unsubscribeName (ThingstreamClient *client, const char *topicName)
 
ThingstreamClientResult Thingstream_Client_unsubscribeTopic (ThingstreamClient *client, ThingstreamTopic topic)
 
ThingstreamClientResult Thingstream_Client_run (ThingstreamClient *client, uint32_t waitMs)
 
const char * Thingstream_Client_getErrorText (ThingstreamClientResult result)
 
void Thingstream_Application_serverTimeCallback (uint32_t unixEpochTime)
 

Variables

const char Thingstream_Client_versionString []
 

Detailed Description

The Thingstream Client API.

Macro Definition Documentation

◆ MAKE_PREDEFINED_TOPIC

#define MAKE_PREDEFINED_TOPIC (   id)
Value:
{ \
.topicType = (uint16_t) topicTypePredefined, \
.topicId = 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), ...)

◆ MAKE_SHORT_TOPIC

#define MAKE_SHORT_TOPIC (   first,
  second 
)
Value:
{ \
.topicType = (uint16_t) topicTypeShort, \
.topicId = ( (first) << 8) | (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'), ...)

◆ Thingstream_Client_destroy

#define Thingstream_Client_destroy (   client)    ((void)(client), CLIENT_SUCCESS)

Destroy the client

Currently a no-op implemented as a macro.

Parameters
clientthe ThingstreamClient instance
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_messageWaiting

#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.

Parameters
clientthe ThingstreamClient instance (not currently used, but may be required in future).
Returns
>= 0: the number of queued messages on the server at the time of the previous publish, ping or connect.
CLIENT_INFORMATION_NOT_AVAILABLE: the Client SDK failed to receive the expected extra data with the last publish, connect or ping. E.g. If the device has never previously connected to (or pinged) the server then the server is unable to send this information with the publish.

◆ THINGSTREAM_DEFAULT_CONNECT_KEEPALIVE

#define THINGSTREAM_DEFAULT_CONNECT_KEEPALIVE   360

The default connection timeout used by Thingstream_Client_connect() when 0 is passed as the keepAlive value.

Typedef Documentation

◆ ThingstreamClient

typedef struct ThingstreamClient_s ThingstreamClient

Opaque type definition for a client instance.

◆ ThingstreamClientResult

The subset of ThingstreamResult values that start with CLIENT_

See ThingstreamResult for details of individual values.

Enumeration Type Documentation

◆ ThingstreamQualityOfService_t

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.

Enumerator
ThingstreamQOSM1 

Fire and forget without the need to be connected (publish only)

ThingstreamQOS0 

Fire and forget - the message may not be delivered

ThingstreamQOS1 

At least once - the message may be delivered more than once

ThingstreamQOS2 

Once and only once - the message will be delivered exactly once

◆ TopicType

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.

Function Documentation

◆ Thingstream_Client_connect()

ThingstreamClientResult Thingstream_Client_connect ( ThingstreamClient client,
bool  cleanSession,
uint16_t  keepAlive,
const char *  domainKey 
)

Connect to the server.

Parameters
clientthe ThingstreamClient instance
cleanSessionset non-zero if the client wants a clean MQTT session
keepAlivethe 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.
domainKeya unique identifier for the client (use NULL to obtain a value from the transport layer).
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_disconnect()

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.

Parameters
clientthe ThingstreamClient instance
durationif 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.
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_getErrorText()

const char* Thingstream_Client_getErrorText ( ThingstreamClientResult  result)

Translate an error code into a concise representative string.

Parameters
resulta ThingstreamClientResult code
Returns
text describing the result

◆ Thingstream_Client_init()

ThingstreamClientResult Thingstream_Client_init ( ThingstreamClient client)

Initialise anything that needs initialising, etc

Parameters
clientthe ThingstreamClient instance
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_ping()

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.

Parameters
clientthe ThingstreamClient instance
Returns
a ThingstreamClientResult indicating success/fail
CLIENT_SUCCESS: the command completed normally
CLIENT_NOT_CONNECTED: unable to retrieve messages, the application must reconnect to the server first.

other negative results indicate some other error condition.

◆ Thingstream_Client_publish()

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.

Parameters
clientthe ThingstreamClient instance
topicthe ThingstreamTopic (type and id) to publish onto
qosthe ThingstreamQualityOfService_t required
retainedif true, server will keep message for future subscribers
payloada pointer to the payload
payloadlenthe length of the payload
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_register()

ThingstreamClientResult Thingstream_Client_register ( ThingstreamClient client,
const char *  topicName,
ThingstreamTopic pOutTopic 
)

Register the named topic by asking the gateway for the topicId

Parameters
clientthe ThingstreamClient instance
topicNamethe name of the topic to be registered
pOutTopica pointer to the ThingstreamTopic to receive the topic type and id.
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_run()

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.

Parameters
clientthe ThingstreamClient instance
waitMsthe time in milliseconds to wait for things to happen, treat zero as "the smallest time that allows pending things to happen"
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_shutdown()

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.

Parameters
clientthe ThingstreamClient instance
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_subscribeName()

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.

Parameters
clientthe ThingstreamClient instance
topicNamethe name of the topic to subscribe to (can be wild-carded)
qosthe ThingstreamQualityOfService_t required
pOutTopica pointer (may be NULL) to the ThingstreamTopic to receive the topic type and id of the named topic.
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_subscribeTopic()

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.

Parameters
clientthe ThingstreamClient instance
topicthe type and id of the ThingstreamTopic to subscribe to
qosthe ThingstreamQualityOfService_t required
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_unsubscribeName()

ThingstreamClientResult Thingstream_Client_unsubscribeName ( ThingstreamClient client,
const char *  topicName 
)

Unsubscribe and stop receiving messages published to a topic.

Parameters
clientthe ThingstreamClient instance
topicNamethe name of the topic to unsubscribe from
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_Client_unsubscribeTopic()

ThingstreamClientResult Thingstream_Client_unsubscribeTopic ( ThingstreamClient client,
ThingstreamTopic  topic 
)

Unsubscribe and stop receiving messages published to a topic.

Parameters
clientthe ThingstreamClient instance
topicthe type and id of the ThingstreamTopic to unsubscribe from
Returns
a ThingstreamClientResult indicating success/fail

◆ Thingstream_createClient()

ThingstreamClient* Thingstream_createClient ( ThingstreamTransport transport)

Create a new client

Parameters
transportthe ThingstreamTransport instance
Returns
a pointer to a ThingstreamClient instance, or NULL if the client instance cannot be created

Variable Documentation

◆ Thingstream_Client_versionString

const char Thingstream_Client_versionString[]
extern

This string matches the Thingstream version e.g. BLD1234-v5.6

topicTypePredefined
@ topicTypePredefined
Definition: client_api.h:69
topicTypeShort
@ topicTypeShort
Definition: client_api.h:74