File indexing completed on 2024-04-21 03:59:49

 /*
     SPDX-FileCopyrightText: 2008, 2011 Will Stephenson <wstephenson@kde.org>
     SPDX-FileCopyrightText: 2010 Lamarque Souza <lamarque@kde.org>
     SPDX-FileCopyrightText: 2013 Daniel Nicoletti <dantti12@gmail.com>
     SPDX-FileCopyrightText: 2013 Lukas Tinkl <ltinkl@redhat.com>
     SPDX-FileCopyrightText: 2013-2015 Jan Grulich <jgrulich@redhat.com>
 
     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
 */
 
 #ifndef MODEMMANAGERQT_MODEM_H
 #define MODEMMANAGERQT_MODEM_H
 
 #include <ModemManager/ModemManager.h>
 
 #include <modemmanagerqt_export.h>
 
 #include <QDBusObjectPath>
 #include <QObject>
 #include <QSharedPointer>
 
 #include "bearer.h"
 #include "generictypes.h"
 #include "interface.h"
 
 namespace ModemManager
 {
 class ModemPrivate;
 
 /**
  * This class represents bearer properties used for creating of new bearers
  */
 class MODEMMANAGERQT_EXPORT BearerProperties
 {
 public:
     /**
      * Constructs an empty BearerProperties object
      */
     BearerProperties();
 
     /**
      * Destroys this BearerProperties object.
      */
     ~BearerProperties();
 
     /**
      * Constructs a BearerProperties object that is a copy of the object @p other.
      */
     BearerProperties(const BearerProperties &other);
 
     /**
      * Returns Access Point Name
      */
     QString apn() const;
 
     /**
      * Sets Access Point Name
      */
     void setApn(const QString &apn);
 
     /**
      * Returns addressing type
      */
     MMBearerIpFamily ipType() const;
 
     /**
      * Sets addressing type
      */
     void setIpType(MMBearerIpFamily ipType);
 
     /**
      * Returns used authentication method
      */
     MMBearerAllowedAuth allowedAuthentication() const;
 
     /**
      * Sets the authentication method to use
      */
     void setAllowedAuthentication(MMBearerAllowedAuth allowedAuth);
 
     /**
      * Returns user name
      */
     QString user() const;
 
     /**
      * Sets user name
      */
     void setUser(const QString &user);
 
     /**
      * Returns password
      */
     QString password() const;
 
     /**
      * Sets password
      */
     void setPassword(const QString &password);
 
     /**
      * Returns whether connection is allowed during roaming
      */
     bool allowRoaming() const;
 
     /**
      * Sets whether connection is allowed during roaming
      */
     void setAllowRoaming(bool allow);
 
     /**
      * Returns protocol of the Rm interface
      */
     MMModemCdmaRmProtocol rmProtocol() const;
 
     /**
      * Sets protocol of the Rm interface
      */
     void setRmProtocol(MMModemCdmaRmProtocol rmProtocol);
 
     /**
      * Returns telephone number to dial
      */
     QString number() const;
 
     /**
      * Sets telephone number to dial
      */
     void setNumber(const QString &number);
 
     /**
      * Makes a copy of the IpConfig object @p other.
      */
     BearerProperties &operator=(const BearerProperties &other);
 
 private:
     class Private;
     Private *const d;
 };
 
 /**
  * @brief The Modem class
  *
  * The Modem interface controls the status and actions in a given modem object.
  */
 class MODEMMANAGERQT_EXPORT Modem : public Interface
 {
     Q_OBJECT
     Q_DECLARE_PRIVATE(Modem)
 
     Q_FLAGS(MMModemCapability)
     Q_FLAGS(MMModemAccessTechnology)
     Q_FLAGS(MMModemMode)
     Q_FLAGS(MMBearerIpFamily)
 
 public:
     Q_DECLARE_FLAGS(Capabilities, MMModemCapability)
     Q_DECLARE_FLAGS(AccessTechnologies, MMModemAccessTechnology)
     Q_DECLARE_FLAGS(ModemModes, MMModemMode)
     Q_DECLARE_FLAGS(IpBearerFamilies, MMBearerIpFamily)
 
     typedef QSharedPointer<Modem> Ptr;
     typedef QList<Ptr> List;
 
     explicit Modem(const QString &path, QObject *parent = nullptr);
     ~Modem() override;
 
     QString uni() const;
     /**
      * @return @p true if the modem is fully functional, @p false when in low power mode or disabled
      * @see setEnabled()
      */
     bool isEnabled() const;
     bool isValid() const;
 
     /**
      * Enable or disable the modem.
      *
      * When enabled, the modem's radio is powered on and data sessions, voice calls, location services, and Short Message Service may be available.
      *
      * When disabled, the modem enters low-power state and no network-related operations are available.
      */
     QDBusPendingReply<void> setEnabled(bool enable);
 
     /**
      * Create a new packet data bearer using the given characteristics.
      *
      * This request may fail if the modem does not support additional bearers, if too many bearers are already defined, or if properties are invalid.
      *
      */
     QDBusPendingReply<QDBusObjectPath> createBearer(const ModemManager::BearerProperties &bearerProperties);
 
     /**
      * Delete an existing packet data bearer.
      *
      * If the bearer is currently active and providing packet data server, it will be disconnected and that packet data service will terminate.
      * @param bearer path to the bearer to delete
      */
     QDBusPendingReply<void> deleteBearer(const QString &bearer);
 
     /**
      * @return the configured packet data bearers (EPS Bearers, PDP Contexts, or CDMA2000 Packet Data Sessions).
      */
     ModemManager::Bearer::List listBearers() const;
 
     /**
      * @return the configured packet data bearer on given path
      */
     ModemManager::Bearer::Ptr findBearer(const QString &bearer) const;
 
     /**
      * Clear non-persistent configuration and state, and return the device to a newly-powered-on state.
      *
      * This command may power-cycle the device.
      */
     QDBusPendingReply<void> reset();
 
     /**
      * Clear the modem's configuration (including persistent configuration and state), and return the device to a factory-default state.
      *
      * If not required by the modem, @p code may be ignored.
      *
      * This command may or may not power-cycle the device.
      * @param code Carrier-supplied code required to reset the modem.
      */
     QDBusPendingReply<void> factoryReset(const QString &code);
 
     /**
      * Set the power @p state of the modem. This action can only be run when the modem is in MM_MODEM_STATE_DISABLED state.
      */
     QDBusPendingReply<void> setPowerState(MMModemPowerState state);
 
     /**
      * Set the capabilities of the device. A restart of the modem may be required.
      * @param caps QFlags of MMModemCapability values, to specify the capabilities to use.
      */
     QDBusPendingReply<void> setCurrentCapabilities(Capabilities caps);
 
     /**
      * Set the access technologies (e.g. 2G/3G/4G preference) the device is currently allowed to use when connecting to a network.
      *
      * The given combination should be supported by the modem, as specified in supportedModes()
      * @param mode
      */
     QDBusPendingReply<void> setCurrentModes(const CurrentModesType &mode);
 
     /**
      * Set the radio frequency and technology bands the device is currently allowed to use when connecting to a network.
      * @param bands List of MMModemBand values, to specify the bands to be used.
      */
     QDBusPendingReply<void> setCurrentBands(const QList<MMModemBand> &bands);
 
     QDBusPendingReply<QString> command(const QString &cmd, uint timeout);
 
     /**
      * @return The path of the SIM object available in this device, if any.
      */
     QString simPath() const;
 
     /**
      * @return List of MMModemCapability values, specifying the combinations of generic family of access technologies the modem supports.
      *
      * If the modem doesn't allow changing the current capabilities, a single entry with MM_MODEM_CAPABILITY_ANY will be given.
      */
     QList<MMModemCapability> supportedCapabilities() const;
 
     /**
      * @return QFlags of MMModemCapability values, specifying the generic family of
      * access technologies the modem currently supports without a firmware
      * reload or reinitialization.
      */
     Capabilities currentCapabilities() const;
 
     /**
      * @return The maximum number of defined packet data bearers the modem supports.
      *
      * This is not the number of active/connected bearers the modem supports,
      * but simply the number of bearers that may be defined at any given time.
      * For example, POTS and CDMA2000-only devices support only one bearer,
      * while GSM/UMTS devices typically support three or more, and any
      * LTE-capable device (whether LTE-only, GSM/UMTS-capable, and/or
      * CDMA2000-capable) also typically support three or more.
      */
     uint maxBearers() const;
 
     /**
      * @return The maximum number of active packet data bearers the modem supports.
      *
      * POTS and CDMA2000-only devices support one active bearer, while GSM/UMTS
      * and LTE-capable devices (including LTE/CDMA devices) typically support at
      * least two active bearers.
      */
     uint maxActiveBearers() const;
 
     /**
      * @return The equipment manufacturer, as reported by the modem.
      */
     QString manufacturer() const;
 
     /**
      * @return The equipment model, as reported by the modem.
      */
     QString model() const;
 
     /**
      * @return The revision identification of the software, as reported by the modem.
      */
     QString revision() const;
 
     /**
      * @return A best-effort device identifier based on various device
      * information like model name, firmware revision, USB/PCI/PCMCIA IDs, and
      * other properties.
      *
      * This ID is not guaranteed to be unique and may be shared between
      * identical devices with the same firmware, but is intended to be "unique
      * enough" for use as a casual device identifier for various user experience
      * operations.
      *
      * This is not the device's IMEI or ESN since those may not be available
      * before unlocking the device via a PIN.
      */
     QString deviceIdentifier() const;
 
     /**
      * @return The physical modem device reference (ie, USB, PCI, PCMCIA device), which may be dependent upon the operating system.
      *
      * In Linux for example, this points to a sysfs path of the usb_device object.
      */
     QString device() const;
 
     /**
      * @return The Operating System device drivers handling communication with the modem hardware.
      */
     QStringList drivers() const;
 
     /**
      * @return The name of the plugin handling this modem.
      */
     QString plugin() const;
 
     /**
      * @return The name of the primary port using to control the modem.
      */
     QString primaryPort() const;
 
     /**
      * @return The list of ports in the modem, given as an array of string and unsigned integer pairs.
      * The string is the port name or path, and the integer is the port type given as a MMModemPortType value.
      *
      * @since 1.1.94
      */
     PortList ports() const;
 
     /**
      * @return The identity of the device.
      *
      * This will be the IMEI number for GSM devices and the hex-format ESN/MEID for CDMA devices.
      */
     QString equipmentIdentifier() const;
 
     /**
      * @return Current lock state of the device, given as a MMModemLock value.
      */
     MMModemLock unlockRequired() const;
 
     /**
      * @return A dictionary in which the keys are MMModemLock flags, and the
      * values are integers giving the number of PIN tries remaining before the
      * code becomes blocked (requiring a PUK) or permanently blocked. Dictionary
      * entries exist only for the codes for which the modem is able to report
      * retry counts.
      */
     UnlockRetriesMap unlockRetries() const;
 
     /**
      * @return Overall state of the modem, given as a MMModemState value.
      *
      * If the device's state cannot be determined, MM_MODEM_STATE_UNKNOWN will be reported.
      */
     MMModemState state() const;
 
     /**
      * @return Error specifying why the modem is in MM_MODEM_STATE_FAILED state, given as a MMModemStateFailedReason value.
      */
     MMModemStateFailedReason stateFailedReason() const;
 
     /**
      * @return QFlags of MMModemAccessTechnology values, specifying the current
      * network access technologies used by the device to communicate with the
      * network.
      *
      * If the device's access technology cannot be determined, MM_MODEM_ACCESS_TECHNOLOGY_UNKNOWN will be reported.
      */
     AccessTechnologies accessTechnologies() const;
 
     /**
      * @return Signal quality in percent (0 - 100) of the dominant access
      * technology the device is using to communicate with the network. Always 0
      * for POTS devices.
      *
      * The additional boolean value indicates if the quality value given was recently taken.
      */
     SignalQualityPair signalQuality() const;
 
     /**
      * @return List of numbers (e.g. MSISDN in 3GPP) being currently handled by this modem.
      */
     QStringList ownNumbers() const;
 
     /**
      * @return A MMModemPowerState value specifying the current power state of the modem.
      */
     MMModemPowerState powerState() const;
 
     /**
      * @return This property exposes the supported mode combinations, given as an list of unsigned integer pairs, where:
      * The first integer is a bitmask of MMModemMode values, specifying the allowed modes.
      * The second integer is a single MMModemMode, which specifies the preferred access technology, among the ones defined in the allowed modes.
      */
     SupportedModesType supportedModes() const;
 
     /**
      * @return A pair of MMModemMode values, where the first one is a bitmask
      * specifying the access technologies (eg 2G/3G/4G) the device is currently
      * allowed to use when connecting to a network, and the second one is the
      * preferred mode of those specified as allowed.
      *
      * The pair must be one of those specified in supportedModes()
      */
     CurrentModesType currentModes() const;
 
     /**
      * @return List of MMModemBand values, specifying the radio frequency and technology bands supported by the device.
      *
      * For POTS devices, only the MM_MODEM_BAND_ANY mode will be returned.
      */
     QList<MMModemBand> supportedBands() const;
 
     /**
      * @return List of MMModemBand values, specifying the radio frequency and
      * technology bands the device is currently using when connecting to a
      * network.
      *
      * It must be a subset of supportedBands()
      */
     QList<MMModemBand> currentBands() const;
 
     /**
      * @return QFlags of MMBearerIpFamily values, specifying the IP families supported by the device.
      */
     IpBearerFamilies supportedIpFamilies() const;
 
     /**
      * Sets the timeout in milliseconds for all async method DBus calls.
      * -1 means the default DBus timeout (usually 25 seconds).
      */
     void setTimeout(int timeout);
 
     /**
      * Returns the current value of the DBus timeout in milliseconds.
      * -1 means the default DBus timeout (usually 25 seconds).
      */
     int timeout() const;
 
 Q_SIGNALS:
     void bearerAdded(const QString &bearer);
     void bearerRemoved(const QString &bearer);
     void bearersChanged();
 
     void simPathChanged(const QString &oldPath, const QString &newPath);
     void supportedCapabilitiesChanged(const QList<MMModemCapability> &supportedCapabilities);
     void currentCapabilitiesChanged(const QFlags<MMModemCapability> &currentCapabilities);
     void maxBearersChanged(uint maxBearers);
     void maxActiveBearersChanged(uint maxActiveBearers);
     void manufacturerChanged(const QString &manufacturer);
     void modelChanged(const QString &model);
     void revisionChanged(const QString &revision);
     void deviceIdentifierChanged(const QString &deviceIdentifier);
     void deviceChanged(const QString &device);
     void driversChanged(const QStringList &drivers);
     void pluginChanged(const QString &plugin);
     void primaryPortChanged(const QString &primaryPort);
     void portsChanged(const ModemManager::PortList &ports);
     void equipmentIdentifierChanged(const QString &equipmentIdentifier);
     void unlockRequiredChanged(MMModemLock unlockRequired);
     void unlockRetriesChanged(const ModemManager::UnlockRetriesMap &unlockRetries);
     void stateFailedReasonChanged(MMModemStateFailedReason stateFailedReason);
     void accessTechnologiesChanged(QFlags<MMModemAccessTechnology> accessTechnologies);
     void signalQualityChanged(ModemManager::SignalQualityPair signalQuality);
     void ownNumbersChanged(const QStringList &ownNumbers);
     void powerStateChanged(MMModemPowerState powerState);
     void supportedModesChanged(ModemManager::SupportedModesType supportedModes);
     void currentModesChanged(ModemManager::CurrentModesType currentModes);
     void supportedBandsChanged(const QList<MMModemBand> &supportedBands);
     void currentBandsChanged(const QList<MMModemBand> &supportedBands);
     void supportedIpFamiliesChanged(QFlags<MMBearerIpFamily> supportedIpFamilies);
     void stateChanged(MMModemState oldState, MMModemState newState, MMModemStateChangeReason reason);
 };
 
 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::Capabilities)
 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::AccessTechnologies)
 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::ModemModes)
 Q_DECLARE_OPERATORS_FOR_FLAGS(Modem::IpBearerFamilies)
 
 } // namespace ModemManager
 
 #endif