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