.. _if:

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

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

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


Data Recorder Interface - recif
###############################

The Data RecorderInterface, ``recif``, defines the CII request/reponse interface for data recording applications, i.e., applications sampling data and typically, writing these in output data files.

This document serves merely to provide an overview of the Data Recorder Interface.
The CII MAL generates the structures (classes) for the interface and are not described in this document.

.. module:: recif

Interfaces
==========

.. class:: RecCmds

    Data Recorder Request/Response Interface.

    .. method:: RecAbort() -> String.

        Abort an on-going Data Recording Session.

        :return: A string with information about the execution of the request.
        :rtype: String
        :raises recif::ExceptionErr: On error.

    .. method:: RecContinue() -> recif::RecStatus.

        Continue a previously paused Data Recording Session.

        :return: A recif::RecStatus with current information about the Data Recording Session.
        :rtype: recif::RecStatus
        :raises recif::ExceptionErr: On error.

    .. method:: RecPause() -> recif::RecStatus.

        Pause an on-going Data Recording Session.

        :return: A recif::RecStatus with current information about the Data Recording Session.
        :rtype: recif::RecStatus
        :raises recif::ExceptionErr: On error.

    .. method:: RecStart(properties) -> recif::RecStatus.

        Start a new Data Recording Session according to the properties provided.

        :param recif::RecProperties properties: Instance of recif::RecProperties class, specifying the conditions for starting the Recording Session.
        :return: A recif::RecStatus with the estimated information about the Data Recording Session execution.
        :rtype: recif::RecStatus
        :raises recif::ExceptionErr: On error.

    .. method:: RecStatus(id) -> recif::RecStatus.

        Query the status of an active or completed Data Recording Session, referenced with the specified Recording ID.
        If no Recording ID is given the current active Recording Session is considered or the last one executed.

        :param str id: Recording ID for the Recording Session in quetions or empty string for current/previous.
        :return: A recif::RecStatus with the estimated information about the Data Recording Session execution.
        :rtype: recif::RecStatus
        :raises recif::ExceptionErr: On error.

    .. method:: RecStop() -> recif::RecStatus.

        Stop an on-going Data Recording Session.
        Possible output data product files are kept.

        :return: A recif::RecStatus with the status about the Data Recording Session up to the point when it was stopped.
        :rtype: recif::RecStatus
        :raises recif::ExceptionErr: On error.

    .. method:: RecWait(waitCond) -> recif::RecStatus.

        Wait (blocking) on an on-going Recording Session according to the conditions specified.
        If the request times out a positive response is returned with a status indicating that the request timed out.
        If an on-going Recording Session is aborted or stopped prematurely, pending responses to RecWait requests, are submitted.

        :param recif::RecWaitSepc waitCond: Conditions for waiting for the Recording Session to complete, typically the timeout to apply.
        :return: A recif::RecStatus with the estimated information about the Data Recording Session execution.
        :rtype: recif::RecStatus
        :raises recif::ExceptionErr: On error.

Data Structures
===============

.. class:: RecStatusNames

    Possible status values for a Recording Session.
    The values defined are:

    * Active: The Recording Session is on-going.
    * Completed: The Recording Session has completed, successfully.
    * Stopped: The Recording Session was stopped due to a RecStop request.
    * Aborted: The Recording Session was aborted due to a RecAbort request.
    * Failed: The Recording Session failed due to some unrecoverable error.
    * Undefined: The status is unknown/not yet updated.

.. class:: RecStatusNames

    Possible status values for a RecWait Request.
    The values defined are:

    * Success: The Recording Session completed while the RecWait request was pending.
    * Timeout: The RecWait request timed out while waiting for the Recording Session to complete.


.. class:: ExceptionErr

    DCS Exception class thrown in case an error is encountered while handling a request.

    .. attribute:: code
        :type: int

        Exception (error) code allocated to the specific exception; 0 if no code is allocated.

    .. attribute:: desc
        :type: str

        Description of the exception (diagnostics).


.. class:: RecWaitSpec

    Defines the conditions for the RecWait Request.
        
    .. attribute:: info
        :type: str
        
        Facilitates submission of context specific information in connection with the RecWait Request.
        
    .. attribute:: timeout
        :type: Double
        
        Timeout in seconds to apply while waiting for an on-going Recording Session to end.


.. class:: RecProperties

    Defines the properties for executing the Recording Session.
        
    .. attribute:: absTime
        :type: double
        
        Absolute point in time given as seconds since epoch for when to start the Recording Session.
        
    .. attribute:: id
        :type: str
        
        Recording ID to allocate to the Recording Session. If specified as an empty string a unique ID will be allocated by the Data Recorder Application.
    
    .. attribute:: info
        :type: str
        
        Free format information (context specific) to submit with the request.
    
    .. attribute:: publishers
        :type: str-array[32]
        
        Reference to specific Recording Data Publishers to activate for recording data.
        If none are specified, all Recording Data Publishers are activated.


.. class:: RecStatus

    Contains the status about an on-going or completed Recording Session.
            
    .. attribute:: dpFiles
        :type: str-array[32]
            
        List of Data Product output files generated in connection with the Recording Session, from all activated Recording Data Publishers.
            
    .. attribute:: endTime
        :type: double
            
        Estimated or actual time for ending the Recording Session.
        
    .. attribute:: filesGenerated
        :type: int
            
        Number of Data Product Files generated in connection with the Recording Session from all activated Recording Data Publishers.
        
    .. attribute:: framesProcessed
        :type: int
            
        Number of image frames processed (so far) during the Recording Session from all activated Recording Data Publishers.
        
    .. attribute:: framesRemaining
        :type: int
            
        Number of image frames expected (still) to be processed during the Recording Session from all activated Recording Data Publishers.
        
    .. attribute:: id
        :type: str
            
        Recording ID allocated to the given Recording Session.
        
    .. attribute:: info
        :type: str
            
        Context speicific status information provided for the Recording Session.
        
    .. attribute:: remainingTime
        :type: double
            
        Estimated remaining execution time for ending the Recording Session.
        
    .. attribute:: sizeRecorded
        :type: int
            
        Size in bytes of all Data Product files produced during the Recording Session by all activated Recording Data Publishers.
        
    .. attribute:: startTime
        :type: double
            
        Time in seconds since epoch for when the Recording Session was started.
        
    .. attribute:: status
        :type: recif::RecStatusNames
            
        Current status an on-going or ended Recording Session.
    
    .. attribute:: timeElapsed
        :type: double
            
        Time in seconds since epoch elapsed since the Recording Session was started.
        
.. class:: RecWaitStatus

    Status returned from a RecWait Request.
      
    .. attribute:: recStatus
        :type: recif::RecStatus
                
        recif::RecStatus object containing the detailed status of the Recording Session.
    
    .. attribute:: status
        :type: recif::RecWaitStatusNames
                
        Status of the RecWait Request.
