.. include:: ../../../recorder.4.0/srcDoc/vars.rst .. _section-replay_administration: Remote Administration ===================== This section provides documentation on |REPS| remote administration. A control client (such as *RTI Admin Console*) can use this interface to remotely control a |REPS|. .. Note:: |REPS| remote administration is based on the |RAP| described in :numref:`section-Rap`. Please refer to that manual for a detailed discussion on the workings of remote administration in |REPS|. Below you will find an API reference for all the supported operations. .. _section-replay_remote_admin_enable: Enabling Remote Administration ------------------------------ By default, remote administration is disabled in |REPS|. To enable remote administration you can use the ```` XML tag (see :numref:`section-replay_configuration`) or the ``-remoteAdministrationDomainId`` command-line parameter (see :numref:`section-replay_usage`). Both of these methods enable remote administration and set the domain ID for remote communication. Available Service Resources --------------------------- :numref:`TableReplayResources` lists the public resources specific to |REPS|. Each resource identifier is expressed as a hierarchical sequence of identifiers, including parent and target resources. (See :numref:`section-Arm-ResourceId` 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: .. code-block:: xml ... The resource identifier is: .. code-block:: html /replay_service/MyReplay In the table, the resource identifier is written as /replay_service/(rs), where (rs) is the service name. 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. .. list-table:: Resources and Their Identifiers in |REPS| :name: TableReplayResources :widths: 20 80 :header-rows: 1 * - Resource - Resource Identifier * - |REPS| - /replay_service/(rs) Example ^^^^^^^ This example shows you how to address a resource of each possible resource class in |REPS|. .. rubric:: |REPS| Entity with name "MyReplay": .. code-block:: xml ... Resource identifier: .. code-block:: html /replay_services/MyReplay .. _section-replay_remote_commands: Remote API Overview ------------------- .. list-table:: Remote Interface Overview :name: ReplayTableRemoteAdminAPI :widths: 10 50 30 :header-rows: 1 * - Resource - Operation - Description * - ReplayService - :ref:`DELETE /replay_services/(rs) ` - Shuts down a running |REPS| * - - :ref:`UPDATE /replay_services/(rs)/state ` - Sets a |REPS| state * - - :ref:`UPDATE /replay_services/(rs)/playback/rate ` - Change the rate of the replay * - - :ref:`UPDATE /replay_services/(rs)/playback/current_timestamp ` - Jump to a specific timestamp and continue the replay * - - :ref:`UPDATE /replay_services/(rs)/playback/current_tag ` - Jump to a specific timestamp tag and continue the replay * - - :ref:`GET /replay_services/(rs)/playback:state ` - Provide the current |REPS| state. It will allow us to detect when |REPS| hit a breakpoint. * - - :ref:`UPDATE /replay_services/(rs)/playback:add_breakpoint ` - Add a new breakpoint * - - :ref:`UPDATE /replay_services/(rs)/playback:remove_breakpoint ` - Remove an existing breakpoint * - - :ref:`UPDATE /replay_services/(rs)/playback:goto_breakpoint ` - Jump to a specific breakpoint and stop the replay * - - :ref:`UPDATE /replay_services/(rs)/playback:next_breakpoint ` - Jump to the next breakpoint and stop the replay * - - :ref:`UPDATE /replay_services/(rs)/playback:continue ` - Continue the replay leaving the current breakpoint * - - :ref:`UPDATE /replay_services/(rs)/playback:next_slice ` - Continue the replay for a slice of period Replay Service -------------- .. _replay_service_self_delete: .. function:: DELETE /replay_services/(rs) **Operation** ``shutdown`` Causes |REPS| to shutdown. .. _replay_service_self_state: .. function:: UPDATE /replay_services/(rs)/state **Operation** ``set_state`` See :ref:`section-Rap-CommonOps-SetState` (:numref:`section-Rap-CommonOps-SetState`). Valid requested states: * ``STARTED`` * ``STOPPED`` * ``PAUSED`` * ``RUNNING`` - Example To pause a replay service with the name "MyReplay": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/state * - ``octet_body`` - .. code-block:: C to_cdr_buffer(RTI::Service::EntityStateKind::PAUSED) .. _replay_service_rate: .. function:: UPDATE /replay_services/(rs)/playback/rate **Operation** ``set_rate`` This operation will cause *Replay Service* to change its rate. **Request body** - The new rate of the replay. .. _replay_service_timestamp: .. function:: UPDATE /replay_services/(rs)/playback/current_timestamp **Operation** ``current_timestamp`` This operation will cause *Replay Service* to change its current timestamp, modifying the replay location backward or forward in time. It will affect the whole service, meaning that all StreamReaders will be affected by it. - Example To change the current timestamp in a replay service named "MyReplay": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/playback/current_timestamp * - ``octet_body`` - .. code-block:: C RTI::RecordingService::TimestampHolder timestamp_holder; timestamp_holder.timestamp_nanos(1600635588280996383); std::vector timestamp_holder_buffer; dds::topic::topic_type_support ::to_cdr_buffer( timestamp_holder_buffer, timestamp_holder); .. _replay_service_tag: .. function:: UPDATE /replay_services/(rs)/playback/current_tag **Operation** ``current_tag`` This operation will cause *Replay Service* to change its current timestamp, modifying the replay location backward or forward in time. The replay will jump to the timestamp of the selected timestamp tag. It will affect the whole service, meaning that all StreamReaders will be affected by it. **Request body** - Tag name of a specific recorded timestamp tag. .. _replay_service_br_state: .. function:: GET /replay_services/(rs)/playback:state **Operation** ``get_state`` This operation will provide the current debug state of the |REPS| related to the debug mode. It will allow you to detect when |REPS| stop in a breakpoint Valid provided states: * ``BREAKPOINT`` * ``WORKING`` **Request body** - Empty. **Reply body** - ``octet_body``: CDR representation of the DebugStatus. .. _replay_service_add_br: .. function:: UPDATE /replay_services/(rs)/playback:add_breakpoint **Operation** ``add_breakpoint`` This operation will create a new breakpoint. |REPS| will only accept as proper breakpoint those which timestamp is not out of the recorded timestamp period. Also, we can use a recorded timestamp tag to create a breakpoint with it. - Examples To create a new breakpoint in a replay service named "MyReplay": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/playback:add_breakpoint * - ``octet_body`` - .. code-block:: C RTI::RecordingService::BreakpointParams breakpoint_arguments; ::dds::core::optional optional_label_value("breakpoint_1"); breakpoint_arguments.label(optional_label_value); breakpoint_arguments.value().timestamp_nanos(1600635588280996383); dds::topic::topic_type_support ::to_cdr_buffer( reinterpret_cast &> (request.octet_body()), breakpoint_arguments); To create a new breakpoint using a timestamp tag: .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/playback:add_breakpoint * - ``octet_body`` - .. code-block:: C RTI::RecordingService::BreakpointParams breakpoint_arguments; ::dds::core::optional optional_label_value("breakpoint_tag"); breakpoint_arguments.label(optional_label_value); breakpoint_arguments.value().tag_name("example/tag1"); dds::topic::topic_type_support ::to_cdr_buffer( reinterpret_cast &> (request.octet_body()), breakpoint_arguments); .. _replay_service_rm_br: .. function:: UPDATE /replay_services/(rs)/playback:remove_breakpoint **Operation** ``remove_breakpoint`` This operation will remove an existing breakpoint for the replay. A breakpoint can be removed by label or by timestamp. In order to clean the complete list of breakpoints (except the default one) you can use the special character "*" as label value. If |REPS| is hitting the breakpoint to be removed, It won't resume the replay. - Examples To remove the breakpoint with label "MyBreakpoint" in a replay service named "MyReplay": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/playback:remove_breakpoint * - ``octet_body`` - .. code-block:: C RTI::RecordingService::BreakpointParams breakpoint_arguments; ::dds::core::optional optional_label_value("MyBreakpoint"); breakpoint_arguments.label(optional_label_value); breakpoint_arguments.value().timestamp_nanos(0); dds::topic::topic_type_support ::to_cdr_buffer( reinterpret_cast &> (request.octet_body()), breakpoint_arguments); .. _replay_service_go_br: .. function:: UPDATE /replay_services/(rs)/playback:goto_breakpoint **Operation** ``goto_breakpoint`` This operation will cause |REPS| to jump to a specific breakpoint. You can specifie the jumping breakpoint by label or by timestamp. It will affect the whole service, meaning that all StreamReaders will be affected by it. -Example: To jump to breakpoint with timestamp "1600635588280996383" in a replay service named "MyReplay": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/playback:goto_breakpoint * - ``octet_body`` - .. code-block:: C RTI::RecordingService::BreakpointParams breakpoint_arguments; breakpoint_arguments.value().timestamp_nanos(1600635588280996383); dds::topic::topic_type_support ::to_cdr_buffer( reinterpret_cast &> (request.octet_body()), breakpoint_arguments); .. _replay_service_next_br: .. function:: UPDATE /replay_services/(rs)/playback:next_breakpoint **Operation** ``next_breakpoint`` This operation will cause |REPS| to jump to the next breakpoint on the list. if |REPS| was on the last breakpoint of the list It will throw an exception. It will affect the whole service, meaning that all StreamReaders will be affected by it. **Request body** - Empty. .. _replay_service_continue: .. function:: UPDATE /replay_services/(rs)/playback:continue **Operation** ``continue`` This operation will cause |REPS| to continue the replay after it hit a breakpoint. If you do not add any CDR representation to the request, it will continue until it hits a new breakpoint or the replay end. Otherwise, this operation will continue the replay for the period of time specified by you. |REPS| has to be on BREAKPOINT state in order to make this action. It will affect the whole service, meaning that all StreamReaders will be affected by it. -Examples: To continue the replay for 1 second in a replay service named "MyReplay": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/playback:continue * - ``octet_body`` - .. code-block:: C RTI::RecordingService::ContinueParams continue_arguments; continue_arguments.value().offset(1000000000); dds::topic::topic_type_support ::to_cdr_buffer( reinterpret_cast &> (request.octet_body()), continue_arguments); To continue the replay for 2 slices periods in a replay service named "MyReplay": .. list-table:: :widths: 30 70 :header-rows: 1 * - Request Field - Value * - ``command_action`` - UPDATE * - ``resource_identifier`` - /replay_services/MyReplay/playback:continue * - ``octet_body`` - .. code-block:: C RTI::RecordingService::ContinueParams continue_arguments; continue_arguments.value().slices(2); dds::topic::topic_type_support ::to_cdr_buffer( reinterpret_cast &> (request.octet_body()), continue_arguments); .. _replay_service_next_slice: .. function:: UPDATE /replay_services/(rs)/playback:next_slice **Operation** ``next_slice`` This operation will cause |REPS| to resume the replay for the duration of a slice period. |REPS| has to be on BREAKPOINT state in order to make this action. It will affect the whole service, meaning that all StreamReaders will be affected by it. **Request body** - Empty.