modemmanager-qt-dev 5.44.0-0ubuntu1 / usr / include / KF5 / ModemManagerQt / modem.h

/*
    Copyright 2008,2011 Will Stephenson <wstephenson@kde.org>
    Copyright 2010 Lamarque Souza <lamarque@kde.org>
    Copyright 2013 Daniel Nicoletti <dantti12@gmail.com>
    Copyright 2013 Lukas Tinkl <ltinkl@redhat.com>
    Copyright 2013-2015 Jan Grulich <jgrulich@redhat.com>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) version 3, or any
    later version accepted by the membership of KDE e.V. (or its
    successor approved by the membership of KDE e.V.), which shall
    act as a proxy defined in Section 6 of version 3 of the license.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef MODEMMANAGERQT_MODEM_H
#define MODEMMANAGERQT_MODEM_H

#include <ModemManager/ModemManager.h>

#include <modemmanagerqt_export.h>

#include <QObject>
#include <QVariant>
#include <QSharedPointer>
#include <QDBusObjectPath>

#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();

    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;

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