File indexing completed on 2025-02-02 14:20:51
0001 /* 0002 SPDX-FileCopyrightText: 2008, 2011 Will Stephenson <wstephenson@kde.org> 0003 SPDX-FileCopyrightText: 2010 Lamarque Souza <lamarque@kde.org> 0004 SPDX-FileCopyrightText: 2013 Daniel Nicoletti <dantti12@gmail.com> 0005 SPDX-FileCopyrightText: 2013 Lukas Tinkl <ltinkl@redhat.com> 0006 SPDX-FileCopyrightText: 2013-2015 Jan Grulich <jgrulich@redhat.com> 0007 0008 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0009 */ 0010 0011 #ifndef MODEMMANAGERQT_MODEM_H 0012 #define MODEMMANAGERQT_MODEM_H 0013 0014 #include <ModemManager/ModemManager.h> 0015 0016 #include <modemmanagerqt_export.h> 0017 0018 #include <QDBusObjectPath> 0019 #include <QObject> 0020 #include <QSharedPointer> 0021 0022 #include "bearer.h" 0023 #include "generictypes.h" 0024 #include "interface.h" 0025 0026 namespace ModemManager 0027 { 0028 class ModemPrivate; 0029 0030 /** 0031 * This class represents bearer properties used for creating of new bearers 0032 */ 0033 class MODEMMANAGERQT_EXPORT BearerProperties 0034 { 0035 public: 0036 /** 0037 * Constructs an empty BearerProperties object 0038 */ 0039 BearerProperties(); 0040 0041 /** 0042 * Destroys this BearerProperties object. 0043 */ 0044 ~BearerProperties(); 0045 0046 /** 0047 * Constructs a BearerProperties object that is a copy of the object @p other. 0048 */ 0049 BearerProperties(const BearerProperties &other); 0050 0051 /** 0052 * Returns Access Point Name 0053 */ 0054 QString apn() const; 0055 0056 /** 0057 * Sets Access Point Name 0058 */ 0059 void setApn(const QString &apn); 0060 0061 /** 0062 * Returns addressing type 0063 */ 0064 MMBearerIpFamily ipType() const; 0065 0066 /** 0067 * Sets addressing type 0068 */ 0069 void setIpType(MMBearerIpFamily ipType); 0070 0071 /** 0072 * Returns used authentication method 0073 */ 0074 MMBearerAllowedAuth allowedAuthentication() const; 0075 0076 /** 0077 * Sets the authentication method to use 0078 */ 0079 void setAllowedAuthentication(MMBearerAllowedAuth allowedAuth); 0080 0081 /** 0082 * Returns user name 0083 */ 0084 QString user() const; 0085 0086 /** 0087 * Sets user name 0088 */ 0089 void setUser(const QString &user); 0090 0091 /** 0092 * Returns password 0093 */ 0094 QString password() const; 0095 0096 /** 0097 * Sets password 0098 */ 0099 void setPassword(const QString &password); 0100 0101 /** 0102 * Returns whether connection is allowed during roaming 0103 */ 0104 bool allowRoaming() const; 0105 0106 /** 0107 * Sets whether connection is allowed during roaming 0108 */ 0109 void setAllowRoaming(bool allow); 0110 0111 /** 0112 * Returns protocol of the Rm interface 0113 */ 0114 MMModemCdmaRmProtocol rmProtocol() const; 0115 0116 /** 0117 * Sets protocol of the Rm interface 0118 */ 0119 void setRmProtocol(MMModemCdmaRmProtocol rmProtocol); 0120 0121 /** 0122 * Returns telephone number to dial 0123 */ 0124 QString number() const; 0125 0126 /** 0127 * Sets telephone number to dial 0128 */ 0129 void setNumber(const QString &number); 0130 0131 /** 0132 * Makes a copy of the IpConfig object @p other. 0133 */ 0134 BearerProperties &operator=(const BearerProperties &other); 0135 0136 private: 0137 class Private; 0138 Private *const d; 0139 }; 0140 0141 /** 0142 * @brief The Modem class 0143 * 0144 * The Modem interface controls the status and actions in a given modem object. 0145 */ 0146 class MODEMMANAGERQT_EXPORT Modem : public Interface 0147 { 0148 Q_OBJECT 0149 Q_DECLARE_PRIVATE(Modem) 0150 0151 Q_FLAGS(MMModemCapability) 0152 Q_FLAGS(MMModemAccessTechnology) 0153 Q_FLAGS(MMModemMode) 0154 Q_FLAGS(MMBearerIpFamily) 0155 0156 public: 0157 Q_DECLARE_FLAGS(Capabilities, MMModemCapability) 0158 Q_DECLARE_FLAGS(AccessTechnologies, MMModemAccessTechnology) 0159 Q_DECLARE_FLAGS(ModemModes, MMModemMode) 0160 Q_DECLARE_FLAGS(IpBearerFamilies, MMBearerIpFamily) 0161 0162 typedef QSharedPointer<Modem> Ptr; 0163 typedef QList<Ptr> List; 0164 0165 explicit Modem(const QString &path, QObject *parent = nullptr); 0166 ~Modem() override; 0167 0168 QString uni() const; 0169 /** 0170 * @return @p true if the modem is fully functional, @p false when in low power mode or disabled 0171 * @see setEnabled() 0172 */ 0173 bool isEnabled() const; 0174 bool isValid() const; 0175 0176 /** 0177 * Enable or disable the modem. 0178 * 0179 * When enabled, the modem's radio is powered on and data sessions, voice calls, location services, and Short Message Service may be available. 0180 * 0181 * When disabled, the modem enters low-power state and no network-related operations are available. 0182 */ 0183 QDBusPendingReply<void> setEnabled(bool enable); 0184 0185 /** 0186 * Create a new packet data bearer using the given characteristics. 0187 * 0188 * This request may fail if the modem does not support additional bearers, if too many bearers are already defined, or if properties are invalid. 0189 * 0190 */ 0191 QDBusPendingReply<QDBusObjectPath> createBearer(const ModemManager::BearerProperties &bearerProperties); 0192 0193 /** 0194 * Delete an existing packet data bearer. 0195 * 0196 * If the bearer is currently active and providing packet data server, it will be disconnected and that packet data service will terminate. 0197 * @param bearer path to the bearer to delete 0198 */ 0199 QDBusPendingReply<void> deleteBearer(const QString &bearer); 0200 0201 /** 0202 * @return the configured packet data bearers (EPS Bearers, PDP Contexts, or CDMA2000 Packet Data Sessions). 0203 */ 0204 ModemManager::Bearer::List listBearers() const; 0205 0206 /** 0207 * @return the configured packet data bearer on given path 0208 */ 0209 ModemManager::Bearer::Ptr findBearer(const QString &bearer) const; 0210 0211 /** 0212 * Clear non-persistent configuration and state, and return the device to a newly-powered-on state. 0213 * 0214 * This command may power-cycle the device. 0215 */ 0216 QDBusPendingReply<void> reset(); 0217 0218 /** 0219 * Clear the modem's configuration (including persistent configuration and state), and return the device to a factory-default state. 0220 * 0221 * If not required by the modem, @p code may be ignored. 0222 * 0223 * This command may or may not power-cycle the device. 0224 * @param code Carrier-supplied code required to reset the modem. 0225 */ 0226 QDBusPendingReply<void> factoryReset(const QString &code); 0227 0228 /** 0229 * Set the power @p state of the modem. This action can only be run when the modem is in MM_MODEM_STATE_DISABLED state. 0230 */ 0231 QDBusPendingReply<void> setPowerState(MMModemPowerState state); 0232 0233 /** 0234 * Set the capabilities of the device. A restart of the modem may be required. 0235 * @param caps QFlags of MMModemCapability values, to specify the capabilities to use. 0236 */ 0237 QDBusPendingReply<void> setCurrentCapabilities(Capabilities caps); 0238 0239 /** 0240 * Set the access technologies (e.g. 2G/3G/4G preference) the device is currently allowed to use when connecting to a network. 0241 * 0242 * The given combination should be supported by the modem, as specified in supportedModes() 0243 * @param mode 0244 */ 0245 QDBusPendingReply<void> setCurrentModes(const CurrentModesType &mode); 0246 0247 /** 0248 * Set the radio frequency and technology bands the device is currently allowed to use when connecting to a network. 0249 * @param bands List of MMModemBand values, to specify the bands to be used. 0250 */ 0251 QDBusPendingReply<void> setCurrentBands(const QList<MMModemBand> &bands); 0252 0253 QDBusPendingReply<QString> command(const QString &cmd, uint timeout); 0254 0255 /** 0256 * @return The path of the SIM object available in this device, if any. 0257 */ 0258 QString simPath() const; 0259 0260 /** 0261 * @return List of MMModemCapability values, specifying the combinations of generic family of access technologies the modem supports. 0262 * 0263 * If the modem doesn't allow changing the current capabilities, a single entry with MM_MODEM_CAPABILITY_ANY will be given. 0264 */ 0265 QList<MMModemCapability> supportedCapabilities() const; 0266 0267 /** 0268 * @return QFlags of MMModemCapability values, specifying the generic family of 0269 * access technologies the modem currently supports without a firmware 0270 * reload or reinitialization. 0271 */ 0272 Capabilities currentCapabilities() const; 0273 0274 /** 0275 * @return The maximum number of defined packet data bearers the modem supports. 0276 * 0277 * This is not the number of active/connected bearers the modem supports, 0278 * but simply the number of bearers that may be defined at any given time. 0279 * For example, POTS and CDMA2000-only devices support only one bearer, 0280 * while GSM/UMTS devices typically support three or more, and any 0281 * LTE-capable device (whether LTE-only, GSM/UMTS-capable, and/or 0282 * CDMA2000-capable) also typically support three or more. 0283 */ 0284 uint maxBearers() const; 0285 0286 /** 0287 * @return The maximum number of active packet data bearers the modem supports. 0288 * 0289 * POTS and CDMA2000-only devices support one active bearer, while GSM/UMTS 0290 * and LTE-capable devices (including LTE/CDMA devices) typically support at 0291 * least two active bearers. 0292 */ 0293 uint maxActiveBearers() const; 0294 0295 /** 0296 * @return The equipment manufacturer, as reported by the modem. 0297 */ 0298 QString manufacturer() const; 0299 0300 /** 0301 * @return The equipment model, as reported by the modem. 0302 */ 0303 QString model() const; 0304 0305 /** 0306 * @return The revision identification of the software, as reported by the modem. 0307 */ 0308 QString revision() const; 0309 0310 /** 0311 * @return A best-effort device identifier based on various device 0312 * information like model name, firmware revision, USB/PCI/PCMCIA IDs, and 0313 * other properties. 0314 * 0315 * This ID is not guaranteed to be unique and may be shared between 0316 * identical devices with the same firmware, but is intended to be "unique 0317 * enough" for use as a casual device identifier for various user experience 0318 * operations. 0319 * 0320 * This is not the device's IMEI or ESN since those may not be available 0321 * before unlocking the device via a PIN. 0322 */ 0323 QString deviceIdentifier() const; 0324 0325 /** 0326 * @return The physical modem device reference (ie, USB, PCI, PCMCIA device), which may be dependent upon the operating system. 0327 * 0328 * In Linux for example, this points to a sysfs path of the usb_device object. 0329 */ 0330 QString device() const; 0331 0332 /** 0333 * @return The Operating System device drivers handling communication with the modem hardware. 0334 */ 0335 QStringList drivers() const; 0336 0337 /** 0338 * @return The name of the plugin handling this modem. 0339 */ 0340 QString plugin() const; 0341 0342 /** 0343 * @return The name of the primary port using to control the modem. 0344 */ 0345 QString primaryPort() const; 0346 0347 /** 0348 * @return The list of ports in the modem, given as an array of string and unsigned integer pairs. 0349 * The string is the port name or path, and the integer is the port type given as a MMModemPortType value. 0350 * 0351 * @since 1.1.94 0352 */ 0353 PortList ports() const; 0354 0355 /** 0356 * @return The identity of the device. 0357 * 0358 * This will be the IMEI number for GSM devices and the hex-format ESN/MEID for CDMA devices. 0359 */ 0360 QString equipmentIdentifier() const; 0361 0362 /** 0363 * @return Current lock state of the device, given as a MMModemLock value. 0364 */ 0365 MMModemLock unlockRequired() const; 0366 0367 /** 0368 * @return A dictionary in which the keys are MMModemLock flags, and the 0369 * values are integers giving the number of PIN tries remaining before the 0370 * code becomes blocked (requiring a PUK) or permanently blocked. Dictionary 0371 * entries exist only for the codes for which the modem is able to report 0372 * retry counts. 0373 */ 0374 UnlockRetriesMap unlockRetries() const; 0375 0376 /** 0377 * @return Overall state of the modem, given as a MMModemState value. 0378 * 0379 * If the device's state cannot be determined, MM_MODEM_STATE_UNKNOWN will be reported. 0380 */ 0381 MMModemState state() const; 0382 0383 /** 0384 * @return Error specifying why the modem is in MM_MODEM_STATE_FAILED state, given as a MMModemStateFailedReason value. 0385 */ 0386 MMModemStateFailedReason stateFailedReason() const; 0387 0388 /** 0389 * @return QFlags of MMModemAccessTechnology values, specifying the current 0390 * network access technologies used by the device to communicate with the 0391 * network. 0392 * 0393 * If the device's access technology cannot be determined, MM_MODEM_ACCESS_TECHNOLOGY_UNKNOWN will be reported. 0394 */ 0395 AccessTechnologies accessTechnologies() const; 0396 0397 /** 0398 * @return Signal quality in percent (0 - 100) of the dominant access 0399 * technology the device is using to communicate with the network. Always 0 0400 * for POTS devices. 0401 * 0402 * The additional boolean value indicates if the quality value given was recently taken. 0403 */ 0404 SignalQualityPair signalQuality() const; 0405 0406 /** 0407 * @return List of numbers (e.g. MSISDN in 3GPP) being currently handled by this modem. 0408 */ 0409 QStringList ownNumbers() const; 0410 0411 /** 0412 * @return A MMModemPowerState value specifying the current power state of the modem. 0413 */ 0414 MMModemPowerState powerState() const; 0415 0416 /** 0417 * @return This property exposes the supported mode combinations, given as an list of unsigned integer pairs, where: 0418 * The first integer is a bitmask of MMModemMode values, specifying the allowed modes. 0419 * The second integer is a single MMModemMode, which specifies the preferred access technology, among the ones defined in the allowed modes. 0420 */ 0421 SupportedModesType supportedModes() const; 0422 0423 /** 0424 * @return A pair of MMModemMode values, where the first one is a bitmask 0425 * specifying the access technologies (eg 2G/3G/4G) the device is currently 0426 * allowed to use when connecting to a network, and the second one is the 0427 * preferred mode of those specified as allowed. 0428 * 0429 * The pair must be one of those specified in supportedModes() 0430 */ 0431 CurrentModesType currentModes() const; 0432 0433 /** 0434 * @return List of MMModemBand values, specifying the radio frequency and technology bands supported by the device. 0435 * 0436 * For POTS devices, only the MM_MODEM_BAND_ANY mode will be returned. 0437 */ 0438 QList<MMModemBand> supportedBands() const; 0439 0440 /** 0441 * @return List of MMModemBand values, specifying the radio frequency and 0442 * technology bands the device is currently using when connecting to a 0443 * network. 0444 * 0445 * It must be a subset of supportedBands() 0446 */ 0447 QList<MMModemBand> currentBands() const; 0448 0449 /** 0450 * @return QFlags of MMBearerIpFamily values, specifying the IP families supported by the device. 0451 */ 0452 IpBearerFamilies supportedIpFamilies() const; 0453 0454 /** 0455 * Sets the timeout in milliseconds for all async method DBus calls. 0456 * -1 means the default DBus timeout (usually 25 seconds). 0457 */ 0458 void setTimeout(int timeout); 0459 0460 /** 0461 * Returns the current value of the DBus timeout in milliseconds. 0462 * -1 means the default DBus timeout (usually 25 seconds). 0463 */ 0464 int timeout() const; 0465 0466 Q_SIGNALS: 0467 void bearerAdded(const QString &bearer); 0468 void bearerRemoved(const QString &bearer); 0469 void bearersChanged(); 0470 0471 void simPathChanged(const QString &oldPath, const QString &newPath); 0472 void supportedCapabilitiesChanged(const QList<MMModemCapability> &supportedCapabilities); 0473 void currentCapabilitiesChanged(const QFlags<MMModemCapability> ¤tCapabilities); 0474 void maxBearersChanged(uint maxBearers); 0475 void maxActiveBearersChanged(uint maxActiveBearers); 0476 void manufacturerChanged(const QString &manufacturer); 0477 void modelChanged(const QString &model); 0478 void revisionChanged(const QString &revision); 0479 void deviceIdentifierChanged(const QString &deviceIdentifier); 0480 void deviceChanged(const QString &device); 0481 void driversChanged(const QStringList &drivers); 0482 void pluginChanged(const QString &plugin); 0483 void primaryPortChanged(const QString &primaryPort); 0484 void portsChanged(const ModemManager::PortList &ports); 0485 void equipmentIdentifierChanged(const QString &equipmentIdentifier); 0486 void unlockRequiredChanged(MMModemLock unlockRequired); 0487 void unlockRetriesChanged(const ModemManager::UnlockRetriesMap &unlockRetries); 0488 void stateFailedReasonChanged(MMModemStateFailedReason stateFailedReason); 0489 void accessTechnologiesChanged(QFlags<MMModemAccessTechnology> accessTechnologies); 0490 void signalQualityChanged(ModemManager::SignalQualityPair signalQuality); 0491 void ownNumbersChanged(const QStringList &ownNumbers); 0492 void powerStateChanged(MMModemPowerState powerState); 0493 void supportedModesChanged(ModemManager::SupportedModesType supportedModes); 0494 void currentModesChanged(ModemManager::CurrentModesType currentModes); 0495 void supportedBandsChanged(const QList<MMModemBand> &supportedBands); 0496 void currentBandsChanged(const QList<MMModemBand> &supportedBands); 0497 void supportedIpFamiliesChanged(QFlags<MMBearerIpFamily> supportedIpFamilies); 0498 void stateChanged(MMModemState oldState, MMModemState newState, MMModemStateChangeReason reason); 0499 }; 0500 0501 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::Capabilities) 0502 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::AccessTechnologies) 0503 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::ModemModes) 0504 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::IpBearerFamilies) 0505 0506 } // namespace ModemManager 0507 0508 #endif