Conventions

This section describes the conventions used in the API documentation.

Unsupported Features

[Not supported (optional)] This note means that the optional feature from the DDS specification is not supported in the current release.

API Naming Conventions

Structure & Class Names

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 DDS_Entity subtypes, the DDS_Condition subtypes, and DDS_WaitSet. 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 type structures are made more explicit through the use of C's structure tag syntax. For example, a DDS_Duration_t object must be declared as being of type "struct DDS_Duration_t," not simply "DDS_Duration_t." Interface types, by contrast, are always of typedef'ed types; their underlying representations are opaque.

API Documentation Terms

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.

Stereotypes

Commonly used stereotypes in the API documentation include the following.

Extensions

• <<extension>>
  • An RTI Connext 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.

Experimental

• <<experimental>>
  • RTI Connext experimental features are used to evaluate new features and get user feedback.
  • These features are not guaranteed to be fully supported and might be implemented only of some of the programming languages supported bt RTI Connext
  • The functional APIs corresponding to experimental features can be distinguished from other APIs by the suffix '_exp'.
  • Experimental features may or may not appear in future product releases.
  • The name of the experimental features APIs will change if they become officially supported. At the very least the suffix '_exp' will be removed.
  • Experimental features should not be used in production.

Types

• <<interface>>
  • Pure interface type with no state.
  • Languages such as Java natively support the concept of an interface type, which is a collection of function 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.

• <<generic>>
  • 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>>
  • Singleton class. There is a single instance of the class.
  • Generally acccessed via a get_instance() static function.

Method Parameters

• <<in>>
  • An input parameter.

• <<out>>
  • An output parameter.

• <<inout>>
  • An input and output parameter.