Entities in the DPS network. More...

Macros
#define	DPS_LINK_LOSS_TIMEOUT 30000
	This establishes the base rate at which keep-alive subscription messages are sent to remote nodes. More...

#define	DPS_MCAST_PUB_DISABLED 0
	Disable multicast send and receive on the node. More...

#define	DPS_MCAST_PUB_ENABLE_RECV 2
	Enable multicast receive on the node. More...

#define	DPS_MCAST_PUB_ENABLE_SEND 1
	Enable multicast send on the node. More...

#define	DPS_SUBSCRIPTION_UPDATE_RATE 2000
	The default maximum rate (in msecs) to compute and send out subscription updates. More...

Typedefs
typedef struct _DPS_Node	DPS_Node
	Opaque type for a node.

typedef void(*	DPS_OnLinkComplete) (DPS_Node node, const DPS_NodeAddress addr, DPS_Status status, void *data)
	Function prototype for function called when a DPS_Link() completes. More...

typedef void(*	DPS_OnLinkLoss) (DPS_Node node, const DPS_NodeAddress addr, void *data)
	Function prototype for function called when a link is lossed. More...

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

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

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

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

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

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

const DPS_NodeAddress *	DPS_GetListenAddress (DPS_Node *node)
	Get the address this node is listening for connections on. More...

const char *	DPS_GetListenAddressString (DPS_Node *node)
	Get text representation of the address this node is listening for connections on. More...

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

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

DPS_Status	DPS_LinkTo (DPS_Node node, const char addrText, DPS_NodeAddress *addr)
	Synchronous helper that wraps DPS_Link(). 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...

DPS_Status	DPS_SetLinkLossCallback (DPS_Node node, DPS_OnLinkLoss cb, void data)
	Set a callback function to called when a link explicily established by this node was lost. More...

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

void	DPS_SetNodeLinkLossTimeout (DPS_Node *node, uint32_t linkLossMsecs)
	Override the default link-loss detection timeout (in msecs) More...

void	DPS_SetNodeSubscriptionUpdateDelay (DPS_Node *node, uint32_t subsRateMsecs)
	Override the default time delay (in msecs) between subscription updates. More...

DPS_Status	DPS_ShutdownNode (DPS_Node node, DPS_OnNodeShutdown cb, void data)
	Shutdowns a node. More...

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

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

DPS_Status	DPS_UnlinkFrom (DPS_Node node, const DPS_NodeAddress addr)
	Synchronous helper that wraps DPS_Unlink(). More...

Detailed Description

Entities in the DPS network.

Macro Definition Documentation

◆ DPS_LINK_LOSS_TIMEOUT

#define DPS_LINK_LOSS_TIMEOUT 30000

This establishes the base rate at which keep-alive subscription messages are sent to remote nodes.

This timeout governs how long it takes to detect a mesh disconnect and start a recovery process. This timeout value should be much larger than DPS_SUBSCRIPTION_UPDATE_RATE.

◆ DPS_MCAST_PUB_DISABLED

#define DPS_MCAST_PUB_DISABLED 0

Disable multicast send and receive on the node.

See mcastPub of DPS_StartNode().

◆ DPS_MCAST_PUB_ENABLE_RECV

#define DPS_MCAST_PUB_ENABLE_RECV 2

Enable multicast receive on the node.

See mcastPub of DPS_StartNode().

◆ DPS_MCAST_PUB_ENABLE_SEND

#define DPS_MCAST_PUB_ENABLE_SEND 1

Enable multicast send on the node.

See mcastPub of DPS_StartNode().

◆ DPS_SUBSCRIPTION_UPDATE_RATE

#define DPS_SUBSCRIPTION_UPDATE_RATE 2000

The default maximum rate (in msecs) to compute and send out subscription updates.

This causes subscription updates coming in from multiple remote nodes to be batched up for forwarding. This reduces network traffic when new nodes join the mesh, particularly at startup time, at the cost of increased latency for the propagation of subscriptions across the mesh. New subscriptions local to a node are not subject to this timeout value and are set immediately to adjacent nodes.

Typedef Documentation

◆ DPS_OnLinkComplete

typedef void(* DPS_OnLinkComplete) (DPS_Node *node, const 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. A status of DPS_ERR_EXISTS indicates the remote node is already linked.
data	Application data passed in the call to DPS_Link()

◆ DPS_OnLinkLoss

typedef void(* DPS_OnLinkLoss) (DPS_Node *node, const DPS_NodeAddress *addr, void *data)

Function prototype for function called when a link is lossed.

Parameters

node	The local node that lost a link
addr	The address of the remote node that was unlinked
data	Application data passed in the call to DPS_SetLinkLossCallback()

◆ DPS_OnNodeDestroyed

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 node is valid during the callback.
data	Data passed to DPS_DestroyNode()

◆ DPS_OnNodeShutdown

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

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

Shutdown cleanly unlinks any nodes from this node. DPS_DestroyNode() does not.

Parameters

node	The node that was shutdown. This node is valid during the callback.
data	Data passed to DPS_ShutdownNode()

◆ DPS_OnResolveAddressComplete

typedef void(* DPS_OnResolveAddressComplete) (DPS_Node *node, const 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()

◆ DPS_OnUnlinkComplete

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

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

Parameters

node	The local node that was unlinked from a remote node
addr	The address of the remote node that was unlinked
data	Application data passed in the call to DPS_Unlink()

Function Documentation

◆ DPS_CreateNode()

DPS_Node* DPS_CreateNode	(	const char *	separators,
		DPS_KeyStore *	keyStore,
		const DPS_KeyId *	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	The key identifier of this node

Returns: The uninitialized node or NULL if there were no resources for the node.

◆ DPS_DestroyNode()

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 null
Or an error status code in which case the callback will not be called.

◆ DPS_GetListenAddress()

const DPS_NodeAddress* DPS_GetListenAddress ( DPS_Node * node )

Get the address this node is listening for connections on.

Parameters

node The node

Returns: The address

◆ DPS_GetListenAddressString()

const char* DPS_GetListenAddressString ( DPS_Node * node )

Get text representation of the address this node is listening for connections on.

Parameters

node The node

Returns: A text string for the address

◆ DPS_GetNodeData()

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

◆ DPS_Link()

DPS_Status DPS_Link	(	DPS_Node *	node,
		const char *	addrText,
		DPS_OnLinkComplete	cb,
		void *	data
	)

Link the local node to a remote node.

Parameters

node	The local node to use
addrText	The text string of the address to link to
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_LinkTo()

DPS_Status DPS_LinkTo	(	DPS_Node *	node,
		const char *	addrText,
		DPS_NodeAddress *	addr
	)

Synchronous helper that wraps DPS_Link().

Parameters

node	The local node to link from
addrText	The text string of the address to link to
addr	Returns the resolved address for the remote node

Returns

DPS_OK if the link is successful,
DPS_ERR_EXISTS if the address is already linked to,
an error otherwise

◆ DPS_ResolveAddress()

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_SetLinkLossCallback()

DPS_Status DPS_SetLinkLossCallback	(	DPS_Node *	node,
		DPS_OnLinkLoss	cb,
		void *	data
	)

Set a callback function to called when a link explicily established by this node was lost.

This function is only called in the case of a surprise link-loss, not when DPS_Unlink() was called.

Parameters

node	The local node
cb	The callback function to call on loss of a link
data	Application data to be passed to the callback

Returns: DPS_OK if successful, an error otherwise

◆ DPS_SetNodeData()

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

◆ DPS_SetNodeLinkLossTimeout()

void DPS_SetNodeLinkLossTimeout	(	DPS_Node *	node,
		uint32_t	linkLossMsecs
	)

Override the default link-loss detection timeout (in msecs)

Parameters

node	The node
linkLossMsecs	The time for the link to an unresponsive remote node to be considered lost

◆ DPS_SetNodeSubscriptionUpdateDelay()

void DPS_SetNodeSubscriptionUpdateDelay	(	DPS_Node *	node,
		uint32_t	subsRateMsecs
	)

Override the default time delay (in msecs) between subscription updates.

Parameters

node	The node
subsRateMsecs	The time delay (in msecs) between updates

◆ DPS_ShutdownNode()

DPS_Status DPS_ShutdownNode	(	DPS_Node *	node,
		DPS_OnNodeShutdown	cb,
		void *	data
	)

Shutdowns a node.

Parameters

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

Returns

DPS_OK if the node will be shutdown and the callback called
DPS_ERR_NULL node or cb was null
Or an error status code in which case the callback will not be called.

◆ DPS_StartNode()

DPS_Status DPS_StartNode	(	DPS_Node *	node,
		int	mcastPub,
		DPS_NodeAddress *	listenAddr
	)

Initialized and starts running a local node.

Node can only be started once.

Parameters

node	The node
mcastPub	Indicates if this node sends or listens for multicast publications
listenAddr	If non-NULL identifies specific address to listen on

Returns: DPS_OK or various error status codes

◆ DPS_Unlink()

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

Unlink a 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.

◆ DPS_UnlinkFrom()

DPS_Status DPS_UnlinkFrom	(	DPS_Node *	node,
		const DPS_NodeAddress *	addr
	)

Synchronous helper that wraps DPS_Unlink().

Parameters

node	The local node to unlink from
addr	The address of the remote node to unlink

Returns: DPS_OK if the unlink is successful, an error otherwise

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ DPS_LINK_LOSS_TIMEOUT

◆ DPS_MCAST_PUB_DISABLED

◆ DPS_MCAST_PUB_ENABLE_RECV

◆ DPS_MCAST_PUB_ENABLE_SEND

◆ DPS_SUBSCRIPTION_UPDATE_RATE

Typedef Documentation

◆ DPS_OnLinkComplete

◆ DPS_OnLinkLoss

◆ DPS_OnNodeDestroyed

◆ DPS_OnNodeShutdown

◆ DPS_OnResolveAddressComplete

◆ DPS_OnUnlinkComplete

Function Documentation

◆ DPS_CreateNode()

◆ DPS_DestroyNode()

◆ DPS_GetListenAddress()

◆ DPS_GetListenAddressString()

◆ DPS_GetNodeData()

◆ DPS_Link()

◆ DPS_LinkTo()

◆ DPS_ResolveAddress()

◆ DPS_SetLinkLossCallback()

◆ DPS_SetNodeData()

◆ DPS_SetNodeLinkLossTimeout()

◆ DPS_SetNodeSubscriptionUpdateDelay()

◆ DPS_ShutdownNode()

◆ DPS_StartNode()

◆ DPS_Unlink()

◆ DPS_UnlinkFrom()