Subscription

Subscriptions. More...

Typedefs
typedef void(*	DPS_OnSubscriptionDestroyed) (DPS_Subscription *sub)
	Function prototype for callback function called when a subscription is destroyed. More...
typedef void(*	DPS_PublicationHandler) (DPS_Subscription *sub, const DPS_Publication *pub, uint8_t *payload, size_t len)
	Function prototype for a publication handler called when a publication is received that matches a subscription. More...
typedef struct _DPS_Subscription	DPS_Subscription
	Opaque type for a subscription.

Functions
DPS_Subscription *	DPS_CreateSubscription (DPS_Node *node, const char **topics, size_t numTopics)
	Allocate memory for a subscription and initialize topics. More...
DPS_Status	DPS_DestroySubscription (DPS_Subscription *sub, DPS_OnSubscriptionDestroyed cb)
	Stop subscribing to the subscription topic and free resources allocated for the subscription. More...
void *	DPS_GetSubscriptionData (DPS_Subscription *sub)
	Get application data pointer previously set by DPS_SetSubscriptionData() More...
DPS_Status	DPS_SetSubscriptionData (DPS_Subscription *sub, void *data)
	Store a pointer to application data in a subscription. More...
DPS_Status	DPS_Subscribe (DPS_Subscription *sub, DPS_PublicationHandler handler)
	Start subscribing to a set of topics. More...
DPS_Status	DPS_SubscribeExpired (DPS_Subscription *sub, int enable)
	Call the publication handler when a matching retained publication expires. More...
DPS_Node *	DPS_SubscriptionGetNode (const DPS_Subscription *sub)
	Get the local node associated with a subscription. More...
size_t	DPS_SubscriptionGetNumTopics (const DPS_Subscription *sub)
	Get the number of topics registered with an active subscription. More...
const char *	DPS_SubscriptionGetTopic (const DPS_Subscription *sub, size_t index)
	Get a topic for an active subscription. More...

Detailed Description

Subscriptions.

Typedef Documentation

DPS_OnSubscriptionDestroyed

typedef void(* DPS_OnSubscriptionDestroyed) (DPS_Subscription *sub)

Function prototype for callback function called when a subscription is destroyed.

Parameters

sub	The subscription that was destroyed. This is valid during the callback.

DPS_PublicationHandler

typedef void(* DPS_PublicationHandler) (DPS_Subscription *sub, const DPS_Publication *pub, uint8_t *payload, size_t len)

Function prototype for a publication handler called when a publication is received that matches a subscription.

Note that there is a possibility of false-positive matches.

The publication handle is only valid within the body of this callback function. DPS_CopyPublication() will make a partial copy of the publication that can be used later for example to call DPS_AckPublication().

The accessor functions DPS_PublicationGetUUID() and DPS_PublicationGetSequenceNum() return information about the received publication.

The accessor functions DPS_SubscriptionGetNumTopics() and DPS_SubscriptionGetTopic() return information about the subscription that was matched.

Parameters

sub	Opaque handle for the subscription that was matched
pub	Opaque handle for the publication that was received
payload	Payload from the publication if any
len	Length of the payload

Function Documentation

DPS_CreateSubscription()

DPS_Subscription* DPS_CreateSubscription	(	DPS_Node *	node,
		const char **	topics,
		size_t	numTopics
	)

Allocate memory for a subscription and initialize topics.

Parameters

node	The local node to use
topics	The topic strings to match
numTopics	The number of topic strings to match - must be >= 1

Returns

The newly created subscription or NULL if resources could not be allocated or the arguments were invalid

DPS_DestroySubscription()

DPS_Status DPS_DestroySubscription	(	DPS_Subscription *	sub,
		DPS_OnSubscriptionDestroyed	cb
	)

Stop subscribing to the subscription topic and free resources allocated for the subscription.

Parameters

sub	The subscription to destroy
cb	Callback function to be called when the subscription is destroyed

Returns

DPS_OK if destroy is successful, an error otherwise

DPS_GetSubscriptionData()

void* DPS_GetSubscriptionData

(

DPS_Subscription *

sub

)

Get application data pointer previously set by DPS_SetSubscriptionData()

Parameters

sub	The subscription

Returns

A pointer to the data or NULL if the subscription is invalid

DPS_SetSubscriptionData()

DPS_Status DPS_SetSubscriptionData	(	DPS_Subscription *	sub,
		void *	data
	)

Store a pointer to application data in a subscription.

Parameters

sub	The subscription
data	The data pointer to store

Returns

DPS_OK or an error

DPS_Subscribe()

DPS_Status DPS_Subscribe	(	DPS_Subscription *	sub,
		DPS_PublicationHandler	handler
	)

Start subscribing to a set of topics.

Parameters

sub	The subscription to start
handler	Callback function to be called with topic matches

Returns

DPS_OK if start is successful, an error otherwise

DPS_SubscribeExpired()

DPS_Status DPS_SubscribeExpired	(	DPS_Subscription *	sub,
		int	enable
	)

Call the publication handler when a matching retained publication expires.

DPS_PublicationGetTTL() will return a negative value when the publication is expired.

Parameters

sub	The subscription
enable	DPS_TRUE to call handler, DPS_FALSE to not call handler

Returns

DPS_OK or an error

DPS_SubscriptionGetNode()

DPS_Node* DPS_SubscriptionGetNode

(

const DPS_Subscription *

sub

)

Get the local node associated with a subscription.

Parameters

sub	The subscription

Returns

The node or NULL if the subscription is invalid

DPS_SubscriptionGetNumTopics()

size_t DPS_SubscriptionGetNumTopics

(

const DPS_Subscription *

sub

)

Get the number of topics registered with an active subscription.

Parameters

sub	The subscription

Returns

The number of topics.

DPS_SubscriptionGetTopic()

const char* DPS_SubscriptionGetTopic	(	const DPS_Subscription *	sub,
		size_t	index
	)

Get a topic for an active subscription.

Parameters

sub	The subscription
index	The topic index

Returns

The topic string or NULL if the subscription or index is invalid.