API Documentation
Documentation for developing SailfishOS applicationsDeviceLock Class
(Sailfish::Mdm::DeviceLock)The DeviceLock class controls security codes and device locking. More...
Header: | #include <mdm-devicelock.h> |
Public Types
enum | ClearOption { ShutdownAfterClear, RebootAfterClear, WipePartitions, ClearExternalMedia } |
flags | ClearOptions |
enum | ManagerLockoutMode { NoManagerLockout, RecoverableManagerLockout, PermanentManagerLockout } |
enum | State { Unlocked, Locked, CodeEntryLockout, ManagerLockout, Undefined } |
Properties
|
|
Public Functions
DeviceLock(QObject *parent = nullptr) | |
~DeviceLock() | |
void | clearDevice(ClearOptions options = ShutdownAfterClear) |
bool | isChangingSecurityCode() const |
bool | isClearingDevice() const |
bool | isHomeEncrypted() |
bool | isSettingLockoutMode() const |
void | setLockoutMode(ManagerLockoutMode mode, const QVariantMap &feedback = QVariantMap()) |
void | setSecurityCode(const QString &code) |
State | state() const |
Signals
void | changingSecurityCodeChanged() |
void | clearDeviceError() |
void | clearingDeviceChanged() |
void | deviceCleared() |
void | lockoutModeChanged() |
void | lockoutModeError() |
void | securityCodeChangeError() |
void | securityCodeChanged() |
void | settingLockoutModeChanged() |
void | stateChanged() |
Detailed Description
The DeviceLock class controls security codes and device locking.
The API allows clients to lock the device, clear the device filesystem, unlock the device, or set the device security code.
To use this class, clients must add the following to their qmake project:
CONFIG += link_pkgconfig PKGCONFIG += sailfishmdm
and then #include <mdm-devicelock.h>
.
Example of usage:
#include <mdm-devicelock.h> void setOrClearDeviceLock(bool lockout, QObject *parent) { Sailfish::Mdm::DeviceLock *lock = new Sailfish::Mdm:DeviceLock(parent); if (lockout) { lock->setLockoutMode(Sailfish::Mdm::DeviceLock::RecoverableManagerLockout); QObject::connect(lock, &Sailfish::Mdm::DeviceLock::lockoutModeChanged, [] { qInfo() << "Device locked"; }); QObject::connect(lock, &Sailfish::Mdm::DeviceLock::lockoutModeError, [] { qInfo() << "Failed to lock device"; }); } else { lock->setLockoutMode(Sailfish::Mdm::DeviceLock::NoManagerLockout); QObject::connect(lock, &Sailfish::Mdm::DeviceLock::lockoutModeChanged, []() { qInfo() << "Lockout cleared"; }); QObject::connect(lock, &Sailfish::Mdm::DeviceLock::lockoutModeError, []() { qInfo() << "Failed to clear lockout"; }); } }
Member Type Documentation
enum DeviceLock::ClearOption
flags DeviceLock::ClearOptions
This enum type specifies options which may be applied when performing clearDevice(). Multiple options may be specified when performing that function, via bitwise OR.
Constant | Value | Description |
---|---|---|
Sailfish::Mdm::DeviceLock::ShutdownAfterClear | 0x00 | The device will be automatically shut down after clear. |
Sailfish::Mdm::DeviceLock::RebootAfterClear | 0x01 | The device will be automatically rebooted after clear. |
Sailfish::Mdm::DeviceLock::WipePartitions | 0x02 | All partitions will be zeroed as a result of the clear. |
Sailfish::Mdm::DeviceLock::ClearExternalMedia | 0x04 | Data on external storage will also be deleted. |
The ClearOptions type is a typedef for QFlags<ClearOption>. It stores an OR combination of ClearOption values.
enum DeviceLock::ManagerLockoutMode
This enum type specifies the changes the device manager may make to the devices lock state.
Constant | Value | Description |
---|---|---|
Sailfish::Mdm::DeviceLock::NoManagerLockout | 0 | Clears any recoverable lockout state. |
Sailfish::Mdm::DeviceLock::RecoverableManagerLockout | 1 | Puts the device into a ManagerLockout state which can be reverted. |
Sailfish::Mdm::DeviceLock::PermanentManagerLockout | 2 | Puts the device into an irreversible ManagerLock state. |
enum DeviceLock::State
This enum type specifies the possible states of the device as reported by the device lock daemon.
Note that emergency calls may be made even when the device is locked.
Constant | Value | Description |
---|---|---|
Sailfish::Mdm::DeviceLock::Unlocked | 0 | The device has been unlocked and can be used by the user. |
Sailfish::Mdm::DeviceLock::Locked | 1 | The device has been locked by the user and must be unlocked to be used. |
Sailfish::Mdm::DeviceLock::CodeEntryLockout | 3 | The device has been locked due to incorrect unlock code entries. |
Sailfish::Mdm::DeviceLock::ManagerLockout | 2 | The device has been locked via MDM and must be unlocked via MDM. |
Sailfish::Mdm::DeviceLock::Undefined | 4 | The device lock state is unknown. |
Property Documentation
changingSecurityCode : const bool
This property holds true if the security code of the device is being changed.
This value is updated if the operation triggered by a call to setSecurityCode() changes state (e.g. begins, completes or fails).
Access functions:
bool | isChangingSecurityCode() const |
Notifier signal:
void | changingSecurityCodeChanged() |
clearingDevice : const bool
This property holds true if the device is currently being cleared.
This value is updated if the operation triggered by a call to clearDevice() changes state (e.g. begins, completes or fails).
Access functions:
bool | isClearingDevice() const |
Notifier signal:
void | clearingDeviceChanged() |
homeEncrypted : const bool
This property holds true if home partition is encrypted.
Access functions:
bool | isHomeEncrypted() |
settingLockoutMode : const bool
This property holds true if the device-lock lockout mode is being changed.
This value is updated when the operation triggered by a call to setLockoutMode() changes state (e.g. begins, completes or fails).
Access functions:
bool | isSettingLockoutMode() const |
Notifier signal:
void | settingLockoutModeChanged() |
state : const State
This property holds the current device lock state.
This value is updated when the lock state of the device as reported by the device lock daemon changes.
Access functions:
State | state() const |
Notifier signal:
void | stateChanged() |
Member Function Documentation
DeviceLock::DeviceLock(QObject *parent = nullptr)
Default constructs an instance of DeviceLock.
DeviceLock::~DeviceLock()
Destroys the instance of DeviceLock.
void DeviceLock::clearDevice(ClearOptions options = ShutdownAfterClear)
Attempts to clear the device according to the specified options.
This operation is asynchronous.
If successful, deviceCleared() will be emitted. Otherwise, clearDeviceError() will be emitted.
The following options may be specified: ShutdownAfterClear
, RebootAfterClear
, WipePartitions
.
[signal]
void DeviceLock::clearDeviceError()
This signal is emitted if an attempt to clear the device filesystem via a call to clearDevice() fails.
[signal]
void DeviceLock::deviceCleared()
This signal is emitted once the device filesystem is cleared due to a call to clearDevice().
[signal]
void DeviceLock::lockoutModeChanged()
This signal is emitted when the lock state of the device transitions to locked out, as a result of a call to setLockoutMode().
[signal]
void DeviceLock::lockoutModeError()
This signal is emitted if a call to setLockoutMode() fails.
[signal]
void DeviceLock::securityCodeChangeError()
This signal is emitted if a call to setSecurityCode() fails.
[signal]
void DeviceLock::securityCodeChanged()
This signal is emitted once the security code for the device has been successfully changed as a result of a call to setSecurityCode().
void DeviceLock::setLockoutMode(ManagerLockoutMode mode, const QVariantMap &feedback = QVariantMap())
Attempts to change the device lock manager lockout state to mode.
This operation is asynchronous.
If successful, lockoutModeChanged() will be emitted. Otherwise, lockoutModeError() will be emitted.
A device in the ManagerLockout state cannot be unlocked except by the MDM client, the PermanentManagerLockout state cannot be removed ever.
The default feedback provided to the user when they are advised of the lockout can be overwritten by populating the feedback map. The following keys are supported:
warning
The warning text describing the reason for the lockout.
void DeviceLock::setSecurityCode(const QString &code)
Attempts to change the security code to the given code.
This operation is asynchronous.
If successful, securityCodeChanged() will be emitted. Otherwise, securityCodeChangeError() will be emitted.