3.3. 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 6.2. 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.3.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.2.6) 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.3.2. Available Service Resources¶
Table 3.15 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 6.1.1.1 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.
Resource | Resource Identifier |
---|---|
Recording Service | /recording_services/(rs) |
Storage | /recording_services/(rs)/storage/(st) |
3.3.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.3.3. Remote API Overview¶
Resource | Operation | Description |
---|---|---|
RecordingService | DELETE /recording_services/(rs) | Shuts down a running Recording Service instance. |
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.3.4. Recording Service¶
-
DELETE /recording_services/(rs)
Operation
shutdown
This operation will cause Recording Service to shutdown.
-
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 6.2.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.3.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).
Example
To tag a moment with the name “/example/test1/tag1”, representing a moment that is 123 milliseconds 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);