RTI Connext DDS Micro  Version 2.4.9
 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 /*ci
310  * \brief Properties a RT_ComponentFactory can be created with
311  */
312 struct RT_ComponentFactoryProperty
313 {
314  /* The "base class" cannot be empty due to some compilers failing,
315  * and there are currently no common factory properties.
316  */
317  void *dummy;
318 };
319 
320 /*ci
321  * \brief Initializer for \ref RT_ComponentFactoryProperty
322  */
323 #define RT_ComponentFactoryProperty_INITIALIZER \
324 { \
325  NULL\
326 }
327 
328 /*ci
329  * \brief Listeners that can be installed on a RT_ComponentFactoryProperty
330  * when it is created
331  */
332 struct RT_ComponentFactoryListener
333 {
334  void *dummy;
335 };
336 
337 /*ci
338  * \brief Initializer for \ref RT_ComponentFactoryListener
339  */
340 #define RT_ComponentFactoryListener_INITIALIZER \
341 {\
342  NULL\
343 }
344 
345 /*ci
346  * \brief Function typedef for a factory initializer
347  *
348  * \param[in] property The property to initialize the factory with
349  * \param[in] listener The listener to initialise the factory with
350  *
351  * \return An implementation of this function must return the initialized
352  * factory on success, NULL otherwise
353  */
354 FUNCTION_MUST_TYPEDEF(
355 struct RT_ComponentFactory*
356 (*RT_ComponentFactory_initializeFactoryFunc)(
357  struct RT_ComponentFactoryProperty *property,
358  struct RT_ComponentFactoryListener *listener)
359 )
360 
361 /*ci
362  * \brief Function typedef for a factory finalizer
363  *
364  * \param[in] factory The factory being finalized
365  * \param[inout] property The property the factory was initialized with if not NULL
366  * \param[inout] listener The listener the factory was initialized with if not NULL
367  *
368  */
369 typedef void
370 (*RT_ComponentFactory_finalizeFactoryFunc)(struct RT_ComponentFactory *factory,
371  struct RT_ComponentFactoryProperty **property,
372  struct RT_ComponentFactoryListener **listener);
373 
374 /*ci
375  * \brief Function typedef for a factory create component function
376  *
377  * \param[in] factory The factory creating an instance of a component
378  * \param[in] property The property for the component
379  * \param[in] listener The listener for the component
380  *
381  * \return An implementation of this function must return the initialized
382  * component on success, NULL otherwise
383  */
384 FUNCTION_MUST_TYPEDEF(
385 RT_Component_T*
386 (*RT_ComponentFactory_createFunc)(struct RT_ComponentFactory *factory,
387  struct RT_ComponentProperty *property,
388  struct RT_ComponentListener *listener)
389 )
390 
391 /*ci
392  * \brief Function typedef for a factory delete component function
393  *
394  * \param[in] factory The factory deleting an instance of a component
395  * \param[in] component The component being deleted
396  *
397  * \return An implementation of this function must return the initialized
398  * component on success, NULL otherwise
399  */
400 typedef void
401 (*RT_ComponentFactory_deleteFunc)(struct RT_ComponentFactory *factory,
402  RT_Component_T* component);
403 
404 /*ci
405  * \brief Function typedef for a factory get interface function
406  *
407  * \param[in] factory The factory to get the interface for
408  *
409  * \return An implementation of this function must return the interface
410  * structure for the component
411  */
412 FUNCTION_MUST_TYPEDEF(
413 struct RT_ComponentI*
414 (*RT_ComponentFactory_get_ifFunc)(struct RT_ComponentFactory *factory)
415 )
416 
417 /*ci
418  * \brief A default factory id if an interface does not specify it
419  */
420 #define RT_COMPONENT_FACTORY_ID_DEFAULT (0)
421 
422 /*ci
423  * \brief The RT_ComponentFactory interface
424  */
425 struct RT_ComponentFactoryI
426 {
427  /*ci
428  * \brief interface id
429  */
430  RTI_INT32 id;
431 
432  /*ci
433  * \brief function to call when the factory is first registered
434  */
435  RT_ComponentFactory_initializeFactoryFunc initialize;
436 
437  /*ci
438  * \brief function to call when the factory is unregistered
439  */
440  RT_ComponentFactory_finalizeFactoryFunc finalize;
441 
442  /*ci
443  * \brief function to call to create an new instance of a component
444  */
445  RT_ComponentFactory_createFunc create_component;
446 
447  /*ci
448  * \brief function to call to delete an instance of a component
449  */
450  RT_ComponentFactory_deleteFunc delete_component;
451 
452  /*ci
453  * \brief function to get the components interface implementation
454  */
455  RT_ComponentFactory_get_ifFunc get_if;
456 };
457 
458 /*ci
459  * \def RT_MAX_FACTORY_NAME
460  * \brief Maximum length of a factory name, it does _not_ include \0
461  */
462 #define RT_MAX_FACTORY_NAME 7
463 
464 /*
465  * Structure to represent a component name as either a 64 bit integer
466  * or name
467  */
468 #ifdef RTI_WIN32
469 #pragma warning(push)
470 #pragma warning(disable: 4522)
471 #endif
472 union DDSCPPDllExport RT_ComponentFactoryId
473 {
474  struct
475  {
476  char _name[RT_MAX_FACTORY_NAME+1];
477  } _name;
478 
479  struct
480  {
481  RTI_UINT32 _high;
482  RTI_UINT32 _low;
483  } _value;
484 
485 #ifdef RTI_CPP
486  public:
487  RT_ComponentFactoryId();
488  bool set_name(const char *const name);
489 #ifdef RTI_CERT
490  private:
491 #else
492  public:
493 #endif
494  RT_ComponentFactoryId& operator=(const char *const name);
495  RT_ComponentFactoryId& operator=(const RT_ComponentFactoryId& from);
496  const RT_ComponentFactoryId& operator=(const RT_ComponentFactoryId& from) const;
497  bool operator==(const RT_ComponentFactoryId& other) const;
498  bool operator==(const char *const name) const;
499  bool operator!=(const RT_ComponentFactoryId& other) const;
500  bool operator!=(const char *const name) const;
501 #endif
502 };
503 
504 #ifdef RTI_WIN32
505 #pragma warning(pop)
506 #endif
507 /*
508  * Abstract type for the factory id
509  */
510 typedef union RT_ComponentFactoryId RT_ComponentFactoryId_T;
511 
512 #define RT_ComponentFactoryId_INITIALIZER \
513 {\
514  {{0}} \
515 }
516 
517 /*ci
518  * \brief Clear a factory id
519  *
520  * \param[in] id Id to clear
521  */
522 RTDllExport void
523 RT_ComponentFactoryId_clear(union RT_ComponentFactoryId *id);
524 
525 /*ci
526  * \brief A ComponentFactory base-class. All component factories must derive
527  * from this class
528  */
529 struct RT_ComponentFactory
530 {
531  /*ci
532  * \brief The factory interface
533  */
534  struct RT_ComponentFactoryI *intf;
535 
536  /*ci
537  * \brief The factory instance
538  */
539  struct RT_ComponentFactory *_factory;
540 
541  /*ci
542  * \brief The factory id
543  */
544  union RT_ComponentFactoryId _id;
545 };
546 
547 /*ci
548  * \brief Initializer for the \ref RT_ComponentFactory
549  */
550 #define RT_ComponentFactory_INITIALIZER \
551 { \
552  NULL,\
553  NULL,\
554  {{0,0}}\
555 }
556 
557 /*ci
558  * \brief The abstract component factory type
559  */
560 typedef struct RT_ComponentFactory RT_ComponentFactory_T;
561 
562 /*ci
563  * \brief Properties a \ref RT_Registry can be created with
564  */
565 struct RT_RegistryProperty
566 {
567  /*ci
568  * \brief The maximum number of component factories which can be registered
569  */
570  RTI_SIZE_T max_factories;
571 
572  /*ci
573  * \brief A database the component factory can use, if needed
574  */
575  DB_Database_T db;
576 };
577 
578 /*ci
579  * \brief Initializer for \ref RT_RegistryProperty
580  */
581 #define RT_RegistryProperty_INITIALIZER \
582 { \
583  1,\
584  NULL\
585 }
586 
587 /*ci
588  * \brief Default values for \ref RT_RegistryProperty
589  */
590 extern RTDllVariable struct RT_RegistryProperty
591  RTCOMPONENTFACTORY_REGISTRY_PROPERTY_DEFAULT;
592 
593 /* forward declaraion for the abstract type definition */
594 struct RT_Registry;
595 
596 /*ci
597  * \brief Abstract RT_Registry type
598  */
599 typedef struct RT_Registry RT_Registry_T;
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.9 Copyright © Thu Dec 15 2016 Real-Time Innovations, Inc