Raritan / Server Technology Xerus™ PDU JSON-RPC API: GsmModem.idl Source File

Raritan / Server Technology Xerus™ PDU JSON-RPC API

GsmModem.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3 * Copyright 2011 Raritan Inc. All rights reserved.
4 */
5
6 #ifndef __GSMMODEM_IDL__
7 #define __GSMMODEM_IDL__
8
9 #include <Event.idl>
10
11 /** Serial Ports */
12 module serial {
13
14 /**
15 * Interface for communication with a GSM modem attached
16 * to a serial port
17 */
18 interface GsmModem {
19 /**
20 * Error codes
21 */
22 constant int SUCCESS = 0; ///< No error
23 constant int ERR_INVALID_VALUE = 1; ///< Invalid argument
24 constant int ERR_WRONG_PIN = 2; ///< The PIN is incorrect or missing
25 constant int ERR_SMS_SEND_FAILED = 3; ///< SMS delivery failed
26 constant int ERR_COMMUNICATION_FAILURE = 4; ///< Communication with the modem failed
27 constant int ERR_SIM_LOCKED = 5; ///< The SIM card is locked and waits for the PUK
28 constant int ERR_WRONG_SIM_STATUS = 6; ///< The SIM card doesn't wait for the PUK
29 constant int ERR_WRONG_PUK = 7; ///< The PUK is incorrect or missing
30 constant int ERR_SIM_PROBLEM = 8; ///< There is a problem with the SIM or service subscription
31
32 /**
33 * Possible security states the sim card can be in at a given time
34 */
35 enumeration SimSecurityStatus {
36 UNLOCKED, ///< SIM card is unlocked
37 WAITFORPIN, ///< PIN must be entered to unlock the SIM card
38 WAITFORPUK, ///< PUK and new PIN must be entered to unlock the SIM card
39 UNKNOWN ///< Unkown security status
40 };
41
42 /**
43 * Structure for holding settings of the GSM modem
44 * and its SIM card
45 */
46 structure Settings {
47 string pin; ///< PIN of the SIM card
48 string smsc; ///< Custom SMS center number (in ITU-T E.164 format),
49 ///< leave empty to use number stored on SIM card
50 };
51
52 /**
53 * Structure holding information about the modem and the SIM card.
54 * Any of the fields may be empty if the information can not be retrieved.
55 */
56 structure Information {
57 string imei; ///< IMEI of the modem
58 string imsi; ///< IMSI of the SIM card
59
60 string manufacturer; ///< modem manufacturer string
61 string model; ///< modem model string
62 string revision; ///< modem revision string
63
64 string ownNumber; ///< own phone number in ITU-T E.164 format
65 string simSmsc; ///< SMS center number stored on SIM card
66 string networkName; ///< Name of the currently used network (PLMN)
67 string serviceProviderName; ///< Name of the service provider (SPN)
68 int receptionLevel; ///< reception level in dBm
69 ///< 0 means unknown, -1 means no reception
70 };
71
72 /**
73 * Sim card security status changed event
74 */
75 valueobject SimSecurityStatusChangedEvent extends idl.Event {
76 SimSecurityStatus newSimStatus; ///< new SIM card security status
77 };
78
79 /**
80 * Sim pin updated event
81 */
82 valueobject SimPinUpdatedEvent extends idl.Event {
83 string newPin; ///< new PIN for SIM card after Unlock
84 };
85
86 /**
87 * @brief Get modem settings
88 *
89 * @return -- Current modem settings
90 */
91 Settings getSettings();
92
93 /**
94 * @brief Set modem settings
95 *
96 * @param settings -- New settings
97 *
98 * @return SUCCESS -- on success
99 * @return ERR_INVALID_VALUE -- if any passed value was invalid
100 */
101 int setSettings(in Settings settings);
102
103 /**
104 * @brief Send out a SMS message
105 *
106 * @param recipient -- Phone number of the message recipient in ITU-T E.164 format
107 * @param text -- Message text (will be sent in multiple messages if longer than 160 characters)
108 *
109 * @return SUCCESS -- on success
110 * @return ERR_WRONG_PIN -- if the PIN currently stored in the settings is incorrect or missing
111 * @return ERR_SMS_SEND_FAILED -- if the delivery of the SMS to the network failed
112 * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
113 * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
114 */
115 int sendSms(in string recipient, in string text);
116
117 /**
118 * @brief Send out a test SMS message
119 *
120 * The message will be sent to the selected recipient with the text 'SMS Test'.
121 *
122 * @param recipient -- Phone number of the message recipient in ITU-T E.164 format
123 * @param testSettings -- Modem settings to be used temporarily during testing
124 *
125 * @return SUCCESS -- on success
126 * @return ERR_WRONG_PIN -- if the PIN currently stored in the settings is incorrect or missing
127 * @return ERR_SMS_SEND_FAILED -- if the delivery of the SMS to the network failed
128 * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
129 * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
130 */
131 int sendTestSms(in string recipient, in Settings testSettings);
132
133 /**
134 * @brief Retrieve low-level information about the modem and the SIM card.
135 *
136 * @param info -- structure holding the returned information
137 *
138 * @return SUCCESS -- on success
139 * @return ERR_WRONG_PIN -- if the used PIN is incorrect or missing
140 * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
141 * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
142 */
143 int getInformation(out Information info);
144
145 /**
146 * @brief Retrieve low-level information about the modem and the SIM card.
147 * Like #getInformation, but allows providing a PIN not stored in the settings
148 *
149 * @param pin -- PIN to use for authentication
150 * @param info -- structure holding the returned information
151 *
152 * @return SUCCESS -- on success
153 * @return ERR_WRONG_PIN -- if the used PIN is incorrect or missing
154 * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
155 * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
156 */
157 int getInformationWithPin(in string pin, out Information info);
158
159 /**
160 * @brief Retrieve security status of the SIM card.
161 *
162 * @param simStatus -- SIM card security status
163 *
164 * @return SUCCESS -- on success
165 * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
166 */
167 int getSimSecurityStatus(out SimSecurityStatus simStatus);
168
169 /**
170 * @brief Unlock SIM card with PUK and set new PIN if the SIM card is in security status WAITFORPUK.
171 * The new PIN is automatically saved in the settings.
172 *
173 * @param puk -- PUK to use for authentication
174 * @param newPin -- new PIN to use for future authentication
175 *
176 * @return SUCCESS -- on success
177 * @return ERR_WRONG_SIM_STATUS -- if the SIM card doesn't wait for the PUK
178 * @return ERR_WRONG_PUK -- if the used PUK is incorrect or missing
179 * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
180 */
181 int unlockSimCard(in string puk, in string newPin);
182 };
183
184 }
185
186 #endif /* __GSMMODEM_IDL__ */
serial::GsmModem
Interface for communication with a GSM modem attached to a serial port.
Definition: GsmModem.idl:18
serial::GsmModem::sendSms
int sendSms(in string recipient, in string text)
Send out a SMS message.
serial::GsmModem::getInformation
int getInformation(out Information info)
Retrieve low-level information about the modem and the SIM card.
serial::GsmModem::unlockSimCard
int unlockSimCard(in string puk, in string newPin)
Unlock SIM card with PUK and set new PIN if the SIM card is in security status WAITFORPUK.
serial::GsmModem::getSettings
Settings getSettings()
Get modem settings.
serial::GsmModem::sendTestSms
int sendTestSms(in string recipient, in Settings testSettings)
Send out a test SMS message.
serial::GsmModem::SimSecurityStatus
SimSecurityStatus
Possible security states the sim card can be in at a given time.
Definition: GsmModem.idl:35
serial::GsmModem::UNLOCKED
@ UNLOCKED
SIM card is unlocked.
Definition: GsmModem.idl:36
serial::GsmModem::WAITFORPUK
@ WAITFORPUK
PUK and new PIN must be entered to unlock the SIM card.
Definition: GsmModem.idl:38
serial::GsmModem::WAITFORPIN
@ WAITFORPIN
PIN must be entered to unlock the SIM card.
Definition: GsmModem.idl:37
serial::GsmModem::setSettings
int setSettings(in Settings settings)
Set modem settings.
serial::GsmModem::getInformationWithPin
int getInformationWithPin(in string pin, out Information info)
Retrieve low-level information about the modem and the SIM card.
serial::GsmModem::getSimSecurityStatus
int getSimSecurityStatus(out SimSecurityStatus simStatus)
Retrieve security status of the SIM card.
idl
Basic IDL definitions.
Definition: Event.idl:10
serial
Serial Ports.
Definition: AnalogModem.idl:12
idl::Event
Common base for all events.
Definition: Event.idl:13
serial::GsmModem::Information
Structure holding information about the modem and the SIM card.
Definition: GsmModem.idl:56
serial::GsmModem::Information::model
string model
modem model string
Definition: GsmModem.idl:61
serial::GsmModem::Information::imei
string imei
IMEI of the modem.
Definition: GsmModem.idl:57
serial::GsmModem::Information::receptionLevel
int receptionLevel
reception level in dBm 0 means unknown, -1 means no reception
Definition: GsmModem.idl:68
serial::GsmModem::Information::networkName
string networkName
Name of the currently used network (PLMN)
Definition: GsmModem.idl:66
serial::GsmModem::Information::simSmsc
string simSmsc
SMS center number stored on SIM card.
Definition: GsmModem.idl:65
serial::GsmModem::Information::imsi
string imsi
IMSI of the SIM card.
Definition: GsmModem.idl:58
serial::GsmModem::Information::ownNumber
string ownNumber
own phone number in ITU-T E.164 format
Definition: GsmModem.idl:64
serial::GsmModem::Information::manufacturer
string manufacturer
modem manufacturer string
Definition: GsmModem.idl:60
serial::GsmModem::Information::serviceProviderName
string serviceProviderName
Name of the service provider (SPN)
Definition: GsmModem.idl:67
serial::GsmModem::Information::revision
string revision
modem revision string
Definition: GsmModem.idl:62
serial::GsmModem::Settings
Structure for holding settings of the GSM modem and its SIM card.
Definition: GsmModem.idl:46
serial::GsmModem::Settings::pin
string pin
PIN of the SIM card.
Definition: GsmModem.idl:47
serial::GsmModem::Settings::smsc
string smsc
Custom SMS center number (in ITU-T E.164 format), leave empty to use number stored on SIM card.
Definition: GsmModem.idl:48
serial::GsmModem::SimPinUpdatedEvent
Sim pin updated event.
Definition: GsmModem.idl:82
serial::GsmModem::SimPinUpdatedEvent::newPin
string newPin
new PIN for SIM card after Unlock
Definition: GsmModem.idl:83
serial::GsmModem::SimSecurityStatusChangedEvent
Sim card security status changed event.
Definition: GsmModem.idl:75
serial::GsmModem::SimSecurityStatusChangedEvent::newSimStatus
SimSecurityStatus newSimStatus
new SIM card security status
Definition: GsmModem.idl:76