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

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