3.4. Remote Administration

A control client (such as RTI Admin Console) can use this interface to remotely control Recording Service.

Note

Recording Service remote administration is based on the RTI Remote Administration Platform described in Section 10.3. Please refer to that manual for a detailed discussion on the workings of remote administration in Recording Service.

Below you will find an API reference for all the supported operations.

3.4.1. Enabling Remote Administration

By default, remote administration is disabled in Recording Service.

To enable remote administration you can use the <administration> XML tag (see Section 3.3.4) or the -remoteAdministrationDomainId command-line parameter (see Section 3.1.3). Both of these methods enable remote administration and set the domain ID for remote communication.

3.4.2. Available Service Resources

Table 3.18 lists the public resources specific to Recording Service. Each resource identifier is expressed as a hierarchical sequence of identifiers, including parent and target resources. (See Section 10.2.2 for details.)

In the table below, the elements (rs), and (st) refer to the name of an entity of the corresponding class as specified in the configuration in the name attribute. For example, in the following configuration:

<recording_service name="MyRecorder">...</recording_service>

The resource identifier is:

/recording_services/MyRecorder

In the table below, the resource identifier is written as /recording_services/(rs), where (rs) is the service name. (st) is the storage name, and so on. This nomenclature is used in the table to give you an idea of the structure of the resource identifiers. For actual (example) resource identifier names, see the example section that follows.

Table 3.18 Resources and Their Identifiers in *Recording Service*
Resource	Resource Identifier
Recording Service	/recording_services/(rs)
Storage	/recording_services/(rs)/storage/(st)

3.4.2.1. Example

This example shows you how to address a resource of each possible resource class in Recording Service.

Recording Service

Entity with name “MyRecorder”:

<recording_service name="MyRecorder">...</recording_service>

Resource identifier:

/recording_services/MyRecorder

Storage

Entity with name “sqlite” (implicit name of the builtin storage):

<recording_service name="MyRecorder">
    <sqlite>...</sqlite>
</recording_service>

Resource identifier:

/recording_services/MyRecorder/storage/sqlite

3.4.3. Remote API Overview

Table 3.19 Remote Interface Overview
Resource	Operation	Description
RecordingService	DELETE /recording_services/(rs)	Shuts down a running Recording Service instance.
RecordingService	UPDATE /recording_services/(rs):flush	Flushes all buffered data in memory into disk.
	UPDATE /recording_services/(rs)/state	Sets a Recording Service state.
builtin SQLite Storage	UPDATE /recording_services/(rs)/storage/sqlite:rollover	Continues the current recording in a new file (also known as a “shard” or file segment). Note: Only valid for builtin SQLite plugin.
	UPDATE /recording_services/(rs)/storage/sqlite:tag_timestamp	Associates a symbolic name with the current time (with an optional offset) in the recording. Note: Only valid for builtin SQLite plugin.

3.4.4. Recording Service

DELETE /recording_services/(rs)

Operation shutdown

This operation will cause Recording Service to shutdown.

UPDATE /recording_services/(rs):flush

Operation flush

This operation will cause Recording Service to flush contents of all topics and topic groups into permanent storage. This operation can be used with any of Recording Service’s modes of operation, but is crucial when running in buffering mode, because it’s the only way to flush buffered samples into permanent storage.

This operation will store a total of N samples into storage, N being the depth of the History QoS policy. If there are fewer samples in the buffer, this operation will store all of them.

This operation will affect the whole service, meaning that all Topics and Topic Groups will be affected by it.

Request Field

Value

action

UPDATE

resource_identifier

/recording_services/MyRecorder:flush

Request body

Empty.

UPDATE /recording_services/(rs)/state

Operation set_state

Sets the state of a Recording Service object. The action is parametrized on octet_body, which could have the following values:

See Set Resource State (Section 10.3.3.4).

Valid requested states:

STARTED

STOPPED

PAUSED

RUNNING

Example
To pause an instance of Recording Service with the name “MyRecorder”:
Request Field

Value
action

UPDATE

resource_identifier

/recording_services/MyRecorder/state

octet_body

to_cdr_buffer(RTI::Service::EntityStateKind::PAUSED)

3.4.5. Storage

UPDATE /recording_services/(rs)/storage/sqlite:rollover

Operation rollover

If the storage plugin being used is the builtin SQLite plugin, this operation will cause the recording to switch to a new file segment (also known as a “shard”) in the fileset.

Request Field

Value

action

UPDATE

resource_identifier

/recording_services/MyRecorder/storage/sqlite:rollover

Request body

Empty.

UPDATE /recording_services/(rs)/storage/sqlite:tag_timestamp

Operation tag_timestamp

If the storage plugin being used is the builtin SQLite plugin, this operation will introduce a new entry in the symbolic timestamps table, using the tag name, textual description, and offset time specified in the arguments to the operation (CDR-serialized in the octet-body with the RTI::RecordingService::DataTagParams data type). The timestamp_offset field represents an offset in seconds from the moment the command is received. If the offset is negative, the tag will be associated with a moment in the past. For example, an offset of 20.3 represents a time ~20.3 seconds in the future, while an offset of -10.1 represents a time ~10.1 seconds in the past.

Example

To tag a moment with the name “/example/test1/tag1”, representing a moment that is 123 seconds in the past:

Request Field

Value

action

UPDATE

resource_identifier

/recording_services/MyRecorder/storage/sqlite:tag_timestamp

octet_body

std::string tag_name_1("/example/test1/tag1");
std::string tag_description_1("start of test");
RTI::RecordingService::DataTagParams data_tag_arguments;
data_tag_arguments.tag_name(tag_name_1);
data_tag_arguments.tag_description(tag_description_1);
data_tag_arguments.timestamp_offset(-123);
std::vector<char> data_tag_arguments_buffer;

dds::topic::topic_type_support<RTI::RecordingService::DataTagParams>
    ::to_cdr_buffer(
        data_tag_arguments_buffer,
        data_tag_arguments);