Legrand / Raritan / Server Technology Xerus™ JSON-RPC API
Loading...
Searching...
No Matches
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 */
12module 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 */
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 */
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 */
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 */
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__ */
Interface for communication with a GSM modem attached to a serial port.
Definition: GsmModem.idl:18
int sendSms(in string recipient, in string text)
Send out a SMS message.
int getInformation(out Information info)
Retrieve low-level information about the modem and the SIM card.
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.
Settings getSettings()
Get modem settings.
int sendTestSms(in string recipient, in Settings testSettings)
Send out a test SMS message.
SimSecurityStatus
Possible security states the sim card can be in at a given time.
Definition: GsmModem.idl:35
@ UNLOCKED
SIM card is unlocked.
Definition: GsmModem.idl:36
@ WAITFORPUK
PUK and new PIN must be entered to unlock the SIM card.
Definition: GsmModem.idl:38
@ WAITFORPIN
PIN must be entered to unlock the SIM card.
Definition: GsmModem.idl:37
int setSettings(in Settings settings)
Set modem settings.
int getInformationWithPin(in string pin, out Information info)
Retrieve low-level information about the modem and the SIM card.
int getSimSecurityStatus(out SimSecurityStatus simStatus)
Retrieve security status of the SIM card.
Basic IDL definitions.
Definition: Event.idl:10
Serial Ports.
Definition: AnalogModem.idl:12
Common base for all events.
Definition: Event.idl:13
Structure holding information about the modem and the SIM card.
Definition: GsmModem.idl:56
string model
modem model string
Definition: GsmModem.idl:61
string imei
IMEI of the modem.
Definition: GsmModem.idl:57
int receptionLevel
reception level in dBm 0 means unknown, -1 means no reception
Definition: GsmModem.idl:68
string networkName
Name of the currently used network (PLMN)
Definition: GsmModem.idl:66
string simSmsc
SMS center number stored on SIM card.
Definition: GsmModem.idl:65
string imsi
IMSI of the SIM card.
Definition: GsmModem.idl:58
string ownNumber
own phone number in ITU-T E.164 format
Definition: GsmModem.idl:64
string manufacturer
modem manufacturer string
Definition: GsmModem.idl:60
string serviceProviderName
Name of the service provider (SPN)
Definition: GsmModem.idl:67
string revision
modem revision string
Definition: GsmModem.idl:62
Structure for holding settings of the GSM modem and its SIM card.
Definition: GsmModem.idl:46
string pin
PIN of the SIM card.
Definition: GsmModem.idl:47
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
Sim pin updated event.
Definition: GsmModem.idl:82
string newPin
new PIN for SIM card after Unlock
Definition: GsmModem.idl:83
Sim card security status changed event.
Definition: GsmModem.idl:75
SimSecurityStatus newSimStatus
new SIM card security status
Definition: GsmModem.idl:76