Documentation Guide

This section describes the conventions used in the API documentation.

Unsupported Features

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

API Naming Conventions

Structure & Class Names

RTI Connext Micro 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. 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 Micro 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.

Types

• <<interface>>
  • Pure interface type with no state.

• <<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.

• <<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. The input parameter is a value parameter and is expected to be a valid value. If the parameter is a pointer, e.g. a pointer to an interface types, it is also an <<in>>, even if the content being pointed to has changed on return. <<in>> means that the pointer argument is not modified, not that the object pointed to is not modified.

• <<out>>
  • An output parameter. Only possible with references. The input value is not used, but the value may be changed on return, e.g a field in a structure may have been updated or a pointer may point to a new object. In general, a parameter is designated with <<out>> only if the caller is expected to access the output directly.

• <<inout>>
  • An input and output parameter. Only possible with references. The input value must be valid, including the value of a pointer, and the parameter may have a new value on output; for example, the address of a pointer to a buffer is updated on return. In general, a parameter is designated with <<inout>> only if the caller is expected to access the output directly.

Cert API

• <<cert>>
  • Supported in safety certified version of RTI Connext Micro. Note, specific fields of <<cert>> data structures may not be supported and will be described in documentation as unsupported.