| Icon | Meaning |
| <img src="images/2a05f87a4292bfecb242bff603249f384f86fc8d046326ed5c2af664e82a5224.jpg"/> | Item of special significance or where caution needs to be taken. |
| <img src="images/2f8a03184f07ba6929c0610d462b5baa13e1b03d87dee3b76889cd5a2761eb27.jpg"/> | Item contains helpful hint or special information. |
| <img src="images/4fe2b4a96e5a4b452bc5568d6f3865119632a2c2edabd550e9a06ba0786d19b9.jpg"/> | Information applies to Windows (e.g. XP, 2003, Windows 7) only. |
| <img src="images/d49e0d6b73988cff221027da5cd9beb3a26afc33ca172d9bb314798958ce59e7.jpg"/> | Information applies to Unix-based systems (e.g. Solaris) only. |
| <img src="images/8900901b866cfe9cfcd7831571589bc731bf0d8c1bc097997ff86d32e54d94ff.jpg"/> | Information applies to Linux-based systems (e.g. Ubuntu) only. |
| <img src="images/8722f419d393c3bbb0a636f2f9be25626b1ff366bae29885cce82fe83d6c1e42.jpg"/> | C language specific. |
| <img src="images/5187ea8199f4587188507201b111cab32a79fe7de38664ea33120658de893b1d.jpg"/> | C++ language specific. |
| <img src="images/0388ee0b2ce3ef57acafdcc66c22e17bfdd93ab5193748ca350639f6a130cba1.jpg"/> | C# language specific. |
| <img src="images/16f7797247fe2ad4c3e888f65321777b2aaf2ae21b5f4149dd3385a6356449ea.jpg"/> | Java language specific. |
# 2
# Introduction
# 2.1 Features
Vortex OpenSplice Streams API supports a common data-distribution pattern where continuous flows or streams of data have to be transported with minimal overhead and therefore maximal achievable throughput.
Vortex OpenSplice Streams API implements this streams pattern by transparent packing and queuing of data samples using auto-generated containers, thus minimizing the overhead normally associated with the management and distribution of individual DDS samples.
# 2.2 Getting Started
The Vortex OpenSplice Streams API is divided in two main components:
• type-specific code that can be generated using the Vortex OpenSplice IDL Pre-Processor
• a Streams library.
Applications that wish to use the Streams API are required to do two things:
1. Link against one of the Vortex OpenSplice Streams libraries available within the Vortex OpenSplice distribution. There are separate libraries for either CORBA-Cohabitation mode or Standalone C++ mode.
2. Annotate the data-model IDL file with #pragma stream directives for each data type for which a Stream needs to be created.
The Vortex OpenSplice Streams API is built on the DCPS API. Since the C++ bindings of Vortex OpenSplice are available in two flavours, so is the Streams API. In the following paragraphs the steps will be discussed to build a simple application that uses the following data-model:
```c
Space.idl:
module Space {
struct Foo {
long long_1;
long long_2;
};
#pragma stream Foo
struct Type2 {
long long_1;
long long_2;
long long_3;
};
#pragma stream Type2
#pragma keylist Type2 long_1
};
```
Using this model, both Foo and Type2 can be used with the Streams API. In addition Type2 can also be used as a regular DDS topic, with long\_1 as key.
The following relevant Streams API classes are generated based on this model for Foo:
```autohotkey
Space::FooStreamDataWriter
Space::FooStreamDataReader
Space::FooStreamBuf
```
It is recommended to use smart references to the StreamDataWriter and StreamDataReader classes in applications. The regular Vortex OpenSplice C++ smart-pointer <class>\_var types are available for this purpose. See the section on Memory Management in the Vortex OpenSplice C++ Reference Guide for more information.
# 2.2.1 CORBA Cohabitation Mode
In CORBA Co-habitation mode, idlpp generates code that can be processed with any of the supported ORB compilers (OpenFusion TAO, Mico, etc.).
First idlpp is executed on the Space.idl file:
```powershell
$ idlpp -I$OSPL_HOME/etc/idl -l cpp -C Space.idl
```
The standard Vortex OpenSplice IDL directory is referenced as include-path, since it contains definitions of some basic data-types and interfaces that are required if DDS Topics are created for any of the types in the IDL file. The other parameters are used to put idlpp in C++ CORBA-Cohabitation mode.
As usual when DDS topics are created, the above command generates, among other files, a file called SpaceDcps.idl. The file SpaceStreams.idl is also generated.
To proceed, idlpp should be executed on the ExampleStreams.idl file:
```powershell
$ idlpp -I$OSPL_HOME/etc/idl -l cpp -C SpaceStreams.idl
```
This creates the descriptions of the DCPS entities that are required to manage the DDS topics that will be used for the Streams types, just like with the original IDL file, in a file called SpaceStreamsDcps.idl.
Now all four IDL files should be processed with the appropriate (ORB-specific) CORBA IDL processor. After this step all code and header files are generated to start using the Streams API in application code.
# 2.2.2 Standalone Mode
In Standalone C++ mode, the generated interfaces are not required to be processed by an IDL compiler. Instead, idlpp will use the cppgen code-generator that is part of the Vortex OpenSplice distribution. idlpp will automatically call cppgen to process certain files; the user is only required to execute idlpp, first on the original IDL file:
```powershell
$ idlpp -I$OSPL_HOME/etc/idl -l cpp -S Space.idl
```
This creates SpaceStreams.idl, which in turn also needs to be processed by idlpp:
```powershell
$ idlpp -I$OSPL_HOME/etc/idl -l cpp -S -i SpaceStreams.idl
```
The -i parameter is required because normally no code is generated for interfaces (for DDS topics, only datatypes are generated). In the case of streams, interfaces should not be ignored.
# 3
# API Reference
# 3.1 Introduction
As described in :ref:‘Getting Started <Getting Started>‘, the Vortex OpenSplice IDL preprocessor generates typed Streams API classes for each type that is annotated with a streams pragma.
As in the Vortex OpenSplice C++ Reference Guide, the fictional type Foo, defined in module Space, is used as an example. When the Foo type is annotated with a pragma streams, FooStreamDataWriter and FooStreamDataReader classes will be generated.
This section describes the usage of all operations on these classes.
# 3.2 QoS Policies