API Documentation

Documentation for developing SailfishOS applications

DeviceLock 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

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.

ConstantValueDescription
Sailfish::Mdm::DeviceLock::ShutdownAfterClear0x00The device will be automatically shut down after clear.
Sailfish::Mdm::DeviceLock::RebootAfterClear0x01The device will be automatically rebooted after clear.
Sailfish::Mdm::DeviceLock::WipePartitions0x02All partitions will be zeroed as a result of the clear.
Sailfish::Mdm::DeviceLock::ClearExternalMedia0x04Data 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.

ConstantValueDescription
Sailfish::Mdm::DeviceLock::NoManagerLockout0Clears any recoverable lockout state.
Sailfish::Mdm::DeviceLock::RecoverableManagerLockout1Puts the device into a ManagerLockout state which can be reverted.
Sailfish::Mdm::DeviceLock::PermanentManagerLockout2Puts 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.

ConstantValueDescription
Sailfish::Mdm::DeviceLock::Unlocked0The device has been unlocked and can be used by the user.
Sailfish::Mdm::DeviceLock::Locked1The device has been locked by the user and must be unlocked to be used.
Sailfish::Mdm::DeviceLock::CodeEntryLockout3The device has been locked due to incorrect unlock code entries.
Sailfish::Mdm::DeviceLock::ManagerLockout2The device has been locked via MDM and must be unlocked via MDM.
Sailfish::Mdm::DeviceLock::Undefined4The 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.

We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.