Topic Functions

Functions
NT_Topic *	NT_GetTopics (NT_Inst inst, const struct WPI_String *prefix, unsigned int types, size_t *count)
	Get Published Topic Handles.
NT_Topic *	NT_GetTopicsStr (NT_Inst inst, const struct WPI_String *prefix, const struct WPI_String *types, size_t types_len, size_t *count)
	Get Published Topic Handles.
struct NT_TopicInfo *	NT_GetTopicInfos (NT_Inst inst, const struct WPI_String *prefix, unsigned int types, size_t *count)
	Get Topics.
struct NT_TopicInfo *	NT_GetTopicInfosStr (NT_Inst inst, const struct WPI_String *prefix, const struct WPI_String *types, size_t types_len, size_t *count)
	Get Topics.
NT_Bool	NT_GetTopicInfo (NT_Topic topic, struct NT_TopicInfo *info)
	Gets Topic Information.
NT_Topic	NT_GetTopic (NT_Inst inst, const struct WPI_String *name)
	Gets Topic Handle.
void	NT_GetTopicName (NT_Topic topic, struct WPI_String *name)
	Gets the name of the specified topic.
enum NT_Type	NT_GetTopicType (NT_Topic topic)
	Gets the type for the specified topic, or unassigned if non existent.
void	NT_GetTopicTypeString (NT_Topic topic, struct WPI_String *type)
	Gets the type string for the specified topic.
void	NT_SetTopicPersistent (NT_Topic topic, NT_Bool value)
	Sets the persistent property of a topic.
NT_Bool	NT_GetTopicPersistent (NT_Topic topic)
	Gets the persistent property of a topic.
void	NT_SetTopicRetained (NT_Topic topic, NT_Bool value)
	Sets the retained property of a topic.
NT_Bool	NT_GetTopicRetained (NT_Topic topic)
	Gets the retained property of a topic.
void	NT_SetTopicCached (NT_Topic topic, NT_Bool value)
	Sets the cached property of a topic.
NT_Bool	NT_GetTopicCached (NT_Topic topic)
	Gets the cached property of a topic.
NT_Bool	NT_GetTopicExists (NT_Handle handle)
	Determine if topic exists (e.g.
void	NT_GetTopicProperty (NT_Topic topic, const struct WPI_String *name, struct WPI_String *property)
	Gets the current value of a property (as a JSON string).
NT_Bool	NT_SetTopicProperty (NT_Topic topic, const struct WPI_String *name, const struct WPI_String *value)
	Sets a property value.
void	NT_DeleteTopicProperty (NT_Topic topic, const struct WPI_String *name)
	Deletes a property.
void	NT_GetTopicProperties (NT_Topic topic, struct WPI_String *properties)
	Gets all topic properties as a JSON string.
NT_Bool	NT_SetTopicProperties (NT_Topic topic, const struct WPI_String *properties)
	Updates multiple topic properties.
NT_Subscriber	NT_Subscribe (NT_Topic topic, enum NT_Type type, const struct WPI_String *typeStr, const struct NT_PubSubOptions *options)
	Creates a new subscriber to value changes on a topic.
void	NT_Unsubscribe (NT_Subscriber sub)
	Stops subscriber.
NT_Publisher	NT_Publish (NT_Topic topic, enum NT_Type type, const struct WPI_String *typeStr, const struct NT_PubSubOptions *options)
	Creates a new publisher to a topic.
NT_Publisher	NT_PublishEx (NT_Topic topic, enum NT_Type type, const struct WPI_String *typeStr, const struct WPI_String *properties, const struct NT_PubSubOptions *options)
	Creates a new publisher to a topic.
void	NT_Unpublish (NT_Handle pubentry)
	Stops publisher.
NT_Entry	NT_GetEntryEx (NT_Topic topic, enum NT_Type type, const struct WPI_String *typeStr, const struct NT_PubSubOptions *options)
	Creates a new entry (subscriber and weak publisher) to a topic.
void	NT_ReleaseEntry (NT_Entry entry)
	Stops entry subscriber/publisher.
void	NT_Release (NT_Handle pubsubentry)
	Stops entry/subscriber/publisher.
NT_Topic	NT_GetTopicFromHandle (NT_Handle pubsubentry)
	Gets the topic handle from an entry/subscriber/publisher handle.

Detailed Description

Function Documentation

NT_DeleteTopicProperty()

void NT_DeleteTopicProperty	(	NT_Topic	topic,
		const struct WPI_String *	name )

Deletes a property.

Has no effect if the property does not exist.

Parameters

topic	topic handle
name	property name

NT_GetEntryEx()

NT_Entry NT_GetEntryEx	(	NT_Topic	topic,
		enum NT_Type	type,
		const struct WPI_String *	typeStr,
		const struct NT_PubSubOptions *	options )

Creates a new entry (subscriber and weak publisher) to a topic.

Parameters

topic	topic handle
type	type
typeStr	type string
options	publish options

Returns

Entry handle

NT_GetTopic()

NT_Topic NT_GetTopic	(	NT_Inst	inst,
		const struct WPI_String *	name )

Gets Topic Handle.

Returns topic handle.

Parameters

inst	instance handle
name	topic name

Returns

Topic handle.

NT_GetTopicCached()

NT_Bool NT_GetTopicCached

(

NT_Topic

topic

)

Gets the cached property of a topic.

Parameters

topic

topic handle

Returns

cached property value

NT_GetTopicExists()

NT_Bool NT_GetTopicExists

(

NT_Handle

handle

)

Determine if topic exists (e.g.

has at least one publisher).

Parameters

handle

Topic, entry, or subscriber handle.

Returns

True if topic exists.

NT_GetTopicFromHandle()

NT_Topic NT_GetTopicFromHandle

(

NT_Handle

pubsubentry

)

Gets the topic handle from an entry/subscriber/publisher handle.

Parameters

pubsubentry

entry/subscriber/publisher handle

Returns

Topic handle

NT_GetTopicInfo()

NT_Bool NT_GetTopicInfo	(	NT_Topic	topic,
		struct NT_TopicInfo *	info )

Gets Topic Information.

Returns information about a topic (name and type).

Parameters

topic	handle
info	information (output)

Returns

True if successful, false on error.

NT_GetTopicInfos()

struct NT_TopicInfo * NT_GetTopicInfos	(	NT_Inst	inst,
		const struct WPI_String *	prefix,
		unsigned int	types,
		size_t *	count )

Get Topics.

Returns an array of topic information (handle, name, type). The results are optionally filtered by string prefix and type to only return a subset of all topics.

Parameters

inst	instance handle
prefix	name required prefix; only topics whose name starts with this string are returned
types	bitmask of NT_Type values; 0 is treated specially as a "don't care"
count	output parameter; set to length of returned array

Returns

Array of topic information.

NT_GetTopicInfosStr()

struct NT_TopicInfo * NT_GetTopicInfosStr	(	NT_Inst	inst,
		const struct WPI_String *	prefix,
		const struct WPI_String *	types,
		size_t	types_len,
		size_t *	count )

Get Topics.

Returns an array of topic information (handle, name, type). The results are optionally filtered by string prefix and type to only return a subset of all topics.

Parameters

inst	instance handle
prefix	name required prefix; only topics whose name starts with this string are returned
types	array of type strings
types_len	number of elements in types array
count	output parameter; set to length of returned array

Returns

Array of topic information.

NT_GetTopicName()

void NT_GetTopicName	(	NT_Topic	topic,
		struct WPI_String *	name )

Gets the name of the specified topic.

Parameters

topic	topic handle
name	topic name (output); return length of 0 and nullptr if handle is invalid.

NT_GetTopicPersistent()

NT_Bool NT_GetTopicPersistent

(

NT_Topic

topic

)

Gets the persistent property of a topic.

Parameters

topic

topic handle

Returns

persistent property value

NT_GetTopicProperties()

void NT_GetTopicProperties	(	NT_Topic	topic,
		struct WPI_String *	properties )

Gets all topic properties as a JSON string.

Each key in the object is the property name, and the corresponding value is the property value.

Parameters

topic	topic handle
properties	JSON string (output)

NT_GetTopicProperty()

void NT_GetTopicProperty	(	NT_Topic	topic,
		const struct WPI_String *	name,
		struct WPI_String *	property )

Gets the current value of a property (as a JSON string).

Parameters

topic	topic handle
name	property name
property	JSON string (output)

NT_GetTopicRetained()

NT_Bool NT_GetTopicRetained

(

NT_Topic

topic

)

Gets the retained property of a topic.

Parameters

topic

topic handle

Returns

retained property value

NT_GetTopics()

NT_Topic * NT_GetTopics	(	NT_Inst	inst,
		const struct WPI_String *	prefix,
		unsigned int	types,
		size_t *	count )

Get Published Topic Handles.

Returns an array of topic handles. The results are optionally filtered by string prefix and type to only return a subset of all topics.

Parameters

inst	instance handle
prefix	name required prefix; only topics whose name starts with this string are returned
types	bitmask of NT_Type values; 0 is treated specially as a "don't care"
count	output parameter; set to length of returned array

Returns

Array of topic handles.

NT_GetTopicsStr()

NT_Topic * NT_GetTopicsStr	(	NT_Inst	inst,
		const struct WPI_String *	prefix,
		const struct WPI_String *	types,
		size_t	types_len,
		size_t *	count )

Get Published Topic Handles.

Returns an array of topic handles. The results are optionally filtered by string prefix and type to only return a subset of all topics.

Parameters

inst	instance handle
prefix	name required prefix; only topics whose name starts with this string are returned
types	array of type strings
types_len	number of elements in types array
count	output parameter; set to length of returned array

Returns

Array of topic handles.

NT_GetTopicType()

enum NT_Type NT_GetTopicType

(

NT_Topic

topic

)

Gets the type for the specified topic, or unassigned if non existent.

Parameters

topic

topic handle

Returns

Topic type

NT_GetTopicTypeString()

void NT_GetTopicTypeString	(	NT_Topic	topic,
		struct WPI_String *	type )

Gets the type string for the specified topic.

This may have more information than the numeric type (especially for raw values).

Parameters

topic	topic handle
type	topic type string (output)

NT_Publish()

NT_Publisher NT_Publish	(	NT_Topic	topic,
		enum NT_Type	type,
		const struct WPI_String *	typeStr,
		const struct NT_PubSubOptions *	options )

Creates a new publisher to a topic.

Parameters

topic	topic handle
type	type
typeStr	type string
options	publish options

Returns

Publisher handle

NT_PublishEx()

NT_Publisher NT_PublishEx	(	NT_Topic	topic,
		enum NT_Type	type,
		const struct WPI_String *	typeStr,
		const struct WPI_String *	properties,
		const struct NT_PubSubOptions *	options )

Creates a new publisher to a topic.

Parameters

topic	topic handle
type	type
typeStr	type string
properties	initial properties (JSON object)
options	publish options

Returns

Publisher handle

NT_Release()

void NT_Release

(

NT_Handle

pubsubentry

)

Stops entry/subscriber/publisher.

Parameters

pubsubentry

entry/subscriber/publisher handle

NT_ReleaseEntry()

void NT_ReleaseEntry

(

NT_Entry

entry

)

Stops entry subscriber/publisher.

Parameters

entry

entry handle

NT_SetTopicCached()

void NT_SetTopicCached	(	NT_Topic	topic,
		NT_Bool	value )

Sets the cached property of a topic.

If true, the server and clients will store the latest value, allowing the value to be read (and not just accessed through event queues and listeners).

Parameters

topic	topic handle
value	True for cached, false for not cached

NT_SetTopicPersistent()

void NT_SetTopicPersistent	(	NT_Topic	topic,
		NT_Bool	value )

Sets the persistent property of a topic.

If true, the stored value is persistent through server restarts.

Parameters

topic	topic handle
value	True for persistent, false for not persistent.

NT_SetTopicProperties()

NT_Bool NT_SetTopicProperties	(	NT_Topic	topic,
		const struct WPI_String *	properties )

Updates multiple topic properties.

Each key in the passed-in JSON object is the name of the property to add/update, and the corresponding value is the property value to set for that property. Null values result in deletion of the corresponding property.

Parameters

topic	topic handle
properties	JSON object string with keys to add/update/delete

Returns

False if properties are not a valid JSON object

NT_SetTopicProperty()

NT_Bool NT_SetTopicProperty	(	NT_Topic	topic,
		const struct WPI_String *	name,
		const struct WPI_String *	value )

Sets a property value.

Parameters

topic	topic handle
name	property name
value	property value (JSON string)

NT_SetTopicRetained()

void NT_SetTopicRetained	(	NT_Topic	topic,
		NT_Bool	value )

Sets the retained property of a topic.

If true, the server retains the topic even when there are no publishers.

Parameters

topic	topic handle
value	new retained property value

NT_Subscribe()

NT_Subscriber NT_Subscribe	(	NT_Topic	topic,
		enum NT_Type	type,
		const struct WPI_String *	typeStr,
		const struct NT_PubSubOptions *	options )

Creates a new subscriber to value changes on a topic.

Parameters

topic	topic handle
type	expected type
typeStr	expected type string
options	subscription options

Returns

Subscriber handle

NT_Unpublish()

void NT_Unpublish

(

NT_Handle

pubentry

)

Stops publisher.

Parameters

pubentry

publisher/entry handle

NT_Unsubscribe()

void NT_Unsubscribe

(

NT_Subscriber

sub

)

Stops subscriber.

Parameters

sub	subscriber handle