This section describes the conventions used in the API documentation.
[Not supported (optional)
] This note means that the optional feature from the DDS specification is not supported in the current release.
RTI Data Distribution Service 4 makes a distinction between value types
and interface types
. Value types are types such as primitives, enumerations, strings, and structures whose identity and equality are determined solely by explicit state. Interface types are those abstract opaque data types that conceptually have an identity apart from their explicit state. Examples include all of the DDSEntity
subtypes, the DDSCondition
subtypes, and DDSWaitSet
. Instances of value types are frequently transitory and are declared on the stack. Instances of interface types typically have longer lifecycles, are accessible by pointer only, and may be managed by a factory object.
Value and interface types are distinguished by their names: value types have names beginning with "DDS_" (i.e. with an underscore); interface types have names beginning with "DDS" (i.e. with no underscore). Another way to think of it: C-style types -- structures, enumerations, etc. -- have names beginning with "DDS_"; C++ classes have names beginning with "DDS."
In the API documentation, the term module refers to a logical grouping of documentation and elements in the API.
At this time, typedefs that occur in the API, such as DDS_ReturnCode_t do not show up in the compound list or indices. This is a known limitation in the generated HTML.
Commonly used stereotypes in the API documentation include the following.
- An RTI Data Distribution Service product extension to the DDS standard specification.
- The extension APIs complement the standard APIs specified by the OMG DDS specification. They are provided to improve product usability and enable access to product-specific features such as pluggable transports.
- Pure interface type with no state.
- Languages such as Java natively support the concept of an interface type, which is a collection of method signatures devoid of any dynamic state.
- In C++, this is achieved via a class with all pure virtual methods and devoid of any instance variables (ie no dynamic state).
- Interfaces are generally organized into a type hierarchy. Static typecasting along the interface type hierarchy is "safe" for valid objects.
- A generic type is a skeleton class written in terms of generic parameters. Type-specific instantiations of such types are conventionally referred to in this documentation in terms of the hypothetical type "Foo"; for example: FooSeq, FooDataType, FooDataWriter, and FooDataReader.
- For portability and efficiency, we implement generics using C preprocessor macros, rather than using C++ templates.
- A generic type interface is declared via a #define macro.
- Concrete types are generated from the generic type statically at compile time. The implementation of the concrete types is provided via the generic macros which can then be compiled as normal C or C++ code.
- Singleton class. There is a single instance of the class.
- Generally acccessed via a
get_instance() static method.