.. include:: ../../../router.1.0/srcDoc/vars.rst

.. _section-replay_administration:

Remote Administration
=====================

This section provides documentation on *Replay Service* remote
administration. A control client (such as *RTI Admin Console*) can use this
interface to remotely control a *Replay Service*.

.. Note::

    *Replay Service* 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 *Replay Service*.

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 *Replay Service*.

To enable remote administration you can use the ``<administration>`` 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 *Replay Service*. 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

   <replay_service name="MyReplay">...</replay_service>

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 |RS|
    :name: TableReplayResources
    :widths: 20 80
    :header-rows: 1

    * - Resource
      - Resource Identifier
    * - *Replay Service*
      - /replay_service/(rs)

Example
^^^^^^^
This example shows you how to address a resource of each possible resource
class in *Replay Service*.

.. rubric:: *Replay Service*

Entity with name "MyReplay":

  .. code-block:: xml

    <replay_service name="MyReplay">...</replay_service>

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
    * - :litrep:`ReplayService`
      - :ref:`DELETE /replay_services/(rs) <replay_service_self_delete>`
      - Shuts down a running *Replay Service*
    * -
      - :ref:`UPDATE /replay_services/(rs)/state <replay_service_self_state>`
      - Sets a *Replay Service* state


Replay Service
--------------

.. _replay_service_self_delete:
.. function:: DELETE /replay_services/(rs)

    **Operation** ``shutdown``

    Causes *Replay Service* 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)