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 7 34 */ 35declare namespace runningLock { 36 37 /** 38 * Provides a mechanism to prevent the system from hibernating so that the applications can run in the background or 39 * when the screen is off. 40 * @syscap SystemCapability.PowerManager.PowerManager.Core 41 * @since 7 42 */ 43 class RunningLock { 44 /** 45 * Prevents the system from hibernating and sets the lock duration. 46 * This method requires the ohos.permission.RUNNING_LOCK permission. 47 * 48 * @permission ohos.permission.RUNNING_LOCK 49 * @param { number } timeout Indicates the lock duration (ms). After the lock duration times out, the lock is automatically 50 * released and the system hibernates if no other {@link RunningLock} is set. 51 * @syscap SystemCapability.PowerManager.PowerManager.Core 52 * @since 7 53 * @deprecated since 9 54 * @useinstead RunningLock#hold 55 */ 56 lock(timeout: number): void; 57 58 /** 59 * Prevents the system from hibernating and sets the lock duration. 60 * This method requires the ohos.permission.RUNNING_LOCK permission. 61 * 62 * @permission ohos.permission.RUNNING_LOCK 63 * @param { number } timeout Indicates the lock duration (ms). After the lock duration times out, 64 * the lock is automatically released and the system hibernates if no other {@link RunningLock} is set. 65 * timeout parameter must be of type number. 66 * @throws { BusinessError } 201 – If the permission is denied. 67 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Incorrect parameter types; 68 * @throws { BusinessError } 4900101 - Failed to connect to the service. 69 * @syscap SystemCapability.PowerManager.PowerManager.Core 70 * @since 9 71 */ 72 hold(timeout: number): void; 73 74 /** 75 * Checks whether a lock is held or in use. 76 * 77 * @returns { boolean } Returns true if the lock is held or in use; returns false if the lock has been released. 78 * @syscap SystemCapability.PowerManager.PowerManager.Core 79 * @since 7 80 * @deprecated since 9 81 * @useinstead RunningLock#isHolding 82 */ 83 isUsed(): boolean; 84 85 /** 86 * Checks whether a lock is held or in use. 87 * 88 * @returns { boolean } Returns true if the lock is held or in use; returns false if the lock has been released. 89 * @throws { BusinessError } 4900101 - Failed to connect to the service. 90 * @syscap SystemCapability.PowerManager.PowerManager.Core 91 * @since 9 92 */ 93 isHolding(): boolean; 94 95 /** 96 * Release the {@link RunningLock} that prevents the system from hibernating. 97 * This method requires the ohos.permission.RUNNING_LOCK permission. 98 * 99 * @permission ohos.permission.RUNNING_LOCK 100 * @syscap SystemCapability.PowerManager.PowerManager.Core 101 * @since 7 102 * @deprecated since 9 103 * @useinstead RunningLock#unhold 104 */ 105 unlock(): void; 106 107 /** 108 * Release the {@link RunningLock} that prevents the system from hibernating. 109 * This method requires the ohos.permission.RUNNING_LOCK permission. 110 * 111 * @permission ohos.permission.RUNNING_LOCK 112 * @throws { BusinessError } 201 – If the permission is denied. 113 * @throws { BusinessError } 4900101 - Failed to connect to the service. 114 * @syscap SystemCapability.PowerManager.PowerManager.Core 115 * @since 9 116 */ 117 unhold(): void; 118 } 119 120 /** 121 * Enumerates the {@link RunningLock} types. 122 * <p>Two {@link RunningLock} types are available: {@link BACKGROUND}, and {@link PROXIMITY_SCREEN_CONTROL}. 123 * {@link BACKGROUND} ensures that applications can run in the background. 124 * {@link PROXIMITY_SCREEN_CONTROL} determines whether to turn on or off the screen based on the proximity sensor. 125 * 126 * @enum { number } 127 * @syscap SystemCapability.PowerManager.PowerManager.Core 128 * @since 7 129 */ 130 export enum RunningLockType { 131 /** 132 * Indicates the lock that prevents the system from hibernating. 133 * 134 * @syscap SystemCapability.PowerManager.PowerManager.Core 135 * @since 7 136 * @deprecated since 10 137 */ 138 BACKGROUND = 1, 139 /** 140 * Indicates the lock that determines whether to turn on or off the screen based on the proximity sensor. 141 * For example, during a call, if the proximity sensor detects that the device is moving close to 142 * the user's ear, the screen turns off; if the proximity sensor detects that the device is moving away 143 * from the user's ear, the screen turns on. 144 * 145 * @syscap SystemCapability.PowerManager.PowerManager.Core 146 * @since 7 147 */ 148 PROXIMITY_SCREEN_CONTROL 149 } 150 151 /** 152 * Checks whether the specified {@link RunningLockType} is supported. 153 * 154 * @param { RunningLockType } type Indicates the specified {@link RunningLockType}. 155 * @param { AsyncCallback<boolean> } callback Indicates the callback function contains the result whether the specified 156 * {@link RunningLockType} is supported. 157 * @syscap SystemCapability.PowerManager.PowerManager.Core 158 * @since 7 159 * @deprecated since 9 160 * @useinstead RunningLock#isSupported 161 */ 162 function isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback<boolean>): void; 163 164 /** 165 * Checks whether the specified {@link RunningLockType} is supported. 166 * 167 * @param { RunningLockType } type Indicates the specified {@link RunningLockType}. 168 * @returns { Promise<boolean> } Returns true if the specified {@link RunningLockType} is supported; 169 * returns false otherwise. 170 * @syscap SystemCapability.PowerManager.PowerManager.Core 171 * @since 7 172 * @deprecated since 9 173 * @useinstead RunningLock#isSupported 174 */ 175 function isRunningLockTypeSupported(type: RunningLockType): Promise<boolean>; 176 177 /** 178 * Checks whether the specified {@link RunningLockType} is supported. 179 * 180 * @param { RunningLockType } type Indicates the specified {@link RunningLockType}. 181 * the RunningLockType type is an enumeration class. 182 * @returns { boolean } Whether the specified {@link RunningLockType} is supported. 183 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Incorrect parameter types; 184 * 2. Parameter verification failed. 185 * @throws { BusinessError } 4900101 - Failed to connect to the service. 186 * @syscap SystemCapability.PowerManager.PowerManager.Core 187 * @since 9 188 */ 189 function isSupported(type: RunningLockType): boolean; 190 191 /** 192 * Creates a {@link RunningLock} object. 193 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 194 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 195 * 196 * @permission ohos.permission.RUNNING_LOCK 197 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or class name and 198 * a suffix. 199 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 200 * @param { AsyncCallback<RunningLock> } callback Indicates the callback contains the {@link RunningLock} object. 201 * @syscap SystemCapability.PowerManager.PowerManager.Core 202 * @since 7 203 * @deprecated since 9 204 * @useinstead RunningLock#create 205 */ 206 function createRunningLock(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void; 207 208 /** 209 * Creates a {@link RunningLock} object. 210 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 211 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 212 * 213 * @permission ohos.permission.RUNNING_LOCK 214 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or class name and 215 * a suffix. 216 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 217 * @returns { Promise<RunningLock> } Returns the {@link RunningLock} object. 218 * @syscap SystemCapability.PowerManager.PowerManager.Core 219 * @since 7 220 * @deprecated since 9 221 * @useinstead RunningLock#create 222 */ 223 function createRunningLock(name: string, type: RunningLockType): Promise<RunningLock>; 224 225 /** 226 * Creates a {@link RunningLock} object. 227 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 228 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 229 * 230 * @permission ohos.permission.RUNNING_LOCK 231 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or 232 * class name and a suffix. 233 * name parameter must be of type string. 234 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 235 * the RunningLockType type is an enumeration class. 236 * @param { AsyncCallback<RunningLock> } callback Indicates the callback of {@link RunningLock} object. 237 * AsyncCallback encapsulates a class of RunningLock type 238 * @throws { BusinessError } 201 – If the permission is denied. 239 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Parameter verification failed. 240 * @syscap SystemCapability.PowerManager.PowerManager.Core 241 * @since 9 242 */ 243 function create(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void; 244 245 /** 246 * Creates a {@link RunningLock} object. 247 * <p>This method requires the ohos.permission.RUNNING_LOCK permission. 248 * <p>The {@link RunningLock} object can be used to perform a lock operation to prevent the system from hibernating. 249 * 250 * @permission ohos.permission.RUNNING_LOCK 251 * @param { string } name Indicates the {@link RunningLock} name. A recommended name consists of the package or 252 * class name and a suffix. 253 * name parameter must be of type string. 254 * @param { RunningLockType } type Indicates the {@link RunningLockType}. 255 * the RunningLockType type is an enumeration class. 256 * @returns { Promise<RunningLock> } The {@link RunningLock} object. 257 * @throws { BusinessError } 201 – If the permission is denied. 258 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Parameter verification failed. 259 * @syscap SystemCapability.PowerManager.PowerManager.Core 260 * @since 9 261 */ 262 function create(name: string, type: RunningLockType): Promise<RunningLock>; 263} 264export default runningLock; 265