RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
ApplicationSupport.h
1 #ifndef ApplicationSupport_h
2 #define ApplicationSupport_h
3 
4 #include "rti_me_c.h"
5 #include "netio/netio_udp.h"
6 #include "disc_dpde/disc_dpde_discovery_plugin.h"
8 
9 /*i
10  * \addtogroup HWAppExModule_AppSupport
11  * @{
12  */
13 
14 #ifdef RTI_WIN32
15 #define snprintf sprintf_s
16 #endif
17 
18 /*i
19  * \brief Value returned by the application to the invoking
20  * shell in case of a successful execution and \ref APP_ARG_KEY_HELP
21  * used as parameter
22  */
23 #define APP_RETVAL_OK 0
24 /*i
25  * \brief Value returned by the application to the invoking
26  * shell in case of an unsuccessful execution.
27  */
28 #define APP_RETVAL_ERROR -1
29 /*i
30  * \brief Value to indicate that an unlimited number
31  * of samples is expected to be written/received.
32  */
33 #define APP_COUNT_UNLIMITED -1
34 
35 struct Application;
36 typedef struct Application Application_t;
37 
38 /* e
39  * \brief User-defined function to read data when some is available.
40  */
41 typedef int (*Application_take_data_fn)(Application_t *application);
42 
43 /*i
44  * \brief Structure containing several configuration parameters exposed by
45  * the application.
46  *
47  * Each member of this data-type represents a custom configuration parameter
48  * that can be used to control the behavior of an application.
49  * Initialization of instances of this type should be carried out using
50  * \ref ApplicationConfig_INITIALIZER, for statically allocated values, or
51  * \ref ApplicationConfig_initialize, for dynamically allocated ones.
52  */
53 typedef struct ApplicationConfig {
54  /*i
55  * \brief DDS Domain ID to join.
56  *
57  * (default value: 0)
58  */
59  DDS_Long domain_id;
60  /*i
61  * \brief Whether the application should be publishing
62  * or subscribing to data.
63  *
64  * (default value: false)
65  */
66  DDS_Boolean publish;
67  /*i
68  * \brief Whether to use best effort (RTI_TRUE)
69  * or reliable (RTI_FALSE) communication.
70  *
71  * (default value: false)
72  */
73  DDS_Boolean best_effort;
74  /*i
75  * \brief Whether a subscribing application should
76  * wait for data by using a listener installed on
77  * the DataReader or by using a WaitSet instance
78  * with the DataReader's StatusCondition attached
79  * to it.
80  *
81  * (default value: false)
82  */
83  DDS_Boolean use_waitset;
84  /*i
85  * \brief Whether a subscribing application should
86  * filter data samples using callback
87  * on_before_sample_commit of a DataReader's listener.
88  *
89  * If this functionality is enabled, then \ref filter_deserialized
90  * must be disabled.
91  *
92  * (default value: false)
93  */
94  DDS_Boolean filter_commit;
95  /*i
96  * \brief Whether a subscribing application should
97  * filter data samples using callback
98  * on_before_sample_deserialize of a DataReader's listener.
99  *
100  * If this functionality is enabled, then \ref filter_commit
101  * must be disabled.
102  *
103  * (default value: false)
104  */
105  DDS_Boolean filter_deserialized;
106  /*i
107  * \brief Whether the application should use dynamic or
108  * static DDS discovery to detect other applications
109  * in the same DDS domain.
110  *
111  * (default value: true)
112  */
113  DDS_Boolean use_dynamic_discovery;
114  /*i
115  * \brief Whether the application should rely on automatic
116  * configuration of network interfaces based on information
117  * provided by the OS or it should instead statically configure
118  * the interface's parameters
119  *
120  * (default value: false)
121  */
122  DDS_Boolean use_static_interface;
123  /*i
124  * \brief A pointer to the TypePlugin to be used by the application.
125  *
126  * The TypePlugin is used to register the data type on the
127  * application's DomainParticipant.
128  *
129  * (default value: NULL)
130  */
131  struct NDDS_Type_Plugin *type_plugin;
132  /*i
133  * \brief Numerical ID of the DataWriter used by the application
134  * (if publishing).
135  *
136  * This value is used along with static
137  * DDS discovery, to identify the writer's end-point when
138  * statically asserting the existence of its remote publication.
139  *
140  * (default value: \ref DEFAULT_ENTITY_ID_WRITER)
141  */
142  DDS_BUILTIN_TOPIC_KEY_TYPE_NATIVE entity_id_writer;
143  /*i
144  * \brief Numerical ID of the DataReader used by the application
145  * (if subscribing).
146  *
147  * This value is used along with static
148  * DDS discovery, to identify the reader's end-point when
149  * statically asserting the existence of its remote subscription.
150  *
151  * (default value: \ref DEFAULT_ENTITY_ID_READER)
152  */
153  DDS_BUILTIN_TOPIC_KEY_TYPE_NATIVE entity_id_reader;
154  /*i
155  * \brief Name of the participant used by the application when publishing data.
156  *
157  * This value is used along with static DDS discovery, to identify
158  * the remote DomainParticipant and assert his existence.
159  *
160  * (default value: \ref DEFAULT_PART_NAME_WRITER)
161  */
162  DDS_Char part_name_writer[DDS_ENTITYNAME_QOS_NAME_MAX];
163  /*i
164  * \brief Name of the participant used by the application when subscribing data.
165  *
166  * This value is used along with static DDS discovery, to identify
167  * the remote DomainParticipant and assert his existence.
168  *
169  * (default value: \ref DEFAULT_PART_NAME_READER)
170  */
171  DDS_Char part_name_reader[DDS_ENTITYNAME_QOS_NAME_MAX];
172  /*i
173  * \brief Name of the topic that will be used by the application to exchange
174  * data.
175  *
176  * (default value: \ref DEFAULT_TOPIC_NAME)
177  */
178  DDS_Char topic_name[RTPS_PATHNAME_LEN_MAX+1];
179  /*i
180  * \brief Name of the type that will be used by the application.
181  *
182  * This is a custom name that is specified when a data-type's TypePlugin
183  * is registered on a DomainParticipant. It can be any non-empty value,
184  * but every DomainParticipant that wants to exchange samples through a
185  * topic of this type must have registered it with the same name in order
186  * for discovery and endpoint matching to be carried out successfully.
187  *
188  * (default value: \ref return value of function
189  * HelloWorldTypeSupport_get_type_name()).
190  */
191  DDS_Char type_name[RTPS_PATHNAME_LEN_MAX+1];
192  /*i
193  * \brief Name of the loopback network interface that will be enabled for
194  * communication.
195  *
196  * (default value: \ref DEFAULT_INTERFACE_LOOP)
197  */
198  DDS_Char interface_loop[DDS_ENTITYNAME_QOS_NAME_MAX];
199  /*i
200  * \brief Name of the external network interface that will be enabled for
201  * communication.
202  *
203  * (default value: \ref DEFAULT_INTERFACE_UDP)
204  */
205  DDS_Char interface_udp[DDS_ENTITYNAME_QOS_NAME_MAX];
206  /*i
207  * \brief Address or hostname of a network peer that will be added to the
208  * list of peers initially contacted for DDS endpoint discovery.
209  *
210  * (default value: \ref DEFAULT_PEER)
211  */
213  /*i
214  * \brief Number of seconds between successive application operations.
215  *
216  * Used to determine:
217  * - Time between successive data sample writes.
218  * - Time-out of reading operations (when using \ref DDS_WaitSet_wait
219  * or when actively waiting for samples to be received by an
220  * asynchronous listener).
221  *
222  * (default value: \ref DEFAULT_SLEEP_SEC)
223  */
224  DDS_Long sleep_time;
225  /*i
226  * \brief Number of samples that an application must wait to
227  * write/receive before terminating
228  *
229  * (default value: \ref APP_COUNT_UNLIMITED)
230  */
231  DDS_Long count_expected;
232  /*i
233  * \brief Number of seconds that the subscriber will run
234  * before application finishes
235  *
236  * Used to determine:
237  * - Publisher : Maximum time a publisher will run when value of
238  * \ref count_expected is not APP_COUNT_UNLIMITED. In case value
239  * of \ref count_expected is APP_COUNT_UNLIMITED the publisher
240  * will not stop.
241  * - Subscriber : Maximum time a subscriber will run when value of
242  * \ref count_expected is not APP_COUNT_UNLIMITED. In case value
243  * of \ref count_expected is APP_COUNT_UNLIMITED the subscriber
244  * will not stop.
245  *
246  * (default value: \ref APP_COUNT_UNLIMITED)
247  */
248  DDS_Long run_window;
249  /*i
250  * \brief QoS configuration for DDS_DomainParticipantFactory.
251  *
252  * (default value: \ref DDS_DomainParticipantFactoryQos_INITIALIZER)
253  */
254  struct DDS_DomainParticipantFactoryQos qos_factory;
255  /*i
256  * \brief QoS configuration for DDS_DomainParticipant.
257  *
258  * (default value: \ref DDS_DomainParticipantQos_INITIALIZER)
259  */
260  struct DDS_DomainParticipantQos qos_participant;
261  /*i
262  * \brief QoS configuration for DDS_DataReader.
263  *
264  * (default value: \ref DDS_DataReaderQos_INITIALIZER)
265  */
266  struct DDS_DataReaderQos qos_reader;
267  /*i
268  * \brief QoS configuration for DDS_DataWriter.
269  *
270  * (default value: \ref DDS_DataWriterQos_INITIALIZER)
271  */
272  struct DDS_DataWriterQos qos_writer;
273  /*i
274  * \brief DDS_DataReaderListener that will be installed on the
275  * DataReader used by the application.
276  *
277  * (default value: \ref DDS_DataReaderListener_INITIALIZER)
278  */
279  struct DDS_DataReaderListener listener_reader;
280  /*i
281  * \brief DDS_DataWriterListener that will be installed on the
282  * DataWriter used by the application.
283  *
284  * (default value: \ref DDS_DataWriterListener_INITIALIZER)
285  */
286  struct DDS_DataWriterListener listener_writer;
287  /*i
288  * \brief DDS_StatusMask used to install the configured DDS_DataReaderListener.
289  *
290  * (default value: \ref DDS_STATUS_MASK_NONE)
291  */
292  DDS_StatusMask listener_reader_mask;
293  /*i
294  * \brief DDS_StatusMask used to install the configured DDS_DataWriterListener.
295  *
296  * (default value: \ref DDS_STATUS_MASK_NONE)
297  */
298  DDS_StatusMask listener_writer_mask;
299  /*i
300  * \brief DDS_StatusMask used to enable statuses on the
301  * DataReader's StatusCondition when using a DDS_WaitSet
302  * to receive data or consume other DDS events.
303  *
304  * (default value: \ref DDS_STATUS_MASK_NONE)
305  */
306  DDS_StatusMask waitset_mask;
307  /*i
308  * \brief Call-back function provided by the user that will be invoked
309  * whenever new data samples are received.
310  *
311  * (default value: NULL)
312  */
313  Application_take_data_fn take_data;
314  /*i
315  * \brief Type-specific function used to determine whether a data-type
316  * has a key or is unkeyed. Required when asserting a remote
317  * subscription/publication to enable static endpoint discovery.
318  *
319  * (default value: NULL)
320  */
322  /*i
323  * \brief Type-specific function used to determine whether a data-type
324  * has a key or is unkeyed. Required when asserting a remote
325  * subscription/publication to enable static endpoint discovery.
326  *
327  * (default value: APP_VERBOSITY)
328  */
329  OSAPI_LogVerbosity_T verbosity;
330 } ApplicationConfig_t;
331 
332 /*i
333  * \brief Default DDS domain ID
334  */
335 #define DEFAULT_DOMAIN_ID 0
336 
337 /*i
338  * \brief Default numerical ID of a DataWriter
339  */
340 #define DEFAULT_ENTITY_ID_WRITER 100
341 
342 /*i
343  * \brief Default numerical ID of a DataReader
344  */
345 #define DEFAULT_ENTITY_ID_READER 200
346 
347 /*i
348  * \brief Default name of a publishing DomainParticipant
349  */
350 #define DEFAULT_PART_NAME_WRITER "HelloWorldPublisher"
351 
352 /*i
353  * \brief Default name of a subscribing DomainParticipant
354  */
355 #define DEFAULT_PART_NAME_READER "HelloWorldSubscriber"
356 
357 /*i
358  * \brief Default name of the topic used by the application
359  */
360 #define DEFAULT_TOPIC_NAME "HelloWorldTopic"
361 
362 /*i
363  * \brief Default address of the network peer that will be initially
364  * contacted for DDS endpoint discovery.
365  */
366 #define DEFAULT_PEER "127.0.0.1"
367 
368 /*i
369  * \brief Default log verbosity
370  */
371 #define DEFAULT_LOG_VERBOSITY OSAPI_LOG_VERBOSITY_ERROR
372 
373 #if defined(RTI_DARWIN)
374 /*i
375  * \brief Default UDP network interface.
376  */
377 #define DEFAULT_UDP_INTERFACE "en1"
378 #elif defined (RTI_LINUX)
379 #define DEFAULT_UDP_INTERFACE "eth0"
380 #elif defined (RTI_VXWORKS)
381 #define DEFAULT_UDP_INTERFACE "geisc0"
382 #elif defined(RTI_WIN32)
383 #define DEFAULT_UDP_INTERFACE "Local Area Connection"
384 #else
385 #define DEFAULT_UDP_INTERFACE "ce0"
386 #endif
387 
388 #if defined(RTI_DARWIN)
389 /*i
390  * \brief Default loopback network interface.
391  */
392 #define DEFAULT_LOOP_INTERFACE "lo0"
393 #elif defined (RTI_LINUX)
394 #define DEFAULT_LOOP_INTERFACE "lo"
395 #elif defined (RTI_VXWORKS)
396 #define DEFAULT_LOOP_INTERFACE "lo0"
397 #elif defined(RTI_WIN32)
398 #define DEFAULT_LOOP_INTERFACE "Loopback Pseudo-Interface 1"
399 #else
400 #define DEFAULT_LOOP_INTERFACE "lo0"
401 #endif
402 
403 /*i
404  * \brief Default sleep_time in seconds.
405  */
406 #define DEFAULT_SLEEP_SEC 1
407 
408 /*i
409  * \brief Value to indicate that the subscriber will run
410  * for a maximum of 24 hours.
411  */
412 #define DEFAULT_RUN_WINDOW_SEC (24 * 60 * 60)
413 
414 /*i
415  * \brief Initialization value for statically allocated instances
416  * of \ref ApplicationConfig_t.
417  */
418 #define ApplicationConfig_INITIALIZER \
419 {\
420  DEFAULT_DOMAIN_ID,\
421  DDS_BOOLEAN_FALSE,\
422  DDS_BOOLEAN_FALSE,\
423  DDS_BOOLEAN_FALSE,\
424  DDS_BOOLEAN_FALSE,\
425  DDS_BOOLEAN_FALSE,\
426  DDS_BOOLEAN_TRUE,\
427  DDS_BOOLEAN_FALSE,\
428  NULL,\
429  DEFAULT_ENTITY_ID_WRITER,\
430  DEFAULT_ENTITY_ID_READER,\
431  DEFAULT_PART_NAME_WRITER,\
432  DEFAULT_PART_NAME_READER,\
433  DEFAULT_TOPIC_NAME,\
434  "", /* must be changed in code by HelloWorldTypeSupport_get_type_name() */ \
435  DEFAULT_LOOP_INTERFACE,\
436  DEFAULT_UDP_INTERFACE,\
437  DEFAULT_PEER,\
438  DEFAULT_SLEEP_SEC,\
439  APP_COUNT_UNLIMITED,\
440  DEFAULT_RUN_WINDOW_SEC, \
441  DDS_DomainParticipantFactoryQos_INITIALIZER,\
442  DDS_DomainParticipantQos_INITIALIZER,\
443  DDS_DataReaderQos_INITIALIZER,\
444  DDS_DataWriterQos_INITIALIZER,\
445  DDS_DataReaderListener_INITIALIZER,\
446  DDS_DataWriterListener_INITIALIZER,\
447  DDS_STATUS_MASK_NONE,\
448  DDS_STATUS_MASK_NONE,\
449  DDS_STATUS_MASK_NONE,\
450  NULL,\
451  NULL,\
452  DEFAULT_LOG_VERBOSITY,\
453 }
454 
455 /*i
456  * \brief Initializes an instance of \ref ApplicationConfig_t to its
457  * default values.
458  */
459 extern void
460 ApplicationConfig_initialize(ApplicationConfig_t *config);
461 
462 /*i
463  * \brief Finalizes an instance of \ref ApplicationConfig_t, releasing
464  * any memory allocated by its members.
465  */
466 extern void
467 ApplicationConfig_finalize(ApplicationConfig_t *config);
468 
469 /*i
470  * \brief Populates an instance of \ref ApplicationConfig_t using
471  * values passed by users through the command line.
472  */
473 extern DDS_Boolean
474 ApplicationConfig_parse_arguments(
475  ApplicationConfig_t *config, int argc, char** argv);
476 
477 /*i
478  * \brief Prints the contents of an instance of \ref ApplicationConfig_t
479  * to the standard output for debug purposes.
480  */
481 extern void
482 ApplicationConfig_print(ApplicationConfig_t *config);
483 
484 /*i
485  * \brief State of a generic DDS application.
486  *
487  * This data-type contains references to any resource/entity created by
488  * the application and required to carry out its functionalities.
489  * It is used to access these resources in the application code and to
490  * properly manage their life-cycle (i.e. finalizing them at shutdown).
491  */
492 typedef struct Application {
493  /*i
494  * \brief User-specified configuration
495  */
496  ApplicationConfig_t config;
497  /*i
498  * \brief Property used to initialize UDP transport
499  */
500  struct UDP_InterfaceFactoryProperty property_udp;
501  /*i
502  * \brief Property used to initialize DPDE module for dynamic DDS discovery.
503  */
504  struct DPDE_DiscoveryPluginProperty property_dpde;
505  /*i
506  * \brief Property used to initialize DPSE module for static DDS discovery.
507  */
508  struct DPSE_DiscoveryPluginProperty property_dpse;
509  /*i
510  * \brief Value used to assert the existence of a remote publication, when
511  * using static DDS discovery.
512  */
513  struct DDS_PublicationBuiltinTopicData rem_publication_data;
514  /*i
515  * \brief Value used to assert the existence of a remote subscription, when
516  * using static DDS discovery.
517  */
518  struct DDS_SubscriptionBuiltinTopicData rem_subscription_data;
519  /*
520  * \brief DDS_DomainParticipant used to access a DDS domain.
521  */
522  DDS_DomainParticipant *participant;
523  /*i
524  * \brief DDS_Publisher used to create DDS_DataWriter endpoints.
525  */
526  DDS_Publisher *publisher;
527  /*i
528  * \brief DDS_Subscriber used to create DDS_DataReader endpoints.
529  */
530  DDS_Subscriber *subscriber;
531  /*i
532  * \brief DDS_Topic used to communicate between remote applications.
533  */
534  DDS_Topic *topic;
535  /*i
536  * \brief DDS_DataReader used to received data from the DDS domain.
537  */
538  DDS_DataReader *reader;
539  /*i
540  * \brief DDS_DataWriter used to publish data to the DDS domain.
541  */
542  DDS_DataWriter *writer;
543  /*i
544  * \brief DDS_WaitSet used to wait for data to be received
545  * from the DDS domain.
546  */
547  DDS_WaitSet *waitset;
548  /*i
549  * \brief DDS_StatusCondition of the DDS_DataReader.
550  */
551  DDS_StatusCondition *condition_dr;
552  /*i
553  * \brief Sequence of DDS_Condition used to store the result of
554  * DDS_WaitSet_wait, when waiting for data to be received.
555  */
556  struct DDS_ConditionSeq active_conditions;
557  /*i
558  * \brief Current number of data-samples that have been processed
559  * (written/received) by the application so far.
560  */
561  DDS_Long count_processed;
562  /*i
563  * \brief This field is only used by the writer. When
564  * \ref on_publication_matched callback is called this field
565  * is set to RTI_TRUE. Publisher application will not write
566  * any data until this field is RTI_TRUE, so until at least
567  * one subscriber has been matched.
568  */
569  RTI_BOOL publication_matched_called;
570 } Application_t;
571 
572 
573 /*i
574  * \brief Creates a new instance of \ref Application_t and initializes
575  * it using the specified configuration.
576  */
577 extern Application_t*
578 Application_create(ApplicationConfig_t *config);
579 
580 /*i
581  * \brief Deletes an instance of \ref Application_t created using
582  * \ref Application_create.
583  */
584 extern void
585 Application_delete(Application_t *application);
586 
587 /*i
588  * \brief Enables the DDS entities of an application
589  */
590 extern DDS_Boolean
591 Application_enable(Application_t *application);
592 
593 /*i
594  * \brief Blocks the invoking thread until new data samples have been received.
595  */
596 extern void
597 Application_wait_for_data(Application_t *application);
598 
599 /*i
600  * \brief Prints help text for the application to standard output
601  */
602 extern void
603 Application_help(char *appname);
604 
605 /*i
606  * \brief Implementation of \ref DDS_DataReaderListener::on_data_available
607  */
608 extern void
609 Application_ListenerHelper_on_data_available(
610  void *listener_data,
611  DDS_DataReader * reader);
612 
613 /*i
614  * \brief Implementation of \ref DDS_DataReaderListener::on_subscription_matched
615  */
616 extern void
617 Application_ListenerHelper_on_subscription_matched(
618  void *listener_data,
619  DDS_DataReader * reader,
620  const struct
622 
623 /*i
624  * \brief Implementation of \ref DDS_DataWriterListener::on_publication_matched
625  */
626 extern void
627 Application_ListenerHelper_on_publication_matched(
628  void *listener_data,
629  DDS_DataWriter * writer,
630  const struct DDS_PublicationMatchedStatus *status);
631 
632 /*i
633  * @}
634  */
635 
636 #endif

RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc