.. _introspectionif:

Introduction
############

Reference Documents
===================

[RD1]
    | Central Control System Development Standards;
    | `ESO-366378 v1 <https://pdm.eso.org/kronodoc/HQ/ESO-366378>`_


Introspection Interface
#######################

Introspection interface ``instrospectionif`` is the interface that provides
information on the running application and its offered commands, topics and
its OLDB path. Its purpose is to facilitate clients to get information
in a formal/authorative manner, since the application is the one that
serves commands and publishes data.

This documentation provides an overview of the interface.  When complex
structures are to be transmitted, the selected method is to use JSON and a
schema will be provided.


.. module:: introspectionif

Interfaces
==========

.. class:: Introspection

    Introspection interface.

    .. method:: GetInterfaces(service) -> String

        Requests the application to return the interface declaration for the
        service in particular.

        :param service: service name of interest. If empty, the
                        method returns every available service in the
                        application server instance.
        :type service: String
        :return: A JSON formatted string that carries pairs of service
                 and its respective MAL ICD XML.
        :rtype: String
        :raises stdif::ExceptionErr: On error.

    .. method:: GetTopics(topic) -> String

        Requests the application to return the topic (structure) declaration for
        the topic in particular.

        :param topic: topic name of interest. If empty, the method returns every
                      available topic in the application server instance.
        :type topic: String
        :return: A JSON formatted string that carries a dictionary of topic URIs
                 and their respective MAL ICD XMLs.
        :rtype: String
        :raises stdif::ExceptionErr: On error.

    .. method:: GetOldbPrefix() -> String

        Requests the application to return the common prefix to all its OLDB
        datapoints.

        :return: A URI that is the prefix to all application OLDB datapoints.
        :rtype: String
        :raises stdif::ExceptionErr: On error.


JSON Schemas
============

GetInterfaces
-------------

The :meth:`GetInterfaces` method returns a JSON formatted string. This
JSON string follows the schema expressed here:

.. literalinclude:: ../../introspectionif/resource/std/getinterfaces.schema.json
    :language: json

An example of such response is given below:

.. literalinclude:: getinterfaces-example.json
    :language: json

