1/* 2 * Copyright (c) 2021-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit BasicServicesKit 19 */ 20 21import { AsyncCallback, BusinessError } from './@ohos.base'; 22 23/** 24 * Provides a mechanism to prevent the system from hibernating so that the applications can run in the background or 25 * when the screen is off. 26 * <p>{@link create} can be called to obtain a {@link RunningLock}. 27 * <p>{@link hold} can be called to set the lock duration, during which the system will not hibernate. After the 28 * lock duration times out, the lock is automatically released and the system hibernates if no other 29 * {@link RunningLock} is set. 30 * 31 * @namespace runningLock 32 * @syscap SystemCapability.PowerManager.PowerManager.Core 33 * @since arkts {'1.1':'7', '1.2':'20'} 34 * @arkts 1.1&1.2 35 */ 36declare namespace runningLock { 37 38 /** 39 * Provides a mechanism to prevent the system from hibernating so that the applications can run in the background or 40 * when the screen is off. 41 * @syscap SystemCapability.PowerManager.PowerManager.Core 42 * @since arkts {'1.1':'7', '1.2':'20'} 43 * @arkts 1.1&1.2 44 */ 45 class RunningLock { 46 /** 47 * Prevents the system from hibernating and sets the lock duration. 48 * This method requires the ohos.permission.RUNNING_LOCK permission. 49 * 50 * @permission ohos.permission.RUNNING_LOCK 51 * @param { number } timeout Indicates the lock duration (ms). After the lock duration times out, the lock is automatically 52 * released and the system hibernates if no other {@link RunningLock} is set. 53 * @syscap SystemCapability.PowerManager.PowerManager.Core 54 * @since 7 55 * @deprecated since 9 56 * @useinstead RunningLock#hold 57 */ 58 lock(timeout: number): void; 59 60 /** 61 * Prevents the system from hibernating and sets the lock duration. 62 * This method requires the ohos.permission.RUNNING_LOCK permission. 63 * 64 * @permission ohos.permission.RUNNING_LOCK 65 * @param { int } timeout Indicates the lock duration (ms). After the lock duration times out, 66 * the lock is automatically released and the system hibernates if no other {@link RunningLock} is set. 67 * timeout parameter must be of type int. 68 * @throws { BusinessError } 201 – If the permission is denied. 69 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Incorrect parameter types; 70 * @syscap SystemCapability.PowerManager.PowerManager.Core 71 * @since arkts {'1.1':'9', '1.2':'20'} 72 * @arkts 1.1&1.2 73 */ 74 hold(timeout: int): void; 75 76 /** 77 * Checks whether a lock is held or in use. 78 * 79 * @returns { boolean } Returns true if the lock is held or in use; returns false if the lock has been released. 80 * @syscap SystemCapability.PowerManager.PowerManager.Core 81 * @since 7 82 * @deprecated since 9 83 * @useinstead RunningLock#isHolding 84 */ 85 isUsed(): boolean; 86 87 /** 88 * Checks whether a lock is held or in use. 89 * 90 * @returns { boolean } Returns true if the lock is held or in use; returns false if the lock has been released. 91 * @syscap SystemCapability.PowerManager.PowerManager.Core 92 * @since arkts {'1.1':'9', '1.2':'20'} 93 * @arkts 1.1&1.2 94 */ 95 isHolding(): boolean; 96 97 /** 98 * Release the {@link RunningLock} that prevents the system from hibernating. 99 * This method requires the ohos.permission.RUNNING_LOCK permission. 100 * 101 * @permission ohos.permission.RUNNING_LOCK 102 * @syscap SystemCapability.PowerManager.PowerManager.Core 103 * @since 7 104 * @deprecated since 9 105 * @useinstead RunningLock#unhold 106 */ 107 unlock(): void; 108 109 /** 110 * Release the {@link RunningLock} that prevents the system from hibernating. 111 * This method requires the ohos.permission.RUNNING_LOCK permission. 112 * 113 * @permission ohos.permission.RUNNING_LOCK 114 * @throws { BusinessError } 201 – If the permission is denied. 115 * @syscap SystemCapability.PowerManager.PowerManager.Core 116 * @since arkts {'1.1':'9', '1.2':'20'} 117 * @arkts 1.1&1.2 118 */ 119 unhold(): void; 120 } 121 122 /** 123 * Enumerates the {@link RunningLock} types. 124 * <p>Two {@link RunningLock} types are available: {@link BACKGROUND}, and {@link PROXIMITY_SCREEN_CONTROL}. 125 * {@link BACKGROUND} ensures that applications can run in the background. 126 * {@link PROXIMITY_SCREEN_CONTROL} determines whether to turn on or off the screen based on the proximity sensor. 127 * 128 * @enum { int } 129 * @syscap SystemCapability.PowerManager.PowerManager.Core 130 * @since arkts {'1.1':'7', '1.2':'20'} 131 * @arkts 1.1&1.2 132 */ 133 export enum RunningLockType { 134 /** 135 * Indicates the lock that prevents the system from hibernating. 136 * 137 * @syscap SystemCapability.PowerManager.PowerManager.Core 138 * @since 7 139 * @deprecated since 10 140 */ 141 BACKGROUND = 1, 142 /** 143 * Indicates the lock that determines whether to turn on or off the screen based on the proximity sensor. 144 * For example, during a call, if the proximity sensor detects that the device is moving close to 145 * the user's ear, the screen turns off; if the proximity sensor detects that the device is moving away 146 * from the user's ear, the screen turns on. 147 * 148 * @syscap SystemCapability.PowerManager.PowerManager.Core 149 * @since arkts {'1.1':'7', '1.2':'20'} 150 * @arkts 1.1&1.2 151 */ 152 PROXIMITY_SCREEN_CONTROL = 2 153 } 154 155 /** 156 * Checks whether the specified {@link RunningLockType} is supported. 157 * 158 * @param { RunningLockType } type Indicates the specified {@link RunningLockType}. 159 * @param { AsyncCallback<boolean> } callback Indicates the callback function contains the result whether the specified 160 * {@link RunningLockType} is supported. 161 * @syscap SystemCapability.PowerManager.PowerManager.Core 162 * @since 7 163 * @deprecated since 9 164 * @useinstead RunningLock#isSupported 165 */ 166 function isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback<boolean>): void; 167 168 /** 169 * Checks whether the specified {@link RunningLockType} is supported. 170 * 171 * @param { RunningLockType } type Indicates the specified {@link RunningLockType}. 172 * @returns { Promise<boolean> } Returns true if the specified {@link RunningLockType} is supported; 173 * returns false otherwise. 174 * @syscap SystemCapability.PowerManager.PowerManager.Core 175 * @since 7 176 * @deprecated since 9 177 * @useinstead RunningLock#isSupported 178 */ 179 function isRunningLockTypeSupported(type: RunningLockType): Promise<boolean>; 180 181 /** 182 * Checks whether the specified {@link RunningLockType} is supported. 183 * 184 * @param { RunningLockType } type Indicates the specified {@link RunningLockType}. 185 * the RunningLockType type is an enumeration class. 186 * @returns { boolean } Whether the specified {@link RunningLockType} is supported. 187 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Incorrect parameter types; 188 * 2. Parameter verification failed. 189 * @syscap SystemCapability.PowerManager.PowerManager.Core 190 * @since arkts {'1.1':'9', '1.2':'20'} 191 * @arkts 1.1&1.2 192 */ 193 function isSupported(type: RunningLockType): boolean; 194 195 /** 196 * Creates a {@link RunningLock} object. 197 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 198 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 199 * 200 * @permission ohos.permission.RUNNING_LOCK 201 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or class name and 202 * a suffix. 203 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 204 * @param { AsyncCallback<RunningLock> } callback Indicates the callback contains the {@link RunningLock} object. 205 * @syscap SystemCapability.PowerManager.PowerManager.Core 206 * @since 7 207 * @deprecated since 9 208 * @useinstead RunningLock#create 209 */ 210 function createRunningLock(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void; 211 212 /** 213 * Creates a {@link RunningLock} object. 214 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 215 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 216 * 217 * @permission ohos.permission.RUNNING_LOCK 218 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or class name and 219 * a suffix. 220 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 221 * @returns { Promise<RunningLock> } Returns the {@link RunningLock} object. 222 * @syscap SystemCapability.PowerManager.PowerManager.Core 223 * @since 7 224 * @deprecated since 9 225 * @useinstead RunningLock#create 226 */ 227 function createRunningLock(name: string, type: RunningLockType): Promise<RunningLock>; 228 229 /** 230 * Creates a {@link RunningLock} object. 231 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 232 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 233 * 234 * @permission ohos.permission.RUNNING_LOCK 235 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or 236 * class name and a suffix. 237 * name parameter must be of type string. 238 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 239 * the RunningLockType type is an enumeration class. 240 * @param { AsyncCallback<RunningLock> } callback Indicates the callback of {@link RunningLock} object. 241 * AsyncCallback encapsulates a class of RunningLock type 242 * @throws { BusinessError } 201 – If the permission is denied. 243 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Parameter verification failed. 244 * @syscap SystemCapability.PowerManager.PowerManager.Core 245 * @since arkts {'1.1':'9', '1.2':'20'} 246 * @arkts 1.1&1.2 247 */ 248 function create(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void; 249 250 /** 251 * Creates a {@link RunningLock} object. 252 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 253 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 254 * 255 * @permission ohos.permission.RUNNING_LOCK 256 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or 257 * class name and a suffix. 258 * name parameter must be of type string. 259 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 260 * the RunningLockType type is an enumeration class. 261 * @returns { Promise<RunningLock> } The {@link RunningLock} object. 262 * @throws { BusinessError } 201 – If the permission is denied. 263 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Parameter verification failed. 264 * @syscap SystemCapability.PowerManager.PowerManager.Core 265 * @since arkts {'1.1':'9', '1.2':'20'} 266 * @arkts 1.1&1.2 267 */ 268 function create(name: string, type: RunningLockType): Promise<RunningLock>; 269} 270export default runningLock;