Creating Topics

18.1.1 Creating Topics

Topics are created using the DomainParticipant’s create_topic() or create_topic_with_profile() operation.

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see 50. Configuring QoS with XML.

DDSTopic * create_topic (
	const char *topic_name, 
	const char *type_name,
	const DDS_TopicQos &qos, 
	DDSTopicListener *listener, 
	DDS_StatusMask mask)

DDSTopic * create_topic_with_profile (
	const char *topic_name, 
	const char *type_name,
	const char *library_name, 
	const char *profile_name,
	DDSTopicListener *listener, 
	DDS_StatusMask mask)

Where:

topic_name	Name for the new Topic, must not exceed 255 characters.
type_name	Name for the user data type, must not exceed 255 characters. It must be the same name that was used to register the DDS type, and the DDS type must be registered with the same DomainParticipant used to create this Topic. See 17.6 Using RTI Code Generator (rtiddsgen).
qos	If you want to use the default QoS settings (described in the API Reference HTML documentation), use DDS_TOPIC_QOS_DEFAULT for this parameter (see Figure 18.2: Creating a Topic with Default QosPolicies ). If you want to customize any of the QosPolicies, supply a QoS structure (see 18.1.3 Setting Topic QosPolicies). If you use DDS_TOPIC_QOS_DEFAULT, it is not safe to create the topic while another thread may be simultaneously calling the DomainParticipant’s set_default_topic_qos() operation.
listener	Listeners are callback routines. Connext uses them to notify your application of specific events (status changes) that may occur with respect to the Topic. The listener parameter may be set to NULL if you do not want to install a Listener. If you use NULL, the Listener of the DomainParticipant to which the Topic belongs will be used instead (if it is set). For more information on TopicListeners, see 18.1.5 Setting Up TopicListeners.
mask	This bit-mask indicates which status changes will cause the Listener to be invoked. The bits in the mask that are set must have corresponding callbacks implemented in the Listener. If you use NULL for the Listener, use DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all callbacks, use DDS_STATUS_MASK_ALL. For information on statuses, see 15.8 Listeners.
library_name	A QoS Library is a named set of QoS profiles. See 50.2 QoS Profiles. If NULL is used for library_name, the DomainParticipant’s default library is assumed.
profile_name	A QoS profile groups a set of related QoS, usually one per entity. See 50.2 QoS Profiles. If NULL is used for profile_name, the DomainParticipant’s default profile is assumed and library_name is ignored.

It is not safe to create a topic while another thread is calling lookup_topicdescription() for that same topic (see 16.3.8 Looking up Topic Descriptions).

Figure 18.2: Creating a Topic with Default QosPolicies

const char *type_name = NULL;
// register the DDS type
type_name = FooTypeSupport::get_type_name();
retcode = FooTypeSupport::register_type(
	participant, type_name);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}

// create the topic
DDSTopic* topic = participant->create_topic(
	"Example Foo", type_name,
	DDS_TOPIC_QOS_DEFAULT, 
	NULL, DDS_STATUS_MASK_NONE);
if (topic == NULL) {
    // process error here
};

For more examples, see 18.1.3.1 Configuring QoS Settings when the Topic is Created.