@ohos.runningLock (RunningLock)

The runningLock module provides APIs for creating, querying, holding, and releasing running locks. A running lock enables the proximity sensor to turn on or off the screen, or prevents the device from entering sleep mode when the screen is off. For details about the running lock types, see RunningLockType.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import {runningLock} from '@kit.BasicServicesKit';

runningLock.isSupported⁹⁺

isSupported(type: RunningLockType): boolean

API description: Checks whether the system supports the running lock of a specified type.

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
type	RunningLockType	Yes	Type of the running lock. The value must be an enum.

Returns

Type	Description
boolean	The value true indicates that the specified type of the running lock is supported, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed.

Example

try {
    let isSupported = runningLock.isSupported(runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL);
    console.info('BACKGROUND type supported: ' + isSupported);
} catch(err) {
    console.error('check supported failed, err: ' + err);
}

runningLock.create⁹⁺

create(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void

API description: Creates a running lock. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the RunningLock object. The value must be a string.
type	RunningLockType	Yes	Type of the RunningLock object. The value must be an enum.
callback	AsyncCallback<RunningLock>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the created RunningLock object. Otherwise, err is an error object. AsyncCallback has encapsulated an API of the RunningLock class.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Parameter verification failed.
201	If the permission is denied.

Example


runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
    if (typeof err === 'undefined') {
        console.info('created running lock: ' + lock);
    } else {
        console.error('create running lock failed, err: ' + err);
    }
});

runningLock.create⁹⁺

create(name: string, type: RunningLockType): Promise<RunningLock>

API description: Creates a running lock. This API uses a promise to return the result.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the RunningLock object. The value must be a string.
type	RunningLockType	Yes	Type of the RunningLock object. The value must be an enum.

Returns

Type	Description
Promise<RunningLock>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Parameter verification failed.
201	If the permission is denied.

Example


runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL)
.then((lock: runningLock.RunningLock) => {
    console.info('created running lock: ' + lock);
})
.catch((err: Error) => {
    console.error('create running lock failed, err: ' + err);
});

runningLock.isRunningLockTypeSupported^(deprecated)

isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback<boolean>): void

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use runningLock.isSupported instead.

API description: Checks whether the system supports the running lock of a specified type. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
type	RunningLockType	Yes	Type of the running lock.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the query result obtained, where the value true indicates that the specified type of the running lock is supported and false indicates the opposite. Otherwise, err is an error object.

Example

runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND, (err: Error, data: boolean) => {
    if (typeof err === 'undefined') {
        console.info('BACKGROUND lock support status: ' + data);
    } else {
        console.error('check BACKGROUND lock support status failed, err: ' + err);
    }
});

runningLock.isRunningLockTypeSupported^(deprecated)

isRunningLockTypeSupported(type: RunningLockType): Promise<boolean>

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use runningLock.isSupported instead.

API description: Checks whether the system supports the running lock of a specified type. This API uses a promise to return the result.

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
type	RunningLockType	Yes	Type of the running lock.

Returns

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the specified type of the running lock is supported, and the value false indicates the opposite.

Example

runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND)
.then((data: boolean) => {
    console.info('BACKGROUND lock support status: ' + data);
})
.catch((err: Error) => {
    console.error('check BACKGROUND lock support status failed, err: ' + err);
});

runningLock.createRunningLock^(deprecated)

createRunningLock(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use runningLock.create instead.

API description: Creates a running lock. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the RunningLock object.
type	RunningLockType	Yes	Type of the RunningLock object to be created.
callback	AsyncCallback<RunningLock>	Yes	Callback used to return the result. If a lock is successfully created, err is undefined and data is the created RunningLock. Otherwise, err is an error object.

Example

runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND, (err: Error, lock: runningLock.RunningLock) => {
    if (typeof err === 'undefined') {
        console.info('created running lock: ' + lock);
    } else {
        console.error('create running lock failed, err: ' + err);
    }
});

runningLock.createRunningLock^(deprecated)

createRunningLock(name: string, type: RunningLockType): Promise<RunningLock>

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use runningLock.create instead.

API description: Creates a running lock. This API uses a promise to return the result.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the RunningLock object.
type	RunningLockType	Yes	Type of the RunningLock object to be created.

Returns

Type	Description
Promise<RunningLock>	Promise used to return the result.

Example

runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
.then((lock: runningLock.RunningLock) => {
    console.info('created running lock: ' + lock);
})
.catch((err: Error) => {
    console.error('create running lock failed, err: ' + err);
});

RunningLock

Defines a RunningLock object.

hold⁹⁺

hold(timeout: number): void

API description: Holds a running lock.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Parameters

Name	Type	Mandatory	Description
timeout	number	Yes	Duration for locking and holding the RunningLock object, in ms. The value must be a number: -1: The lock is permanently held and needs to be released automatically. 0: The lock is released 3 seconds after the timer expires by default. > 0: The lock is released based on the input value after the timer expires.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Incorrect parameter types.
201	If the permission is denied.

Example

// RunningLockTest.ets
class RunningLockTest {
    public static recordLock: runningLock.RunningLock;

    public static holdRunningLock(): void {
        if (RunningLockTest.recordLock) {
            RunningLockTest.recordLock.hold(500);
            console.info('hold running lock success');
        } else {
            runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
                if (typeof err === 'undefined') {
                    console.info('create running lock: ' + lock);
                    RunningLockTest.recordLock = lock;
                    try {
                        lock.hold(500);
                        console.info('hold running lock success');
                    } catch(err) {
                        console.error('hold running lock failed, err: ' + err);
                    }
                } else {
                    console.error('create running lock failed, err: ' + err);
                }
            });
        }
    }
}

unhold⁹⁺

unhold(): void

API description: Releases this running lock.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	If the permission is denied.

Example

// RunningLockTest.ets
class RunningLockTest {
    public static recordLock: runningLock.RunningLock;

    public static unholdRunningLock(): void {
        if (RunningLockTest.recordLock) {
            RunningLockTest.recordLock.unhold();
            console.info('unhold running lock success');
        } else {
            runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
                if (typeof err === 'undefined') {
                    console.info('create running lock: ' + lock);
                    RunningLockTest.recordLock = lock;
                    try {
                        lock.unhold();
                        console.info('unhold running lock success');
                    } catch(err) {
                        console.error('unhold running lock failed, err: ' + err);
                    }
                } else {
                    console.error('create running lock failed, err: ' + err);
                }
            });
        }
    }
}

isHolding⁹⁺

isHolding(): boolean

API description: Checks whether this running lock is being held.

System capability: SystemCapability.PowerManager.PowerManager.Core

Returns

Type	Description
boolean	The value true indicates that the RunningLock object is held; and the value false indicates that the RunningLock object is released.

Example

// RunningLockTest.ets
class RunningLockTest {
    public static recordLock: runningLock.RunningLock;

    public static isHoldingRunningLock(): void {
        if (RunningLockTest.recordLock) {
            let isHolding = RunningLockTest.recordLock.isHolding();
            console.info('check running lock holding status: ' + isHolding);
        } else {
            runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
                if (typeof err === 'undefined') {
                    console.info('create running lock: ' + lock);
                    RunningLockTest.recordLock = lock;
                    let isHolding = lock.isHolding();
                    console.info('check running lock holding status: ' + isHolding);
                } else {
                    console.error('create running lock failed, err: ' + err);
                }
            });
        }
    }
}

lock^(deprecated)

lock(timeout: number): void

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use RunningLock.hold instead.

API description: Locks a running lock.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Parameters

Name	Type	Mandatory	Description
timeout	number	Yes	Duration for locking and holding the RunningLock object, in ms.

Example

runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
.then((lock: runningLock.RunningLock) => {
    lock.lock(500);
    console.info('create running lock and lock success');
})
.catch((err: Error) => {
    console.error('create running lock failed, err: ' + err);
});

unlock^(deprecated)

unlock(): void

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use RunningLock.unhold instead.

API description: Releases this running lock.

System capability: SystemCapability.PowerManager.PowerManager.Core

Required permission: ohos.permission.RUNNING_LOCK

Example

runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
.then((lock: runningLock.RunningLock) => {
    lock.unlock();
    console.info('create running lock and unlock success');
})
.catch((err: Error) => {
    console.error('create running lock failed, err: ' + err);
});

isUsed^(deprecated)

isUsed(): boolean

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use RunningLock.isHolding instead.

API description: Checks whether this running lock is used.

System capability: SystemCapability.PowerManager.PowerManager.Core

Returns

Type	Description
boolean	The value true indicates that the RunningLock object is held; and the value false indicates that the RunningLock object is released.

Example

runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
.then((lock: runningLock.RunningLock) => {
    let isUsed = lock.isUsed();
    console.info('check running lock used status: ' + isUsed);
})
.catch((err: Error) => {
    console.error('check running lock used status failed, err: ' + err);
});

RunningLockType

Enumerates the types of RunningLock objects.

System capability: SystemCapability.PowerManager.PowerManager.Core

Name	Value	Description
BACKGROUND^(deprecated)	1	A lock that prevents the system from entering sleep mode when the screen is off. NOTE This parameter is supported since API version 7 and deprecated since API version 10.
PROXIMITY_SCREEN_CONTROL	2	A lock that enables the proximity sensor and turns on or off the screen based on the distance between the sensor and the obstacle.
BACKGROUND_USER_IDLE²³⁺	129	A background lock that prevents the system from automatically entering sleep mode when the user is inactive for a period of time. Note: This lock cannot prevent the system from entering the forced sleep state in scenarios such as closing the PC lid. The user must listen for the COMMON_EVENT_ENTER_FORCE_SLEEP event and release this lock after receiving the event. The behavior of this lock varies with devices. For details about how to use this type of lock, see Preventing the Idle System from Entering Sleep Mode.

@ohos.runningLock (RunningLock)

Modules to Import

runningLock.isSupported9+

runningLock.create9+

runningLock.create9+

runningLock.isRunningLockTypeSupported(deprecated)

runningLock.isRunningLockTypeSupported(deprecated)

runningLock.createRunningLock(deprecated)

runningLock.createRunningLock(deprecated)

RunningLock

hold9+

unhold9+

isHolding9+

lock(deprecated)

unlock(deprecated)

isUsed(deprecated)

RunningLockType

runningLock.isSupported⁹⁺

runningLock.create⁹⁺

runningLock.create⁹⁺

runningLock.isRunningLockTypeSupported^(deprecated)

runningLock.isRunningLockTypeSupported^(deprecated)

runningLock.createRunningLock^(deprecated)

runningLock.createRunningLock^(deprecated)

hold⁹⁺

unhold⁹⁺

isHolding⁹⁺

lock^(deprecated)

unlock^(deprecated)

isUsed^(deprecated)