Data Structures
struct	_DPS_KeyStore

Macros
#define	A_SIZEOF(a) (sizeof(a) / sizeof((a)[0]))

#define	DPS_TRUE 1

#define	DPS_FALSE 0

#define	DPS_MCAST_PUB_DISABLED 0

#define	DPS_MCAST_PUB_ENABLE_SEND 1

#define	DPS_MCAST_PUB_ENABLE_RECV 2

Typedefs
typedef struct _DPS_Node	DPS_Node
	Opaque type for a node. More...

typedef struct _DPS_NodeAddress	DPS_NodeAddress
	Opaque type for a remote node address. More...

typedef struct _DPS_Subscription	DPS_Subscription
	Opaque type for a subscription. More...

typedef struct _DPS_Publication	DPS_Publication
	Opaque type for a publication. More...

typedef struct _DPS_KeyStore	DPS_KeyStore

typedef DPS_Status(*	DPS_ContentKeyCallback) (DPS_KeyStore keyStore, const DPS_UUID kid, uint8_t *key, size_t keyLen)
	Function prototype for callback function for requesting the encryption key for a specific key identifier. More...

typedef DPS_Status(*	DPS_NetworkKeyCallback) (DPS_KeyStore keyStore, uint8_t buffer, size_t bufferLen, size_t *keyLen)

typedef struct _DPS_MemoryKeyStore	DPS_MemoryKeyStore

typedef void(*	DPS_OnNodeDestroyed) (DPS_Node node, void data)
	Function prototype for callback function called when a node is destroyed. More...

typedef void(*	DPS_AcknowledgementHandler) (DPS_Publication pub, uint8_t payload, size_t len)
	Function prototype for a publication acknowledgment handler called when an acknowledgement for a publication is received from a remote subscriber. 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 void(*	DPS_OnLinkComplete) (DPS_Node node, DPS_NodeAddress addr, DPS_Status status, void *data)
	Function prototype for function called when a DPS_Link() completes. More...

typedef void(*	DPS_OnUnlinkComplete) (DPS_Node node, DPS_NodeAddress addr, void *data)
	Function prototype for function called when a DPS_Unlink() completes. More...

typedef void(*	DPS_OnResolveAddressComplete) (DPS_Node node, DPS_NodeAddress addr, void *data)
	Function prototype for function called when a DPS_ResolveAddress() completes. More...

Functions
const char *	DPS_SubscriptionGetTopic (const DPS_Subscription *sub, size_t index)
	Get a topic for an active subscription. More...

size_t	DPS_SubscriptionGetNumTopics (const DPS_Subscription *sub)
	Get the number of topics registered with an active subscription. More...

const DPS_UUID *	DPS_PublicationGetUUID (const DPS_Publication *pub)
	Get the UUID for 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...

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

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

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

DPS_MemoryKeyStore *	DPS_CreateMemoryKeyStore ()

void	DPS_DestroyMemoryKeyStore (DPS_MemoryKeyStore *mks)

DPS_Status	DPS_SetContentKey (DPS_MemoryKeyStore mks, const DPS_UUID kid, uint8_t *key, size_t keyLen)

DPS_Status	DPS_SetNetworkKey (DPS_MemoryKeyStore mks, uint8_t key, size_t keyLen)

DPS_KeyStore *	DPS_MemoryKeyStoreHandle (DPS_MemoryKeyStore *mks)

DPS_Node *	DPS_CreateNode (const char separators, DPS_KeyStore keyStore, const DPS_UUID *keyId)
	Allocates space for a local DPS node. More...

DPS_Status	DPS_SetNodeData (DPS_Node node, void data)
	Store a pointer to application data in a node. More...

void *	DPS_GetNodeData (const DPS_Node *node)
	Get application data pointer previously set by DPS_SetNodeData() More...

DPS_Status	DPS_StartNode (DPS_Node *node, int mcastPub, int listenPort)
	Initialized and starts running a local node. More...

DPS_Status	DPS_DestroyNode (DPS_Node node, DPS_OnNodeDestroyed cb, void data)
	Destroys a node and free any resources. More...

uv_loop_t *	DPS_GetLoop (DPS_Node *node)
	Get the uv event loop for this node. More...

DPS_Publication *	DPS_CreatePublication (DPS_Node *node)
	Allocates storage for 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_Status	DPS_SetPublicationData (DPS_Publication pub, void data)
	Store a pointer to application data in a publication. 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_UUID keyId, DPS_AcknowledgementHandler handler)
	Initializes a newly created publication with a set of topics. 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_DestroyPublication (DPS_Publication *pub)
	Delete a publication and frees any resources allocated. More...

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

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

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_SetSubscriptionData (DPS_Subscription sub, void data)
	Store a pointer to application data in a subscription. More...

void *	DPS_GetSubscriptionData (DPS_Subscription *sub)
	Get application data pointer previously set by DPS_SetSubscriptionData() More...

DPS_Node *	DPS_SubscriptionGetNode (const DPS_Subscription *sub)
	Get the local node associated with a subscription. More...

DPS_Status	DPS_Subscribe (DPS_Subscription *sub, DPS_PublicationHandler handler)
	Start subscribing to a set of topics. More...

DPS_Status	DPS_DestroySubscription (DPS_Subscription *sub)
	Stop subscribing to the subscription topic and free resources allocated for the subscription. More...

DPS_Status	DPS_Link (DPS_Node node, DPS_NodeAddress addr, DPS_OnLinkComplete cb, void *data)
	Link the local node to a remote node. More...

DPS_Status	DPS_Unlink (DPS_Node node, DPS_NodeAddress addr, DPS_OnUnlinkComplete cb, void *data)
	Unlink the local node from a remote node. More...

uint16_t	DPS_GetPortNumber (DPS_Node *node)
	Get the port number this node is listening for connections on. More...

DPS_Status	DPS_ResolveAddress (DPS_Node node, const char host, const char service, DPS_OnResolveAddressComplete cb, void data)
	Resolve a host name or IP address and service name or port number. More...

const char *	DPS_NodeAddrToString (DPS_NodeAddress *addr)
	Get text representation of an address. More...

DPS_NodeAddress *	DPS_CreateAddress ()
	Creates an node address. More...

DPS_NodeAddress *	DPS_SetAddress (DPS_NodeAddress addr, const struct sockaddr sa)
	Set a node address. More...

void	DPS_CopyAddress (DPS_NodeAddress dest, const DPS_NodeAddress src)
	Copy a node address. More...

void	DPS_DestroyAddress (DPS_NodeAddress *addr)
	Frees resources associated with an address. More...

uint32_t	DPS_Rand ()
	Returns a non-secure random number. More...

Macro Definition Documentation

#define A_SIZEOF ( a ) (sizeof(a) / sizeof((a)[0]))

#define DPS_FALSE 0

#define DPS_MCAST_PUB_DISABLED 0

#define DPS_MCAST_PUB_ENABLE_RECV 2

#define DPS_MCAST_PUB_ENABLE_SEND 1

#define DPS_TRUE 1

Typedef Documentation

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

Function prototype for a publication acknowledgment 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

typedef DPS_Status(* DPS_ContentKeyCallback) (DPS_KeyStore *keyStore, const DPS_UUID *kid, uint8_t *key, size_t keyLen)

Function prototype for callback function for requesting the encryption key for a specific key identifier.

This function must not block

Parameters

node	The node that is requesting the key
kid	The key identifier
key	Buffer for returning the key.
keyLen	Size of the key buffer

Returns: DPS_OK if a key matching the kid was returned DPS_ERR_MSSING if there is no matching key

typedef struct _DPS_KeyStore DPS_KeyStore

typedef struct _DPS_MemoryKeyStore DPS_MemoryKeyStore

typedef DPS_Status(* DPS_NetworkKeyCallback) (DPS_KeyStore *keyStore, uint8_t *buffer, size_t bufferLen, size_t *keyLen)

typedef struct _DPS_Node DPS_Node

Opaque type for a node.

typedef struct _DPS_NodeAddress DPS_NodeAddress

Opaque type for a remote node address.

typedef void(* DPS_OnLinkComplete) (DPS_Node *node, DPS_NodeAddress *addr, DPS_Status status, void *data)

Function prototype for function called when a DPS_Link() completes.

Parameters

node	The local node to use
addr	The address of the remote node that was linked
status	Indicates if the link completed or failed
data	Application data passed in the call to DPS_Link()

typedef void(* DPS_OnNodeDestroyed) (DPS_Node *node, void *data)

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

Parameters

node	The node that was destroyed. This pointer is valid during the callback.
data	Data pointer passed to DPS_DestroyNode()

typedef void(* DPS_OnResolveAddressComplete) (DPS_Node *node, DPS_NodeAddress *addr, void *data)

Function prototype for function called when a DPS_ResolveAddress() completes.

Parameters

node	The local node to use
addr	The resolved address or NULL if the address could not be resolved
data	Application data passed in the call to DPS_ResolveAddress()

typedef void(* DPS_OnUnlinkComplete) (DPS_Node *node, DPS_NodeAddress *addr, void *data)

Function prototype for function called when a DPS_Unlink() completes.

Parameters

node	The local node to use
addr	The address of the remote node that was unlinked
data	Application data passed in the call to DPS_Link()

typedef struct _DPS_Publication DPS_Publication

Opaque type for a publication.

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 possibilitly 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

typedef struct _DPS_Subscription DPS_Subscription

Opaque type for a subscription.

Function Documentation

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

Aknowledge 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 acknowedged 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 aknowledgment
len	The length of the payload

void DPS_CopyAddress	(	DPS_NodeAddress *	dest,
		const DPS_NodeAddress *	src
	)

Copy a node address.

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_DestroyPublcation() 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_NodeAddress* DPS_CreateAddress ( )

Creates an node address.

DPS_MemoryKeyStore* DPS_CreateMemoryKeyStore ( )

DPS_Node* DPS_CreateNode	(	const char *	separators,
		DPS_KeyStore *	keyStore,
		const DPS_UUID *	keyId
	)

Allocates space for a local DPS node.

Parameters

separators	The separator characters to use for topic matching, if NULL defaults to "/"
keyStore	The key store to use for this node
keyId	Encryption key id to use for publications sent from this node

Returns: A pointer to the uninitialized node or NULL if there were no resources for the node.

DPS_Publication* DPS_CreatePublication ( DPS_Node * node )

Allocates storage for a publication.

Parameters

node	The local node to use

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: Returns a pointer to the newly created subscription or NULL if resources could not be allocated or the arguments were invalid

void DPS_DestroyAddress ( DPS_NodeAddress * addr )

Frees resources associated with an address.

void DPS_DestroyMemoryKeyStore ( DPS_MemoryKeyStore * mks )

DPS_Status DPS_DestroyNode	(	DPS_Node *	node,
		DPS_OnNodeDestroyed	cb,
		void *	data
	)

Destroys a node and free any resources.

Parameters

node	The node to destroy
cb	Callback function to be called when the node is destroyed
data	Data to be passed to the callback function

Returns: -DPS_OK if the node will be destroyed and the callback called -DPS_ERR_NULL node or cb was a null pointer -Or an error status code in which case the callback will not be called.

DPS_Status DPS_DestroyPublication ( DPS_Publication * pub )

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 zero TTL.

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

Parameters

pub	The publication to destroy

DPS_Status DPS_DestroySubscription ( DPS_Subscription * sub )

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

Parameters

sub	The subscription to cancel

uv_loop_t* DPS_GetLoop ( DPS_Node * node )

Get the uv event loop for this node.

The only thing that is safe to do with the node is to create an async callback. Other libuv APIs can then be called from within the async callback.

Parameters

node	The local node to use

void* DPS_GetNodeData ( const DPS_Node * node )

Get application data pointer previously set by DPS_SetNodeData()

Parameters

node The node

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

uint16_t DPS_GetPortNumber ( DPS_Node * node )

Get the port number this node is listening for connections on.

Parameters

node	The local node to use

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_Node* DPS_GetPublicationNode ( const DPS_Publication * pub )

Get the local node associated with a publication.

Parameters

pub	A publication

Returns: Returns the local node associated with a publication

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_Status DPS_InitPublication	(	DPS_Publication *	pub,
		const char **	topics,
		size_t	numTopics,
		int	noWildCard,
		const DPS_UUID *	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 acknowledgment handler is optional, if present the publication is marked as requesting acknowledgment and that information is provided to the subscribers.

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

Parameters

pub	The 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 acknowledgments

DPS_Status DPS_Link	(	DPS_Node *	node,
		DPS_NodeAddress *	addr,
		DPS_OnLinkComplete	cb,
		void *	data
	)

Link the local node to a remote node.

Parameters

node	The local node to use
addr	The address of the remote node to link to
cb	The callback function to call on completion, can be NULL which case the function is synchronous
data	Application data to be passed to the callback

Returns: DPS_OK or an error status. If an error status is returned the callback function will not be called.

DPS_KeyStore* DPS_MemoryKeyStoreHandle ( DPS_MemoryKeyStore * mks )

const char* DPS_NodeAddrToString ( DPS_NodeAddress * addr )

Get text representation of an address.

This function uses a static string buffer so is not thread safe.

Parameters

addr	to get the text for

Returns: A text string for the address

DPS_Node* DPS_PublicationGetNode ( const DPS_Publication * pub )

Get the local node associated with a publication.

Parameters

pub	The publication

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

size_t DPS_PublicationGetNumTopics ( const DPS_Publication * pub )

Get the number of topics in a publication.

Parameters

pub	The publication

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.

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.

const DPS_UUID* DPS_PublicationGetUUID ( const DPS_Publication * pub )

Get the UUID for a publication.

Parameters

pub	The publication

int DPS_PublicationIsAckRequested ( const DPS_Publication * pub )

Check if an acknowledgement was requested for a publication.

Parameters

pub	The publication

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

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 succesfully published

uint32_t DPS_Rand ( )

Returns a non-secure random number.

DPS_Status DPS_ResolveAddress	(	DPS_Node *	node,
		const char *	host,
		const char *	service,
		DPS_OnResolveAddressComplete	cb,
		void *	data
	)

Resolve a host name or IP address and service name or port number.

Parameters

node	The local node to use
host	The host name or IP address to resolve
service	The port or service name to resolve
cb	The callback function to call on completion
data	Application data to be passed to the callback

Returns: DPS_OK or an error status. If an error status is returned the callback function will not be called.

DPS_NodeAddress* DPS_SetAddress	(	DPS_NodeAddress *	addr,
		const struct sockaddr *	sa
	)

Set a node address.

Parameters

addr	The address to set
sa	The value to set

Returns: The addr passed in.

DPS_Status DPS_SetContentKey	(	DPS_MemoryKeyStore *	mks,
		const DPS_UUID *	kid,
		uint8_t *	key,
		size_t	keyLen
	)

DPS_Status DPS_SetNetworkKey	(	DPS_MemoryKeyStore *	mks,
		uint8_t *	key,
		size_t	keyLen
	)

DPS_Status DPS_SetNodeData	(	DPS_Node *	node,
		void *	data
	)

Store a pointer to application data in a node.

Parameters

node	The node
data	The data pointer to store

Returns: DPS_OK or and error

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 and error

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_Status DPS_StartNode	(	DPS_Node *	node,
		int	mcastPub,
		int	listenPort
	)

Initialized and starts running a local node.

Node can only be started once. stopped.

Parameters

node	The node
mcastPub	Indicates if this node sends or listens for multicast publications
listenPort	If non-zero identifies specific port to listen on

Returns: DPS_OK or various error status codes

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

DPS_Node* DPS_SubscriptionGetNode ( const DPS_Subscription * sub )

Get the local node associated with a subscription.

Parameters

sub	The subscription

Returns: A pointer to the node or NULL if the subscription is invalid

size_t DPS_SubscriptionGetNumTopics ( const DPS_Subscription * sub )

Get the number of topics registered with an active subscription.

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.

DPS_Status DPS_Unlink	(	DPS_Node *	node,
		DPS_NodeAddress *	addr,
		DPS_OnUnlinkComplete	cb,
		void *	data
	)

Unlink the local node from a remote node.

Parameters

node	The local node to use
addr	The address of the remote node to unlink from
cb	The callback function to call on completion, can be NULL which case the function is synchronous
data	Application data to be passed to the callback

Returns: DPS_OK or an error status. If an error status is returned the callback function will not be called.

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation