Publications. More...

Data Structures
struct	_DPS_Buffer
	A buffer. More...

Typedefs
typedef void(*	DPS_AcknowledgementHandler) (DPS_Publication pub, uint8_t payload, size_t len)
	Function prototype for a publication acknowledgement handler called when an acknowledgement for a publication is received from a remote subscriber. More...

typedef void(*	DPS_AckPublicationBufsComplete) (DPS_Publication pub, const DPS_Buffer bufs, size_t numBufs, DPS_Status status, void *data)
	Called when DPS_AckPublicationBufs() completes. More...

typedef struct _DPS_Buffer	DPS_Buffer
	A buffer.

typedef void(*	DPS_OnPublicationDestroyed) (DPS_Publication *pub)
	Function prototype for callback function called when a publication is destroyed. More...

typedef struct _DPS_Publication	DPS_Publication
	Opaque type for a publication.

typedef void(*	DPS_PublishBufsComplete) (DPS_Publication pub, const DPS_Buffer bufs, size_t numBufs, DPS_Status status, void *data)
	Called when DPS_PublishBufs() completes. More...

Functions
const DPS_KeyId *	DPS_AckGetSenderKeyId (const DPS_Publication *pub)
	Get the key identifier of an acknowledgement, only valid with the body of the DPS_AcknowledgementHandler function. More...

uint32_t	DPS_AckGetSequenceNum (const DPS_Publication *pub)
	Get the sequence number being acknowledged, only valid with the body of the DPS_AcknowledgementHandler function. More...

DPS_Status	DPS_AckPublication (const DPS_Publication pub, const uint8_t ackPayload, size_t len)
	Acknowledge a publication. More...

DPS_Status	DPS_AckPublicationBufs (const DPS_Publication pub, const DPS_Buffer bufs, size_t numBufs, DPS_AckPublicationBufsComplete cb, void *data)
	Acknowledge a publication. More...

DPS_Publication *	DPS_CopyPublication (const DPS_Publication *pub)
	Creates a partial copy of a publication that can be used to acknowledge the publication. More...

DPS_Publication *	DPS_CreatePublication (DPS_Node *node)
	Allocates storage for a publication. More...

DPS_Status	DPS_DestroyPublication (DPS_Publication *pub, DPS_OnPublicationDestroyed cb)
	Delete a publication and frees any resources allocated. More...

void *	DPS_GetPublicationData (const DPS_Publication *pub)
	Get application data pointer previously set by DPS_SetPublicationData() More...

DPS_Status	DPS_InitPublication (DPS_Publication pub, const char topics, size_t numTopics, int noWildCard, const DPS_KeyId keyId, DPS_AcknowledgementHandler handler)
	Initializes a newly created publication with a set of topics. More...

DPS_Status	DPS_PublicationAddSubId (DPS_Publication pub, const DPS_KeyId keyId)
	Adds a key identifier to use for encrypted publications. More...

DPS_Node *	DPS_PublicationGetNode (const DPS_Publication *pub)
	Get the local node associated with a publication. More...

size_t	DPS_PublicationGetNumTopics (const DPS_Publication *pub)
	Get the number of topics in a publication. More...

const DPS_KeyId *	DPS_PublicationGetSenderKeyId (const DPS_Publication *pub)
	Get the key identifier of a publication. More...

uint32_t	DPS_PublicationGetSequenceNum (const DPS_Publication *pub)
	Get the sequence number for a publication. More...

const char *	DPS_PublicationGetTopic (const DPS_Publication *pub, size_t index)
	Get a topic for a publication. More...

int16_t	DPS_PublicationGetTTL (const DPS_Publication *pub)
	Get the TTL for a publication. More...

const DPS_UUID *	DPS_PublicationGetUUID (const DPS_Publication *pub)
	Get the UUID for a publication. More...

int	DPS_PublicationIsAckRequested (const DPS_Publication *pub)
	Check if an acknowledgement was requested for a publication. More...

void	DPS_PublicationRemoveSubId (DPS_Publication pub, const DPS_KeyId keyId)
	Removes a key identifier to use for encrypted publications. More...

DPS_Status	DPS_Publish (DPS_Publication pub, const uint8_t pubPayload, size_t len, int16_t ttl)
	Publish a set of topics along with an optional payload. More...

DPS_Status	DPS_PublishBufs (DPS_Publication pub, const DPS_Buffer bufs, size_t numBufs, int16_t ttl, DPS_PublishBufsComplete cb, void *data)
	Publish a set of topics along with an optional payload. More...

DPS_Status	DPS_SetPublicationData (DPS_Publication pub, void data)
	Store a pointer to application data in a publication. More...

Detailed Description

Publications.

Typedef Documentation

◆ DPS_AcknowledgementHandler

typedef void(* DPS_AcknowledgementHandler) (DPS_Publication *pub, uint8_t *payload, size_t len)

Function prototype for a publication acknowledgement handler called when an acknowledgement for a publication is received from a remote subscriber.

The handler is called for each subscriber that generates an acknowledgement so may be called numerous times for same publication.

Parameters

pub	Opaque handle for the publication that was received
payload	Payload accompanying the acknowledgement if any
len	Length of the payload

◆ DPS_AckPublicationBufsComplete

typedef void(* DPS_AckPublicationBufsComplete) (DPS_Publication *pub, const DPS_Buffer *bufs, size_t numBufs, DPS_Status status, void *data)

Called when DPS_AckPublicationBufs() completes.

Parameters

pub	The publication
bufs	The payload buffers passed to DPS_AckPublicationBufs()
numBufs	The number of payload buffers passed to DPS_AckPublicationBufs()
status	The status of the publish
data	Application data passed to DPS_AckPublicationBufs()

◆ DPS_OnPublicationDestroyed

typedef void(* DPS_OnPublicationDestroyed) (DPS_Publication *pub)

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

Parameters

pub	The publication that was destroyed. This is valid during the callback.

◆ DPS_PublishBufsComplete

typedef void(* DPS_PublishBufsComplete) (DPS_Publication *pub, const DPS_Buffer *bufs, size_t numBufs, DPS_Status status, void *data)

Called when DPS_PublishBufs() completes.

Parameters

pub	The publication
bufs	The payload buffers passed to DPS_PublishBufs()
numBufs	The number of payload buffers passed to DPS_PublishBufs()
status	The status of the publish
data	Application data passed to DPS_PublishBufs()

Function Documentation

◆ DPS_AckGetSenderKeyId()

const DPS_KeyId* DPS_AckGetSenderKeyId ( const DPS_Publication * pub )

Get the key identifier of an acknowledgement, only valid with the body of the DPS_AcknowledgementHandler function.

Parameters

pub	The pub parameter of DPS_AcknowledgementHandler

Returns: The key identifier of the subscriber, may be NULL

◆ DPS_AckGetSequenceNum()

uint32_t DPS_AckGetSequenceNum ( const DPS_Publication * pub )

Get the sequence number being acknowledged, only valid with the body of the DPS_AcknowledgementHandler function.

Parameters

pub	The pub parameter of DPS_AcknowledgementHandler

Returns: The sequence number of the acknowledged publication.

◆ DPS_AckPublication()

DPS_Status DPS_AckPublication	(	const DPS_Publication *	pub,
		const uint8_t *	ackPayload,
		size_t	len
	)

Acknowledge a publication.

A publication should be acknowledged as soon as possible after receipt, ideally from within the publication handler callback function. If the publication cannot be acknowledged immediately in the publication handler callback, call DPS_CopyPublication() to make a partial copy of the publication that can be passed to this function at a later time.

Parameters

pub	The publication to acknowledge
ackPayload	Optional payload to accompany the acknowledgement
len	The length of the payload

Returns: DPS_OK if acknowledge is successful, an error otherwise

◆ DPS_AckPublicationBufs()

DPS_Status DPS_AckPublicationBufs	(	const DPS_Publication *	pub,
		const DPS_Buffer *	bufs,
		size_t	numBufs,
		DPS_AckPublicationBufsComplete	cb,
		void *	data
	)

Acknowledge a publication.

A publication should be acknowledged as soon as possible after receipt, ideally from within the publication handler callback function. If the publication cannot be acknowledged immediately in the publication handler callback, call DPS_CopyPublication() to make a partial copy of the publication that can be passed to this function at a later time.

Parameters

pub	The publication to acknowledge
bufs	Optional payload buffers - this memory must remain valid until the callback function is called
numBufs	The number of buffers
cb	Callback function called when the acknowledge is complete
data	Data to be passed to the callback function

Returns: DPS_OK if acknowledge is successful, an error otherwise

◆ DPS_CopyPublication()

DPS_Publication* DPS_CopyPublication ( const DPS_Publication * pub )

Creates a partial copy of a publication that can be used to acknowledge the publication.

The copy is not useful for anything other than in a call to DPS_AckPublication() and should be freed by calling DPS_DestroyPublication() when no longer needed.

The partial copy can be used with DPS_PublicationGetUUID() and DPS_PublicationGetSequenceNum()

Parameters

pub	The publication to copy

Returns: A partial copy of the publication or NULL if the publication could not be copied.

◆ DPS_CreatePublication()

DPS_Publication* DPS_CreatePublication ( DPS_Node * node )

Allocates storage for a publication.

Parameters

node	The local node to use

Returns: The newly created publication, or NULL if creation failed

◆ DPS_DestroyPublication()

DPS_Status DPS_DestroyPublication	(	DPS_Publication *	pub,
		DPS_OnPublicationDestroyed	cb
	)

Delete a publication and frees any resources allocated.

This does not cancel retained publications that have an unexpired TTL. To expire a retained publication call DPS_Publish() with a negative TTL.

This function should only be called for publications created by DPS_CreatePublication() or DPS_CopyPublication().

Parameters

pub	The publication to destroy
cb	Callback function to be called when the publication is destroyed

Returns: DPS_OK if destroy is successful, an error otherwise

◆ DPS_GetPublicationData()

void* DPS_GetPublicationData ( const DPS_Publication * pub )

Get application data pointer previously set by DPS_SetPublicationData()

Parameters

pub	The publication

Returns: A pointer to the data or NULL if the publication is invalid

◆ DPS_InitPublication()

DPS_Status DPS_InitPublication	(	DPS_Publication *	pub,
		const char **	topics,
		size_t	numTopics,
		int	noWildCard,
		const DPS_KeyId *	keyId,
		DPS_AcknowledgementHandler	handler
	)

Initializes a newly created publication with a set of topics.

Each publication has a UUID and a sequence number. The sequence number is incremented each time the publication is published. This allows subscriber to determine that publications received form a series. The acknowledgement handler is optional, if present the publication is marked as requesting acknowledgement and that information is provided to the subscribers.

Call the accessor function DPS_PublicationGetUUID() to get the UUID for this publication.

Parameters

pub	The publication to initialize
topics	The topic strings to publish
numTopics	The number of topic strings to publish - must be >= 1
noWildCard	If TRUE the publication will not match wildcard subscriptions
keyId	Optional key identifier to use for encrypted publications
handler	Optional handler for receiving acknowledgements

Returns: DPS_OK if initialization is successful, an error otherwise

◆ DPS_PublicationAddSubId()

DPS_Status DPS_PublicationAddSubId	(	DPS_Publication *	pub,
		const DPS_KeyId *	keyId
	)

Adds a key identifier to use for encrypted publications.

Parameters

pub	The publication to initialize
keyId	Key identifier to use for encrypted publications

Returns: DPS_OK if addition is successful, an error otherwise

◆ DPS_PublicationGetNode()

DPS_Node* DPS_PublicationGetNode ( const DPS_Publication * pub )

Get the local node associated with a publication.

Parameters

pub	The publication

Returns: The node or NULL if the publication is invalid

◆ DPS_PublicationGetNumTopics()

size_t DPS_PublicationGetNumTopics ( const DPS_Publication * pub )

Get the number of topics in a publication.

Parameters

pub	The publication

Returns: The number of topics.

◆ DPS_PublicationGetSenderKeyId()

const DPS_KeyId* DPS_PublicationGetSenderKeyId ( const DPS_Publication * pub )

Get the key identifier of a publication.

Parameters

pub	The publication

Returns: The key identifier of the publisher, may be NULL

◆ DPS_PublicationGetSequenceNum()

uint32_t DPS_PublicationGetSequenceNum ( const DPS_Publication * pub )

Get the sequence number for a publication.

Serial numbers are always > 0.

Parameters

pub	The publication

Returns: The sequence number or zero if the publication is invalid.

◆ DPS_PublicationGetTopic()

const char* DPS_PublicationGetTopic	(	const DPS_Publication *	pub,
		size_t	index
	)

Get a topic for a publication.

Parameters

pub	The publication
index	The topic index

Returns: The topic string or NULL if the publication or index is invalid.

◆ DPS_PublicationGetTTL()

int16_t DPS_PublicationGetTTL ( const DPS_Publication * pub )

Get the TTL for a publication.

Parameters

pub	The publication

Returns: Time to live in seconds - maximum TTL is about 9 hours

◆ DPS_PublicationGetUUID()

const DPS_UUID* DPS_PublicationGetUUID ( const DPS_Publication * pub )

Get the UUID for a publication.

Parameters

pub	The publication

Returns: The UUID if publication is valid, or NULL otherwise

◆ DPS_PublicationIsAckRequested()

int DPS_PublicationIsAckRequested ( const DPS_Publication * pub )

Check if an acknowledgement was requested for a publication.

Parameters

pub	The publication

Returns: 1 if an acknowledgement was requested, otherwise 0.

◆ DPS_PublicationRemoveSubId()

void DPS_PublicationRemoveSubId	(	DPS_Publication *	pub,
		const DPS_KeyId *	keyId
	)

Removes a key identifier to use for encrypted publications.

Parameters

pub	The publication to initialize
keyId	Key identifier to remove

◆ DPS_Publish()

DPS_Status DPS_Publish	(	DPS_Publication *	pub,
		const uint8_t *	pubPayload,
		size_t	len,
		int16_t	ttl
	)

Publish a set of topics along with an optional payload.

The topics will be published immediately to matching subscribers and then re-published whenever a new matching subscription is received.

Call the accessor function DPS_PublicationGetUUID() to get the UUID for this publication. Call the accessor function DPS_PublicationGetSequenceNum() to get the current sequence number for this publication. The sequence number is incremented each time DPS_Publish() is called for the same publication.

Parameters

pub	The publication to send
pubPayload	Optional payload
len	Length of the payload
ttl	Time to live in seconds - maximum TTL is about 9 hours

Returns: DPS_OK if the topics were successfully published

◆ DPS_PublishBufs()

DPS_Status DPS_PublishBufs	(	DPS_Publication *	pub,
		const DPS_Buffer *	bufs,
		size_t	numBufs,
		int16_t	ttl,
		DPS_PublishBufsComplete	cb,
		void *	data
	)

Publish a set of topics along with an optional payload.

The topics will be published immediately to matching subscribers and then re-published whenever a new matching subscription is received.

Call the accessor function DPS_PublicationGetUUID() to get the UUID for this publication. Call the accessor function DPS_PublicationGetSequenceNum() to get the current sequence number for this publication. The sequence number is incremented each time DPS_Publish() is called for the same publication.

Note: When the ttl is greater than zero, the callback function will not be called until the publication expires, is replaced by a subsequent call to DPS_PublishBufs(), is canceled, or is destroyed.

Parameters

pub	The publication to send
bufs	Optional payload buffers - this memory must remain valid until the callback function is called
numBufs	The number of buffers
ttl	Time to live in seconds - maximum TTL is about 9 hours
cb	Callback function called when the publish is complete
data	Data to be passed to the callback function

Returns: DPS_OK if the topics were successfully published

◆ DPS_SetPublicationData()

DPS_Status DPS_SetPublicationData	(	DPS_Publication *	pub,
		void *	data
	)

Store a pointer to application data in a publication.

Parameters

pub	The publication
data	The data pointer to store

Returns: DPS_OK or an error

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ DPS_AcknowledgementHandler

◆ DPS_AckPublicationBufsComplete

◆ DPS_OnPublicationDestroyed

◆ DPS_PublishBufsComplete

Function Documentation

◆ DPS_AckGetSenderKeyId()

◆ DPS_AckGetSequenceNum()

◆ DPS_AckPublication()

◆ DPS_AckPublicationBufs()

◆ DPS_CopyPublication()

◆ DPS_CreatePublication()

◆ DPS_DestroyPublication()

◆ DPS_GetPublicationData()

◆ DPS_InitPublication()

◆ DPS_PublicationAddSubId()

◆ DPS_PublicationGetNode()

◆ DPS_PublicationGetNumTopics()

◆ DPS_PublicationGetSenderKeyId()

◆ DPS_PublicationGetSequenceNum()

◆ DPS_PublicationGetTopic()

◆ DPS_PublicationGetTTL()

◆ DPS_PublicationGetUUID()

◆ DPS_PublicationIsAckRequested()

◆ DPS_PublicationRemoveSubId()

◆ DPS_Publish()

◆ DPS_PublishBufs()

◆ DPS_SetPublicationData()