Listener Functions

Typedefs
typedef void(*	NT_ListenerCallback) (void *data, const struct NT_Event *event)
	Event listener callback function. More...

Functions
NT_ListenerPoller	NT_CreateListenerPoller (NT_Inst inst)
	Creates a listener poller. More...
void	NT_DestroyListenerPoller (NT_ListenerPoller poller)
	Destroys a listener poller. More...
struct NT_Event *	NT_ReadListenerQueue (NT_ListenerPoller poller, size_t *len)
	Read notifications. More...
void	NT_RemoveListener (NT_Listener listener)
	Removes a listener. More...
NT_Bool	NT_WaitForListenerQueue (NT_Handle handle, double timeout)
	Wait for the listener queue to be empty. More...
NT_Listener	NT_AddListenerSingle (NT_Inst inst, const char *prefix, size_t prefix_len, unsigned int mask, void *data, NT_ListenerCallback callback)
	Create a listener for changes to topics with names that start with the given prefix. More...
NT_Listener	NT_AddListenerMultiple (NT_Inst inst, const struct NT_String *prefixes, size_t prefixes_len, unsigned int mask, void *data, NT_ListenerCallback callback)
	Create a listener for changes to topics with names that start with any of the given prefixes. More...
NT_Listener	NT_AddListener (NT_Handle handle, unsigned int mask, void *data, NT_ListenerCallback callback)
	Create a listener. More...
NT_Listener	NT_AddPolledListenerSingle (NT_ListenerPoller poller, const char *prefix, size_t prefix_len, unsigned int mask)
	Creates a polled topic listener. More...
NT_Listener	NT_AddPolledListenerMultiple (NT_ListenerPoller poller, const struct NT_String *prefixes, size_t prefixes_len, unsigned int mask)
	Creates a polled topic listener. More...
NT_Listener	NT_AddPolledListener (NT_ListenerPoller poller, NT_Handle handle, unsigned int mask)
	Creates a polled listener. More...

Detailed Description

Typedef Documentation

NT_ListenerCallback

typedef void(* NT_ListenerCallback) (void *data, const struct NT_Event *event)

Event listener callback function.

Parameters

data	data pointer provided to callback creation function
event	event info

Function Documentation

NT_AddListener()

NT_Listener NT_AddListener	(	NT_Handle	handle,
		unsigned int	mask,
		void *	data,
		NT_ListenerCallback	callback
	)

Create a listener.

Some combinations of handle and mask have no effect:

• connection and log message events are only generated on instances
• topic and value events are only generated on non-instances

Adding value and topic events on a topic will create a corresponding internal subscriber with the lifetime of the listener.

Adding a log message listener through this function will only result in events at NT_LOG_INFO or higher; for more customized settings, use NT_AddLogger().

Parameters

handle	Handle
mask	Bitmask of NT_EventFlags values
data	Data passed to callback function
callback	Listener function

Returns

Listener handle

NT_AddListenerMultiple()

NT_Listener NT_AddListenerMultiple	(	NT_Inst	inst,
		const struct NT_String *	prefixes,
		size_t	prefixes_len,
		unsigned int	mask,
		void *	data,
		NT_ListenerCallback	callback
	)

Create a listener for changes to topics with names that start with any of the given prefixes.

This creates a corresponding internal subscriber with the lifetime of the listener.

Parameters

inst	Instance handle
prefixes	Topic name string prefixes
prefixes_len	Number of elements in prefixes array
mask	Bitmask of NT_EventFlags values (only topic and value events will be generated)
data	Data passed to callback function
callback	Listener function

Returns

Listener handle

NT_AddListenerSingle()

NT_Listener NT_AddListenerSingle	(	NT_Inst	inst,
		const char *	prefix,
		size_t	prefix_len,
		unsigned int	mask,
		void *	data,
		NT_ListenerCallback	callback
	)

Create a listener for changes to topics with names that start with the given prefix.

This creates a corresponding internal subscriber with the lifetime of the listener.

Parameters

inst	Instance handle
prefix	Topic name string prefix
prefix_len	Length of topic name string prefix
mask	Bitmask of NT_EventFlags values (only topic and value events will be generated)
data	Data passed to callback function
callback	Listener function

Returns

Listener handle

NT_AddPolledListener()

NT_Listener NT_AddPolledListener	(	NT_ListenerPoller	poller,
		NT_Handle	handle,
		unsigned int	mask
	)

Creates a polled listener.

The caller is responsible for calling NT_ReadListenerQueue() to poll.

Some combinations of handle and mask have no effect:

• connection and log message events are only generated on instances
• topic and value events are only generated on non-instances

Adding value and topic events on a topic will create a corresponding internal subscriber with the lifetime of the listener.

Adding a log message listener through this function will only result in events at NT_LOG_INFO or higher; for more customized settings, use NT_AddPolledLogger().

Parameters

poller	poller handle
handle	handle
mask	NT_NotifyKind bitmask

Returns

Listener handle

NT_AddPolledListenerMultiple()

NT_Listener NT_AddPolledListenerMultiple	(	NT_ListenerPoller	poller,
		const struct NT_String *	prefixes,
		size_t	prefixes_len,
		unsigned int	mask
	)

Creates a polled topic listener.

This creates a corresponding internal subscriber with the lifetime of the listener. The caller is responsible for calling NT_ReadListenerQueue() to poll.

Parameters

poller	poller handle
prefixes	array of UTF-8 string prefixes
prefixes_len	Length of prefixes array
mask	NT_EventFlags bitmask (only topic and value events will be generated)

Returns

Listener handle

NT_AddPolledListenerSingle()

NT_Listener NT_AddPolledListenerSingle	(	NT_ListenerPoller	poller,
		const char *	prefix,
		size_t	prefix_len,
		unsigned int	mask
	)

Creates a polled topic listener.

This creates a corresponding internal subscriber with the lifetime of the listener. The caller is responsible for calling NT_ReadListenerQueue() to poll.

Parameters

poller	poller handle
prefix	UTF-8 string prefix
prefix_len	Length of UTF-8 string prefix
mask	NT_EventFlags bitmask (only topic and value events will be generated)

Returns

Listener handle

NT_CreateListenerPoller()

NT_ListenerPoller NT_CreateListenerPoller

(

NT_Inst

inst

)

Creates a listener poller.

A poller provides a single queue of poll events. Events linked to this poller (using NT_AddPolledXListener()) will be stored in the queue and must be collected by calling NT_ReadListenerQueue(). The returned handle must be destroyed with NT_DestroyListenerPoller().

Parameters

inst	instance handle

Returns

poller handle

NT_DestroyListenerPoller()

void NT_DestroyListenerPoller

(

NT_ListenerPoller

poller

)

Destroys a listener poller.

This will abort any blocked polling call and prevent additional events from being generated for this poller.

Parameters

poller

poller handle

NT_ReadListenerQueue()

struct NT_Event * NT_ReadListenerQueue	(	NT_ListenerPoller	poller,
		size_t *	len
	)

Read notifications.

Parameters

poller	poller handle
len	length of returned array (output)

Returns

Array of events. Returns NULL and len=0 if no events since last call.

NT_RemoveListener()

void NT_RemoveListener

(

NT_Listener

listener

)

Removes a listener.

Parameters

listener

Listener handle to remove

NT_WaitForListenerQueue()

NT_Bool NT_WaitForListenerQueue	(	NT_Handle	handle,
		double	timeout
	)

Wait for the listener queue to be empty.

This is primarily useful for deterministic testing. This blocks until either the listener queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.

Parameters

handle	handle
timeout	timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely

Returns

False if timed out, otherwise true.