/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2011 Raritan Inc. All rights reserved.
 */

#include <GsmModem.idl>
#include <AnalogModem.idl>

/** Serial Ports */
module serial {

    /**
     * Interface describing a physical serial port
     * and the devices which can be attached to it
     */
    interface SerialPort_3_0_1 {
        /**
         * Error codes
         */
        constant int SUCCESS           = 0; ///< No error
        constant int ERR_INVALID_VALUE = 1; ///< Invalid arguments

        /**
         * Possible states the port can be in at a given time
         */
        enumeration PortState {
            CONSOLE,            ///< The console application is running on the port
            ANALOGMODEM,        ///< An analog modem is attached to the port
            GSMMODEM,           ///< A GSM modem is attached to the port
            DISCONNECTED        ///< No device matching the configured mode is detected
        };

        /**
         * Device type the port shall be looking for
         */
        enumeration DetectionType {
            AUTOMATIC,          ///< Try to automatically determine the connected device
            FORCE_CONSOLE,      ///< Always assume a console (terminal) is connected
            FORCE_ANALOGMODEM,  ///< Always assume an analog modem is connected
            FORCE_GSMMODEM      ///< Always assume a GSM modem is connected
        };

        /**
         * Possible baud rates
         */
        enumeration BaudRate {
            BR1200,             ///<   1.200 kbit/s
            BR2400,             ///<   2.400 kbit/s
            BR4800,             ///<   4.800 kbit/s
            BR9600,             ///<   9.600 kbit/s
            BR19200,            ///<  19.200 kbit/s
            BR38400,            ///<  38.400 kbit/s
            BR57600,            ///<  57.600 kbit/s
            BR115200            ///< 115.200 kbit/s
        };

        /**
         * (Static) meta data containing port properties
         */
        structure MetaData {
            boolean hasModemSupport; ///< Whether or not the port can detect modems (if false,
                                     ///< this port can only operate in console mode)
        };

        /**
         * Structure holding information about
         * the current state of the port
         */
        structure State {
            PortState state;    ///< Current connection state
            string deviceName;  ///< Name of the device currently connected
        };

        /**
         * Port settings
         */
        structure Settings {
            BaudRate consoleBaudRate;   ///< Baud rate to be used for running the console application
            BaudRate modemBaudRate;     ///< Baud rate to be used for communicating with an attached modem
            DetectionType detectType;   ///< Type of connected device to be assumed in device detection
        };

        /**
         * Event emitted when the modem connection state changes
         */
        valueobject ModemEvent extends idl.Event {
            Object modem;               ///< Either a {@link AnalogModem} or a {@link GsmModem}
        };

        /**
         * Event emitted when a modem is connected
         */
        valueobject ModemAddedEvent extends ModemEvent {
        };

        /**
         * Event emitted when a modem is disconnected
         */
        valueobject ModemRemovedEvent extends ModemEvent {
        };

        /**
         * @brief Get port meta data
         *
         * @return -- Meta data
         */
        MetaData getMetaData();

        /**
         * @brief Get current settings
         *
         * @return -- Settings
         */
        Settings getSettings();

        /**
         * @brief Set settings
         *
         * @param settings -- new settings
         *
         * @return SUCCESS           -- on success
         * @return ERR_INVALID_VALUE -- if any passed value was invalid
         */
        int setSettings(in Settings settings);

        /**
         * @brief Get current port state
         *
         * @return -- Port state
         */
        State getState();

        /**
         * @brief Get modem connected to port
         *
         * @return -- an instance of the connected modem (either
         *            {@link AnalogModem} or {@link GsmModem})
         */
        Object getModem();
    };

}
