GsmModem.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2011 Raritan Inc. All rights reserved.
 */
 
#ifndef __GSMMODEM_IDL__
#define __GSMMODEM_IDL__
 
#include <Event.idl>
 
/** Serial Ports */
module serial {
 
    /**
     * Interface for communication with a GSM modem attached
     * to a serial port
     */
    interface GsmModem {
        /**
         * Error codes
         */
        constant int SUCCESS                   = 0; ///< No error
        constant int ERR_INVALID_VALUE         = 1; ///< Invalid argument
        constant int ERR_WRONG_PIN             = 2; ///< The PIN is incorrect or missing
        constant int ERR_SMS_SEND_FAILED       = 3; ///< SMS delivery failed
        constant int ERR_COMMUNICATION_FAILURE = 4; ///< Communication with the modem failed
        constant int ERR_SIM_LOCKED            = 5; ///< The SIM card is locked and waits for the PUK
        constant int ERR_WRONG_SIM_STATUS      = 6; ///< The SIM card doesn't wait for the PUK
        constant int ERR_WRONG_PUK             = 7; ///< The PUK is incorrect or missing
        constant int ERR_SIM_PROBLEM           = 8; ///< There is a problem with the SIM or service subscription
 
        /**
         * Possible security states the sim card can be in at a given time
         */
        enumeration SimSecurityStatus {
            UNLOCKED,           ///< SIM card is unlocked
            WAITFORPIN,         ///< PIN must be entered to unlock the SIM card
            WAITFORPUK,         ///< PUK and new PIN must be entered to unlock the SIM card
            UNKNOWN             ///< Unkown security status
        };
 
        /**
         * Structure for holding settings of the GSM modem
         * and its SIM card
         */
        structure Settings {
            string pin;         ///< PIN of the SIM card
            string smsc;        ///< Custom SMS center number (in ITU-T E.164 format),
                                ///< leave empty to use number stored on SIM card
        };
 
        /**
         * Structure holding information about the modem and the SIM card.
         * Any of the fields may be empty if the information can not be retrieved.
         */
        structure Information {
            string imei;                ///< IMEI of the modem
            string imsi;                ///< IMSI of the SIM card
 
            string manufacturer;        ///< modem manufacturer string
            string model;               ///< modem model string
            string revision;            ///< modem revision string
 
            string ownNumber;           ///< own phone number in ITU-T E.164 format
            string simSmsc;             ///< SMS center number stored on SIM card
            string networkName;         ///< Name of the currently used network (PLMN)
            string serviceProviderName; ///< Name of the service provider (SPN)
            int receptionLevel;         ///< reception level in dBm
                                        ///< 0 means unknown, -1 means no reception
        };
 
        /**
         * Sim card security status changed event
         */
        valueobject SimSecurityStatusChangedEvent extends idl.Event {
            SimSecurityStatus newSimStatus; ///< new SIM card security status
        };
 
        /**
         * Sim pin updated event
         */
        valueobject SimPinUpdatedEvent extends idl.Event {
            string newPin; ///< new PIN for SIM card after Unlock
        };
 
        /**
         * @brief Get modem settings
         *
         * @return -- Current modem settings
         */
        Settings getSettings();
 
        /**
         * @brief Set modem 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 Send out a SMS message
         *
         * @param recipient -- Phone number of the message recipient in ITU-T E.164 format
         * @param text      -- Message text (will be sent in multiple messages if longer than 160 characters)
         *
         * @return SUCCESS                   -- on success
         * @return ERR_WRONG_PIN             -- if the PIN currently stored in the settings is incorrect or missing
         * @return ERR_SMS_SEND_FAILED       -- if the delivery of the SMS to the network failed
         * @return ERR_SIM_LOCKED            -- if the SIM card is locked and waits for the PUK
         * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
         */
        int sendSms(in string recipient, in string text);
 
        /**
         * @brief Send out a test SMS message
         *
         * The message will be sent to the selected recipient with the text 'SMS Test'.
         *
         * @param recipient    -- Phone number of the message recipient in ITU-T E.164 format
         * @param testSettings -- Modem settings to be used temporarily during testing
         *
         * @return SUCCESS                   -- on success
         * @return ERR_WRONG_PIN             -- if the PIN currently stored in the settings is incorrect or missing
         * @return ERR_SMS_SEND_FAILED       -- if the delivery of the SMS to the network failed
         * @return ERR_SIM_LOCKED            -- if the SIM card is locked and waits for the PUK
         * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
         */
        int sendTestSms(in string recipient, in Settings testSettings);
 
        /**
         * @brief Retrieve low-level information about the modem and the SIM card.
         *
         * @param info         -- structure holding the returned information
         *
         * @return SUCCESS                   -- on success
         * @return ERR_WRONG_PIN             -- if the used PIN is incorrect or missing
         * @return ERR_SIM_LOCKED            -- if the SIM card is locked and waits for the PUK
         * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
         */
        int getInformation(out Information info);
 
        /**
         * @brief Retrieve low-level information about the modem and the SIM card.
         *        Like #getInformation, but allows providing a PIN not stored in the settings
         *
         * @param pin   -- PIN to use for authentication
         * @param info  -- structure holding the returned information
         *
         * @return SUCCESS                   -- on success
         * @return ERR_WRONG_PIN             -- if the used PIN is incorrect or missing
         * @return ERR_SIM_LOCKED            -- if the SIM card is locked and waits for the PUK
         * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
         */
        int getInformationWithPin(in string pin, out Information info);
 
        /**
         * @brief Retrieve security status of the SIM card.
         *
         * @param simStatus -- SIM card security status
         *
         * @return SUCCESS                   -- on success
         * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
         */
        int getSimSecurityStatus(out SimSecurityStatus simStatus);
 
        /**
         * @brief Unlock SIM card with PUK and set new PIN if the SIM card is in security status WAITFORPUK.
         *        The new PIN is automatically saved in the settings.
         *
         * @param puk    -- PUK to use for authentication
         * @param newPin -- new PIN to use for future authentication
         *
         * @return SUCCESS                   -- on success
         * @return ERR_WRONG_SIM_STATUS      -- if the SIM card doesn't wait for the PUK
         * @return ERR_WRONG_PUK             -- if the used PUK is incorrect or missing
         * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
         */
        int unlockSimCard(in string puk, in string newPin);
    };
 
}
 
#endif /* __GSMMODEM_IDL__ */