RTI Connext DDS Micro  Version 2.4.6
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
rt_rt.h
1 /*
2  * FILE: rt_log.h - RT API
3  *
4  * Copyright 2011-2015 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 04nov2015,tk MICRO-1505 Reduce memory footprint
14  * 02jul2015,tk MICRO-1292/PR#14955 Modified ComponentFactoryProperty
15  * 15may2014,tk MICRO-791 Return RTI_INT32, not RTI_BOOL, in compare function
16  * 05may2014,tk MICRO-72 Updated based on CR-232
17  * 22apr2014,tk MICRO-82 Removed run method, kept base interface class
18  * 12dec2011,tk Written
19  */
20 
21 /*ci
22  * \file
23  * \defgroup RT_RunTimeClass Run-Time
24  * \ingroup RTInternalModule
25  * \brief RT Run-Time API
26  */
27 /*ci \addtogroup RTInternalModule
28  * @{
29  */
30 #ifndef rt_rt_h
31 #define rt_rt_h
32 
33 #ifndef rt_dll_h
34 #include "rt/rt_dll.h"
35 #endif
36 
37 #ifndef osapi_types_h
38 #include "osapi/osapi_types.h"
39 #endif
40 
41 #ifndef osapi_timer_h
42 #include "osapi/osapi_timer.h"
43 #endif
44 
45 #ifndef reda_circularlist_h
46 #include "reda/reda_circularlist.h"
47 #endif
48 
49 #ifndef db_api_h
50 #include "db/db_api.h"
51 #endif
52 
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56 
57 #ifndef NULL
58 #define NULL ((void*)0)
59 #endif
60 
61 #ifdef RTI_CPP
62 #define RT_CPP_SUPPORT_METHODS_BASIC(T) \
63  public:\
64  T();\
65  ~T();\
66  private: \
67  T(const T& from);\
68  T& operator=(const T& from);\
69  bool operator==(const T& other);\
70  bool operator!=(const T& other);
71 #else /* ifdef RTI_CPP */
72 #define RT_CPP_SUPPORT_METHODS_BASIC(T)
73 #endif /* ifdef RTI_CPP */
74 
75 
76 /*******************************************************************************
77  * RTConstants
78  ******************************************************************************/
79 
80 /*ci
81  * \brief Create an interface id from a class and and instance
82  *
83  * \param[in] class_ The interface class
84  * \param[in] instance_ The instance of the interface class
85  *
86  * \return The interface id
87  */
88 #define RT_MKINTERFACEID(class_,instance_) \
89  ((((class_)<<16)&0xffff0000) | (instance_))
90 
91 /*ci
92  * \brief Get the interface class from an interface class id
93  *
94  * \param[in] id_ The interface id
95  *
96  * \return interface class
97  */
98 #define RT_INTERFACE_CLASS(id_) ((id_) >> 16)
99 
100 /*ci
101  * \brief Get the interface class instance from an interface class id
102  *
103  * \param[in] id_ The interface id
104  *
105  * \return interface class instance
106  */
107 #define RT_INTERFACE_INSTANCE(id_) ((id_) & 0xffff)
108 
109 /* INTERFACE CLASSES */
110 /*ci
111  * \brief The unknown interface class
112  */
113 #define RT_COMPONENT_CLASS_UNKNOWN (0x0000)
114 
115 /*ci
116  *\brief The discovery interface class
117  */
118 #define RT_COMPONENT_CLASS_DISCOVERY (0x0001)
119 
120 /*ci
121  *\brief The writer history interface class
122  */
123 #define RT_COMPONENT_CLASS_WHISTORY (0x0002)
124 
125 /*ci
126  *\brief The writer history interface class
127  */
128 #define RT_COMPONENT_CLASS_RHISTORY (0x0003)
129 
130 /*ci
131  *\brief The NETIO interface class
132  */
133 #define RT_COMPONENT_CLASS_NETIO (0x0004)
134 
135 /* DDS Discovery class components */
136 
137 /*ci
138  * \brief The DPDE discovery class instance
139  */
140 #define RT_COMPONENT_INSTANCE_DISCOVERY_DPDE (1)
141 
142 /*ci
143  * \brief The DPSE discovery class instance
144  */
145 #define RT_COMPONENT_INSTANCE_DISCOVERY_DPSE (2)
146 
147 /*ci
148  * \brief DDS WH_SM WriterHistory class instance
149  */
150 #define RT_COMPONENT_INSTANCE_WHISTORY_SM (1)
151 
152 /*ci
153  * \brief DDS RH_SM WriterHistory class instance
154  */
155 #define RT_COMPONENT_INSTANCE_RHISTORY_SM (1)
156 
157 /*ci
158  * \brief UDP NETIO class instance
159  */
160 #define RT_COMPONENT_INSTANCE_UDP (1)
161 
162 /*ci
163  * \brief RTPS NETIO class instance
164  */
165 #define RT_COMPONENT_INSTANCE_RTPS (2)
166 
167 /*ci
168  * \brief INTRA NETIO class instance
169  */
170 #define RT_COMPONENT_INSTANCE_INTRA (3)
171 
172 /*ci
173  * \brief DDS WriterInterface NETIO class instance
174  */
175 #define RT_COMPONENT_INSTANCE_DDSWI (4)
176 
177 /*ci
178  * \brief DDS Readernterface NETIO class instance
179  */
180 #define RT_COMPONENT_INSTANCE_DDSRI (5)
181 
182 /*ci The number of tables created by RT cannot exceed this number. If more tables
183  * are required, increase this number.
184  */
185 #define RT_RESOURCE_TABLES_PER_INSTANCE (1)
186 
187 /*ci
188  * \brief Type used to identify components
189  */
190 typedef RTI_UINT32 RT_ComponentInterfaceId_t;
191 
192 /*******************************************************************************
193  * RT_Component
194  ******************************************************************************/
195 struct RT_Component;
196 
197 /*ci
198  * \brief Abstract RT_Component type
199  */
200 typedef struct RT_Component RT_Component_T;
201 
202 /*ci
203  * \brief Notify listeners on changes in component state.
204  *
205  * \details
206  *
207  * The RT_ComponentListener structure is for future extensions.
208  */
209 struct RT_ComponentListener
210 {
211  /*ci
212  * \brief data passed in listeners
213  */
214  void *data;
215 };
216 
217 /*ci
218  * \brief Initializer for RT_ComponentListener
219  */
220 #define RT_ComponentListener_INITIALIZER \
221 { \
222  NULL \
223 }
224 
225 /*ci
226  * \brief Properties a component can be created with
227  */
228 struct RT_ComponentProperty
229 {
230  /*ci
231  * \brief A database to create tables in if needed
232  */
233  DB_Database_T db;
234 
235  /*ci
236  * \brief A timer to create timeouts from if needed
237  */
238  OSAPI_Timer_T timer;
239 };
240 
241 #define RT_ComponentProperty_INITIALIZER \
242 {\
243  NULL,\
244  NULL \
245 }
246 
247 /*ci
248  * \brief The component base interface
249  */
250 struct RT_ComponentI
251 {
252  /*ci
253  * \brief Some compilers do not allow empty structures. There are
254  * currently no base interface functions required
255  */
256  RTI_INT32 dummy;
257 };
258 
259 /*ci
260  * \brief The component base class
261  */
262 struct RT_Component
263 {
264  /*ci
265  *\brief Pointer to the component interface
266  */
267  struct RT_ComponentI *_intf;
268 
269  /*ci
270  *\brief The component id
271  */
272  RTI_UINT32 id;
273 };
274 
275 /*ci
276  *
277  * \brief Initialize a RT_Component base-class
278  *
279  * \details
280  *
281  * All components must initialized the RT_Component base-class by
282  * calling this function
283  *
284  * \param[in] c The component to initialize
285  * \param[in] intf Pointer to implementation of the RT_ComponentI interface
286  * \param[in] id Unique ID for the component
287  * \param[in] property Properties for the component
288  * \param[in] listener Listeners to call when a component changes
289  *
290  * \sa \ref RT_Component_finalize
291  */
292 RTDllExport void
293 RT_Component_initialize(RT_Component_T *c,
294  struct RT_ComponentI *intf,
295  RTI_UINT32 id,
296  const struct RT_ComponentProperty *const property,
297  const struct RT_ComponentListener *const listener);
298 
299 #ifndef RTI_CERT
300 /*ci
301  *
302  * \brief Finalize a RT_Component base-class
303  *
304  * \details
305  *
306  * All components must be finalized by calling this function
307  *
308  * \param[in] c The component to finalize
309  *
310  * \sa \ref RT_Component_initialize
311  */
312 RTDllExport void
313 RT_Component_finalize(RT_Component_T *c);
314 #endif /* !RTI_CERT */
315 
316 #define RT_COMPONENTI_BASE {0}
317 
318 /*******************************************************************************
319  * RT_ComponentFactoryI
320  ******************************************************************************/
321 struct RT_ComponentFactory;
322 
323 /*ci
324  * \brief Properties a RT_ComponentFactory can be created with
325  */
326 struct RT_ComponentFactoryProperty
327 {
328  /* The "base class" cannot be empty due to some compilers failing,
329  * and there are currently no common factory properties.
330  */
331  void *dummy;
332 };
333 
334 /*ci
335  * \brief Initializer for \ref RT_ComponentFactoryProperty
336  */
337 #define RT_ComponentFactoryProperty_INITIALIZER \
338 { \
339  NULL\
340 }
341 
342 /*ci
343  * \brief Listeners that can be installed on a RT_ComponentFactoryProperty
344  * when it is created
345  */
346 struct RT_ComponentFactoryListener
347 {
348  void *dummy;
349 };
350 
351 /*ci
352  * \brief Initializer for \ref RT_ComponentFactoryListener
353  */
354 #define RT_ComponentFactoryListener_INITIALIZER \
355 {\
356  NULL\
357 }
358 
359 /*ci
360  * \brief Function typedef for a factory initializer
361  *
362  * \param[in] property The property to initialize the factory with
363  * \param[in] listener The listener to initialise the factory with
364  *
365  * \return An implementation of this function must return the initialized
366  * factory on success, NULL otherwise
367  */
368 FUNCTION_MUST_TYPEDEF(
369 struct RT_ComponentFactory*
370 (*RT_ComponentFactory_initializeFactoryFunc)(
371  struct RT_ComponentFactoryProperty *property,
372  struct RT_ComponentFactoryListener *listener)
373 )
374 
375 /*ci
376  * \brief Function typedef for a factory finalizer
377  *
378  * \param[in] factory The factory being finalized
379  * \param[inout] property The property the factory was initialized with if not NULL
380  * \param[inout] listener The listener the factory was initialized with if not NULL
381  *
382  */
383 typedef void
384 (*RT_ComponentFactory_finalizeFactoryFunc)(struct RT_ComponentFactory *factory,
385  struct RT_ComponentFactoryProperty **property,
386  struct RT_ComponentFactoryListener **listener);
387 
388 /*ci
389  * \brief Function typedef for a factory create component function
390  *
391  * \param[in] factory The factory creating an instance of a component
392  * \param[in] property The property for the component
393  * \param[in] listener The listener for the component
394  *
395  * \return An implementation of this function must return the initialized
396  * component on success, NULL otherwise
397  */
398 FUNCTION_MUST_TYPEDEF(
399 RT_Component_T*
400 (*RT_ComponentFactory_createFunc)(struct RT_ComponentFactory *factory,
401  struct RT_ComponentProperty *property,
402  struct RT_ComponentListener *listener)
403 )
404 
405 /*ci
406  * \brief Function typedef for a factory delete component function
407  *
408  * \param[in] factory The factory deleting an instance of a component
409  * \param[in] component The component being deleted
410  *
411  * \return An implementation of this function must return the initialized
412  * component on success, NULL otherwise
413  */
414 typedef void
415 (*RT_ComponentFactory_deleteFunc)(struct RT_ComponentFactory *factory,
416  RT_Component_T* component);
417 
418 /*ci
419  * \brief Function typedef for a factory get interface function
420  *
421  * \param[in] factory The factory to get the interface for
422  *
423  * \return An implementation of this function must return the interface
424  * structure for the component
425  */
426 FUNCTION_MUST_TYPEDEF(
427 struct RT_ComponentI*
428 (*RT_ComponentFactory_get_ifFunc)(struct RT_ComponentFactory *factory)
429 )
430 
431 /*ci
432  * \brief A default factory id if an interface does not specify it
433  */
434 #define RT_COMPONENT_FACTORY_ID_DEFAULT (0)
435 
436 /*ci
437  * \brief The RT_ComponentFactory interface
438  */
439 struct RT_ComponentFactoryI
440 {
441  /*ci
442  * \brief interface id
443  */
444  RTI_INT32 id;
445 
446  /*ci
447  * \brief function to call when the factory is first registered
448  */
449  RT_ComponentFactory_initializeFactoryFunc initialize;
450 
451  /*ci
452  * \brief function to call when the factory is unregistered
453  */
454  RT_ComponentFactory_finalizeFactoryFunc finalize;
455 
456  /*ci
457  * \brief function to call to create an new instance of a component
458  */
459  RT_ComponentFactory_createFunc create_component;
460 
461  /*ci
462  * \brief function to call to delete an instance of a component
463  */
464  RT_ComponentFactory_deleteFunc delete_component;
465 
466  /*ci
467  * \brief function to get the components interface implementation
468  */
469  RT_ComponentFactory_get_ifFunc get_if;
470 };
471 
472 /*ci
473  * \def RT_MAX_FACTORY_NAME
474  * \brief Maximum length of a factory name, it does _not_ include \0
475  */
476 #define RT_MAX_FACTORY_NAME 7
477 
478 /*
479  * Structure to represent a component name as either a 64 bit integer
480  * or name
481  */
482 union DDSCPPDllExport RT_ComponentFactoryId
483 {
484  struct
485  {
486  char _name[RT_MAX_FACTORY_NAME+1];
487  } _name;
488 
489  struct
490  {
491  RTI_UINT32 _high;
492  RTI_UINT32 _low;
493  } _value;
494 
495  RT_CPP_SUPPORT_METHODS_BASIC(RT_ComponentFactoryId)
496 
497 #ifdef RTI_CPP
498 public:
499  bool set_name(const char *const name);
500 #endif
501 };
502 
503 /*
504  * Abstract type for the factory id
505  */
506 typedef union RT_ComponentFactoryId RT_ComponentFactoryId_T;
507 
508 #define RT_ComponentFactoryId_INITIALIZER \
509 {\
510  {{0}} \
511 }
512 
513 /*ci
514  * \brief Clear a factory id
515  *
516  * \param[in] id Id to clear
517  */
518 RTDllExport void
519 RT_ComponentFactoryId_clear(union RT_ComponentFactoryId *id);
520 
521 /*ci
522  * \brief A ComponentFactory base-class. All component factories must derive
523  * from this class
524  */
525 struct RT_ComponentFactory
526 {
527  /*ci
528  * \brief The factory interface
529  */
530  struct RT_ComponentFactoryI *intf;
531 
532  /*ci
533  * \brief The factory instance
534  */
535  struct RT_ComponentFactory *_factory;
536 
537  /*ci
538  * \brief The factory id
539  */
540  union RT_ComponentFactoryId _id;
541 };
542 
543 /*ci
544  * \brief Initializer for the \ref RT_ComponentFactory
545  */
546 #define RT_ComponentFactory_INITIALIZER \
547 { \
548  NULL,\
549  NULL,\
550  {{0,0}}\
551 }
552 
553 /*ci
554  * \brief The abstract component factory type
555  */
556 typedef struct RT_ComponentFactory RT_ComponentFactory_T;
557 
558 /*ci
559  * \brief Properties a \ref RT_Registry can be created with
560  */
561 struct RT_RegistryProperty
562 {
563  /*ci
564  * \brief The maximum number of component factories which can be registered
565  */
566  RTI_SIZE_T max_factories;
567 
568  /*ci
569  * \brief A database the component factory can use, if needed
570  */
571  DB_Database_T db;
572 };
573 
574 /*ci
575  * \brief Initializer for \ref RT_RegistryProperty
576  */
577 #define RT_RegistryProperty_INITIALIZER \
578 { \
579  1,\
580  NULL\
581 }
582 
583 /*ci
584  * \brief Default values for \ref RT_RegistryProperty
585  */
586 extern RTDllVariable struct RT_RegistryProperty
587  RTCOMPONENTFACTORY_REGISTRY_PROPERTY_DEFAULT;
588 
589 /* forward declaraion for the abstract type definition */
590 struct RT_Registry;
591 
592 /*ci
593  * \brief Abstract RT_Registry type
594  */
595 typedef struct RT_Registry RT_Registry_T;
596 
597 /*ci
598  * \brief Get the RT_Registry
599  *
600  * \details
601  *
602  * The RT_Registry exists as a single instance within a process.
603  *
604  * \return pointer to registry on success, NULL on failure
605  *
606  * \sa ref RT_Registry_finalize
607  */
608 SHOULD_CHECK_RETURN RTDllExport RT_Registry_T*
609 RT_Registry_get_instance(void);
610 
611 #ifndef RTI_CERT
612 /*ci
613  * \brief Finalize the RT_Registry
614  *
615  * \details
616  *
617  * The RT_Registry exists as a single instance within a process. This
618  * call finalizes the registry instance. If an already finalized registry
619  * is finalized again nothing is done.
620  *
621  * \return RTI_TRUE on success, RTI_FALSE on failure
622  *
623  * \sa ref RT_Registry_get_instance
624  */
625 SHOULD_CHECK_RETURN RTDllExport RTI_BOOL
626 RT_Registry_finalize(RT_Registry_T*);
627 #endif
628 
629 /*e \dref_RT_Registry_register
630  */
631 MUST_CHECK_RETURN RTDllExport RTI_BOOL
632 RT_Registry_register(RT_Registry_T *registry,
633  const char *name,
634  struct RT_ComponentFactoryI *intf,
635  struct RT_ComponentFactoryProperty *property,
636  struct RT_ComponentFactoryListener *listener);
637 
638 /*e \dref_RT_Registry_unregister
639  */
640 SHOULD_CHECK_RETURN RTDllExport RTI_BOOL
641 RT_Registry_unregister(RT_Registry_T *registry,
642  const char *name,
643  struct RT_ComponentFactoryProperty **property,
644  struct RT_ComponentFactoryListener **listener);
645 
646 /*ci
647  * \brief Find a component factory based on the name
648  *
649  * \details
650  *
651  * This function is used to find a component based on its name.
652  *
653  * \param[in] registry Registry to search for the component factory in
654  * \param[in] name The name of the component factory to find
655 
656  * \return pointer to \ref RT_ComponentFactory on success, NULL on failure
657  *
658  * \sa ref RT_Registry_lookup_cid
659  */
660 MUST_CHECK_RETURN RTDllExport struct RT_ComponentFactory*
661 RT_Registry_lookup(RT_Registry_T *registry,const char *name);
662 
663 /*ci
664  * \brief Find a component factory based on the name and class id
665  *
666  * \details
667  *
668  * This function is used to find a component based on its name <em> and
669  * </em> the class id. If the name exists but is of the wrong class id
670  * NULL is returned.
671  *
672  * \param[in] registry Registry to search for the component factory in
673  * \param[in] name The name of the component factory to find
674  * \param[in] cid Component ID to choose from
675 
676  * \return pointer to \ref RT_ComponentFactory on success, NULL on failure
677  *
678  * \sa ref RT_Registry_lookup
679  */
680 MUST_CHECK_RETURN RTDllExport struct RT_ComponentFactory*
681 RT_Registry_lookup_cid(RT_Registry_T *registry,const char *name,RTI_INT32 cid);
682 
683 /*ci
684  * \brief Get the current properties for the registry
685  *
686  * \details
687  *
688  * This function returns the current properties for the registry
689  *
690  * \param[in] registry Registry to return properties for
691  * \param[out] property Current properties on successful return
692 
693  * \return RTI_TRUE on success, RTI_FALSE on failure
694  *
695  * \sa ref RT_Registry_set_property
696  */
697 MUST_CHECK_RETURN RTDllExport RTI_BOOL
698 RT_Registry_get_property(RT_Registry_T *registry,
699  struct RT_RegistryProperty *property);
700 
701 /*ci
702  * \brief Set the properties for the registry
703  *
704  * \details
705  *
706  * This function sets the properties for the registry. Note that the properties
707  * can only be changed until the first registration takes place.
708  *
709  * \param[in] registry Registry to set properties on
710  * \param[in] property New registry properties
711 
712  * \return RTI_TRUE on success, RTI_FALSE on failure
713  *
714  * \sa ref RT_Registry_get_property
715  */
716 MUST_CHECK_RETURN RTDllExport RTI_BOOL
717 RT_Registry_set_property(RT_Registry_T *registry,
718  struct RT_RegistryProperty *property);
719 
720 /*ci
721  * \brief Get the interface of a component factory
722  *
723  * \details
724  *
725  * Get the interface of a component factory
726  *
727  * \param[in] factory Factory to return id for
728  *
729  * \return Factory id
730  */
731 RTDllExport RTI_INT32
732 RT_ComponentFactory_get_id(struct RT_ComponentFactory *factory);
733 
734 /*ce \dref_RT_Registry_ComponentFactoryId_set_name
735  * \brief Assign a name to a RT_ComponentFactoryId_T variable
736  *
737  * \details
738  *
739  * Use this function to assign a name to a RT_ComponentFactoryId_T variable,
740  * such as the name of the discovery plugin to use.
741  *
742  * \param id \st_in Id to initialize
743  * \param name \st_in Name to initialize with
744  *
745  * \return RTI_TRUE on success, RTI_FALSE on failure
746  */
747 MUST_CHECK_RETURN RTDllExport RTI_BOOL
748 RT_ComponentFactoryId_set_name(RT_ComponentFactoryId_T *id,
749  const char *const name);
750 
751 /*ci
752  * \brief Return the component factory id as a name
753  *
754  * \details
755  *
756  * Return the component factory id as a name
757  *
758  * \param[in] id Id to return name from
759  *
760  * \return id as name
761  */
762 MUST_CHECK_RETURN RTDllExport const char*
763 RT_ComponentFactoryId_get_name(const RT_ComponentFactoryId_T *const id);
764 
765 /*ci
766  * \brief Compare a component factory id to a name
767  *
768  * \details
769  *
770  * Compare a component factory id to a name
771  *
772  * \param[in] id Id to compare
773  * \param[in] name Name to compare against
774  *
775  * \return RTI_TRUE if the id is equal to the name
776  */
777 MUST_CHECK_RETURN RTDllExport RTI_BOOL
778 RT_ComponentFactoryId_equals(RT_ComponentFactoryId_T *id,
779  const char *const name);
780 
781 /*ci
782  * \brief Compare a two component factory ids
783  *
784  * \details
785  *
786  * Compare a two component factory ids
787  *
788  * \param[in] id1 Left side of comparison
789  * \param[in] id2 Right side of comparison
790  *
791  * \return positive integer if id1 is greater than id2,
792  * negative integer if id1 is less than id2,
793  * zero if id1 is equal to id2
794  */
795 MUST_CHECK_RETURN RTDllExport RTI_INT32
796 RT_ComponentFactoryId_compare(const RT_ComponentFactoryId_T *id1,
797  const RT_ComponentFactoryId_T *id2);
798 
799 #ifdef __cplusplus
800 } /* extern "C" */
801 #endif
802 
803 #endif
804 
805 /*ci @} */

RTI Connext DDS Micro Version 2.4.6 Copyright © Sun Jan 24 2016 Real-Time Innovations, Inc