1/* 2 * Copyright (c) 2022 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 16import { AsyncCallback , Callback} from './basic'; 17import { WantAgent } from "./@ohos.wantAgent"; 18import Context from './application/BaseContext'; 19 20/** 21 * Manages background tasks. 22 * 23 * @namespace backgroundTaskManager 24 * @since 9 25 */ 26declare namespace backgroundTaskManager { 27 /** 28 * The info of delay suspend. 29 * 30 * @interface DelaySuspendInfo 31 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 32 * @since 9 33 */ 34 interface DelaySuspendInfo { 35 /** 36 * The unique identifier of the delay request. 37 */ 38 requestId: number; 39 /** 40 * The actual delay duration (ms). 41 */ 42 actualDelayTime: number; 43 } 44 45 /** 46 * Cancels delayed transition to the suspended state. 47 * 48 * @param { number } requestId - The identifier of the delay request. 49 * @throws { BusinessError } 401 - Parameter error. 50 * @throws { BusinessError } 9800001 - Memory operation failed. 51 * @throws { BusinessError } 9800002 - Parcel operation failed. 52 * @throws { BusinessError } 9800003 - Inner transact failed. 53 * @throws { BusinessError } 9800004 - System service operation failed. 54 * @throws { BusinessError } 9900001 - Caller information verification failed. 55 * @throws { BusinessError } 9900002 - Background task verification failed. 56 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 57 * @since 9 58 */ 59 function cancelSuspendDelay(requestId: number): void; 60 61 /** 62 * Obtains the remaining time before an application enters the suspended state. 63 * 64 * @param { number } requestId - The identifier of the delay request. 65 * @param { AsyncCallback<number> } callback - The callback of the remaining delay time. 66 * @throws { BusinessError } 401 - Parameter error. 67 * @throws { BusinessError } 9800001 - Memory operation failed. 68 * @throws { BusinessError } 9800002 - Parcel operation failed. 69 * @throws { BusinessError } 9800003 - Inner transact failed. 70 * @throws { BusinessError } 9800004 - System service operation failed. 71 * @throws { BusinessError } 9900001 - Caller information verification failed. 72 * @throws { BusinessError } 9900002 - Background task verification failed. 73 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 74 * @since 9 75 */ 76 function getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void; 77 78 /** 79 * Obtains the remaining time before an application enters the suspended state. 80 * 81 * @since 9 82 * @param { number } requestId - The identifier of the delay request. 83 * @returns { Promise<number> } The promise returns the remaining delay time. 84 * @throws { BusinessError } 401 - Parameter error. 85 * @throws { BusinessError } 9800001 - Memory operation failed. 86 * @throws { BusinessError } 9800002 - Parcel operation failed. 87 * @throws { BusinessError } 9800003 - Inner transact failed. 88 * @throws { BusinessError } 9800004 - System service operation failed. 89 * @throws { BusinessError } 9900001 - Caller information verification failed. 90 * @throws { BusinessError } 9900002 - Background task verification failed. 91 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 92 */ 93 function getRemainingDelayTime(requestId: number): Promise<number>; 94 95 /** 96 * Requests delayed transition to the suspended state. 97 * 98 * @param { string } reason - Indicates the reason for delayed transition to the suspended state. 99 * @param { Callback<void> } callback - The callback delay time expired. 100 * @returns { DelaySuspendInfo } Info of delay request. 101 * @throws { BusinessError } 401 - Parameter error. 102 * @throws { BusinessError } 9800001 - Memory operation failed. 103 * @throws { BusinessError } 9800002 - Parcel operation failed. 104 * @throws { BusinessError } 9800003 - Inner transact failed. 105 * @throws { BusinessError } 9800004 - System service operation failed. 106 * @throws { BusinessError } 9900001 - Caller information verification failed. 107 * @throws { BusinessError } 9900002 - Background task verification failed. 108 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 109 * @since 9 110 */ 111 function requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo; 112 113 /** 114 * Service ability uses this method to request start running in background. 115 * <p> System will publish a notification related to the this service. </p> 116 * 117 * @permission ohos.permission.KEEP_BACKGROUND_RUNNING 118 * @param { Context } context - App running context. 119 * @param { BackgroundMode } bgMode - Indicates which background mode to request. 120 * @param { WantAgent } wantAgent - Indicates which ability to start when user click the notification bar. 121 * @param { AsyncCallback<void> } callback - The callback of the function. 122 * @throws { BusinessError } 201 - Permission denied. 123 * @throws { BusinessError } 202 - Not System App. 124 * @throws { BusinessError } 401 - Parameter error. 125 * @throws { BusinessError } 9800001 - Memory operation failed. 126 * @throws { BusinessError } 9800002 - Parcel operation failed. 127 * @throws { BusinessError } 9800003 - Inner transact failed. 128 * @throws { BusinessError } 9800004 - System service operation failed. 129 * @throws { BusinessError } 9800005 - Background task verification failed. 130 * @throws { BusinessError } 9800006 - Notification verification failed. 131 * @throws { BusinessError } 9800007 - Task storage failed. 132 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 133 * @since 9 134 */ 135 function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void; 136 137 /** 138 * Service ability uses this method to request start running in background. 139 * <p> System will publish a notification related to the this service. </p> 140 * 141 * @permission ohos.permission.KEEP_BACKGROUND_RUNNING 142 * @param { Context } context - App running context. 143 * @param { BackgroundMode } bgMode - Indicates which background mode to request. 144 * @param { WantAgent } wantAgent - Indicates which ability to start when user click the notification bar. 145 * @returns { Promise<void> } The promise returned by the function. 146 * @throws { BusinessError } 201 - Permission denied. 147 * @throws { BusinessError } 202 - Not System App. 148 * @throws { BusinessError } 401 - Parameter error. 149 * @throws { BusinessError } 9800001 - Memory operation failed. 150 * @throws { BusinessError } 9800002 - Parcel operation failed. 151 * @throws { BusinessError } 9800003 - Inner transact failed. 152 * @throws { BusinessError } 9800004 - System service operation failed. 153 * @throws { BusinessError } 9800005 - Background task verification failed. 154 * @throws { BusinessError } 9800006 - Notification verification failed. 155 * @throws { BusinessError } 9800007 - Task storage failed. 156 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 157 * @since 9 158 */ 159 function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void>; 160 161 /** 162 * Service ability uses this method to request stop running in background. 163 * 164 * @param { Context } context - App running context. 165 * @param { AsyncCallback<void> } callback - The callback of the function. 166 * @throws { BusinessError } 201 - Permission denied. 167 * @throws { BusinessError } 401 - Parameter error. 168 * @throws { BusinessError } 9800001 - Memory operation failed. 169 * @throws { BusinessError } 9800002 - Parcel operation failed. 170 * @throws { BusinessError } 9800003 - Inner transact failed. 171 * @throws { BusinessError } 9800004 - System service operation failed. 172 * @throws { BusinessError } 9800005 - Background task verification failed. 173 * @throws { BusinessError } 9800006 - Notification verification failed. 174 * @throws { BusinessError } 9800007 - Task storage failed. 175 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 176 * @since 9 177 */ 178 function stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void; 179 180 /** 181 * Service ability uses this method to request stop running in background. 182 * 183 * @param { Context } context - App running context. 184 * @returns { Promise<void> } The promise returned by the function. 185 * @throws { BusinessError } 201 - Permission denied. 186 * @throws { BusinessError } 401 - Parameter error. 187 * @throws { BusinessError } 9800001 - Memory operation failed. 188 * @throws { BusinessError } 9800002 - Parcel operation failed. 189 * @throws { BusinessError } 9800003 - Inner transact failed. 190 * @throws { BusinessError } 9800004 - System service operation failed. 191 * @throws { BusinessError } 9800005 - Background task verification failed. 192 * @throws { BusinessError } 9800006 - Notification verification failed. 193 * @throws { BusinessError } 9800007 - Task storage failed. 194 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 195 * @since 9 196 */ 197 function stopBackgroundRunning(context: Context): Promise<void>; 198 199 /** 200 * Apply or unapply efficiency resources. 201 * 202 * @throws { BusinessError } 201 - Permission denied. 203 * @throws { BusinessError } 202 - Not System App. 204 * @throws { BusinessError } 401 - Parameter error. 205 * @throws { BusinessError } 9800001 - Memory operation failed. 206 * @throws { BusinessError } 9800002 - Parcel operation failed. 207 * @throws { BusinessError } 9800003 - Inner transact failed. 208 * @throws { BusinessError } 9800004 - System service operation failed. 209 * @throws { BusinessError } 18700001 - Caller information verification failed. 210 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 211 * @systemapi Hide this for inner system use. 212 * @since 9 213 */ 214 function applyEfficiencyResources(request: EfficiencyResourcesRequest): void; 215 216 /** 217 * Reset all efficiency resources apply. 218 * 219 * @throws { BusinessError } 201 - Permission denied. 220 * @throws { BusinessError } 202 - Not System App. 221 * @throws { BusinessError } 401 - Parameter error. 222 * @throws { BusinessError } 9800001 - Memory operation failed. 223 * @throws { BusinessError } 9800002 - Parcel operation failed. 224 * @throws { BusinessError } 9800003 - Inner transact failed. 225 * @throws { BusinessError } 9800004 - System service operation failed. 226 * @throws { BusinessError } 18700001 - Caller information verification failed. 227 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 228 * @systemapi Hide this for inner system use. 229 * @since 9 230 */ 231 function resetAllEfficiencyResources(): void; 232 233 /** 234 * Supported background mode. 235 * 236 * @enum { number } 237 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 238 * @since 9 239 */ 240 export enum BackgroundMode { 241 /** 242 * data transfer mode 243 * 244 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 245 * @since 9 246 */ 247 DATA_TRANSFER = 1, 248 249 /** 250 * audio playback mode 251 * 252 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 253 * @since 9 254 */ 255 AUDIO_PLAYBACK = 2, 256 257 /** 258 * audio recording mode 259 * 260 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 261 * @since 9 262 */ 263 AUDIO_RECORDING = 3, 264 265 /** 266 * location mode 267 * 268 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 269 * @since 9 270 */ 271 LOCATION = 4, 272 273 /** 274 * bluetooth interaction mode 275 * 276 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 277 * @since 9 278 */ 279 BLUETOOTH_INTERACTION = 5, 280 281 /** 282 * multi-device connection mode 283 * 284 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 285 * @since 9 286 */ 287 MULTI_DEVICE_CONNECTION = 6, 288 289 /** 290 * wifi interaction mode 291 * 292 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 293 * @systemapi Hide this for inner system use. 294 * @since 9 295 */ 296 WIFI_INTERACTION = 7, 297 298 /** 299 * Voice over Internet Phone mode 300 * 301 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 302 * @systemapi Hide this for inner system use. 303 * @since 9 304 */ 305 VOIP = 8, 306 307 /** 308 * background continuous calculate mode, for example 3D render. 309 * only supported in particular device 310 * 311 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 312 * @since 9 313 */ 314 TASK_KEEPING = 9, 315 } 316 317 /** 318 * The type of resource. 319 * 320 * @enum { number } 321 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 322 * @systemapi Hide this for inner system use. 323 * @since 9 324 */ 325 export enum ResourceType { 326 /** 327 * The cpu resource for not being suspended. 328 */ 329 CPU = 1, 330 331 /** 332 * The resource for not being proxyed common_event. 333 */ 334 COMMON_EVENT = 1 << 1, 335 336 /** 337 * The resource for not being proxyed timer. 338 */ 339 TIMER = 1 << 2, 340 341 /** 342 * The resource for not being proxyed workscheduler. 343 */ 344 WORK_SCHEDULER = 1 << 3, 345 346 /** 347 * The resource for not being proxyed bluetooth. 348 */ 349 BLUETOOTH = 1 << 4, 350 351 /** 352 * The resource for not being proxyed gps. 353 */ 354 GPS = 1 << 5, 355 356 /** 357 * The resource for not being proxyed audio. 358 */ 359 AUDIO = 1 << 6 360 } 361 362 /** 363 * The request of efficiency resources. 364 * 365 * @interface EfficiencyResourcesRequest 366 * @syscap SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 367 * @systemapi Hide this for inner system use. 368 * @since 9 369 */ 370 export interface EfficiencyResourcesRequest { 371 /** 372 * The set of resource types that app wants to apply. 373 */ 374 resourceTypes: number; 375 376 /** 377 * True if the app begin to use, else false. 378 */ 379 isApply: boolean; 380 381 /** 382 * The duration that the resource can be used most. 383 */ 384 timeOut: number; 385 386 /** 387 * True if the apply action is persist, else false. Default value is false. 388 */ 389 isPersist?: boolean; 390 391 /** 392 * True if apply action is for process, false is for package. Default value is false. 393 */ 394 isProcess?: boolean; 395 396 /** 397 * The apply reason. 398 */ 399 reason: string; 400 } 401} 402 403export default backgroundTaskManager; 404