1# @ohos.app.ability.autoStartupManager (autoStartupManager) (System API) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @zhu-feimo; @Luobniz21--> 6<!--Designer: @ccllee1--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10The autoStartupManager module provides APIs for listening for auto-startup status changes of application components and setting application components to automatically start upon system boot. 11 12> **NOTE** 13> 14> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15> 16> The APIs of this module can be used only in the stage model. 17> 18> The APIs provided by this module are system APIs. 19 20## Modules to Import 21 22```ts 23import { autoStartupManager } from '@kit.AbilityKit'; 24``` 25 26## on 27 28on(type: 'systemAutoStartup', callback: AutoStartupCallback): void 29 30Registers a callback to listen for auto-startup status changes of an application component. 31 32**Required permissions**: ohos.permission.MANAGE_APP_BOOT 33 34**System capability**: SystemCapability.Ability.AbilityRuntime.Core 35 36**Parameters** 37 38| Name | Type | Mandatory | Description | 39| --------- | ---------------------------------------- | ---- | -------------- | 40| type | string | Yes | Event type. The value is fixed at **systemAutoStartup**, which can be called only by system applications.| 41| callback | [AutoStartupCallback](js-apis-inner-application-autoStartupCallback-sys.md) | Yes | Callback used for registration. | 42 43**Error codes** 44 45For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 46 47| ID| Error Message| 48| -------- | -------------------------------- | 49| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 50| 202 | Permission denied, non-system app called system api. | 51| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 52| 16000050 | Internal error. | 53 54**Example** 55 56```ts 57import { autoStartupManager, common } from '@kit.AbilityKit'; 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60try { 61 autoStartupManager.on('systemAutoStartup', { 62 onAutoStartupOn(data: common.AutoStartupInfo) { 63 console.info(`autostartupmanager onAutoStartupOn, data: ${JSON.stringify(data)}.`); 64 }, 65 onAutoStartupOff(data: common.AutoStartupInfo) { 66 console.info(`autostartupmanager onAutoStartupOff, data: ${JSON.stringify(data)}.`); 67 } 68 }); 69} catch (err) { 70 let code = (err as BusinessError).code; 71 let msg = (err as BusinessError).message; 72 console.error(`autostartupmanager on success, err code: ${code}, err msg: ${msg}.`); 73} 74``` 75 76## off 77 78off(type: 'systemAutoStartup', callback?: AutoStartupCallback): void 79 80Unregisters the callback used to listen for auto-startup status changes of an application component. 81 82**Required permissions**: ohos.permission.MANAGE_APP_BOOT 83 84**System capability**: SystemCapability.Ability.AbilityRuntime.Core 85 86**Parameters** 87 88| Name | Type | Mandatory | Description | 89| --------- | ---------------------------------------- | ---- | -------------- | 90| type | string | Yes | Event type. The value is fixed at **systemAutoStartup**, which can be called only by system applications.| 91| callback | [AutoStartupCallback](js-apis-inner-application-autoStartupCallback-sys.md) | No| Callback used for unregistration.| 92 93**Error codes** 94 95For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 96 97| ID| Error Message| 98| -------- | -------------------------------- | 99| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 100| 202 | Permission denied, non-system app called system api. | 101| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 102| 16000050 | Internal error. | 103 104**Example** 105 106```ts 107import { autoStartupManager, common } from '@kit.AbilityKit'; 108import { BusinessError } from '@kit.BasicServicesKit'; 109 110try { 111 autoStartupManager.off('systemAutoStartup', { 112 onAutoStartupOn(data: common.AutoStartupInfo) { 113 console.info(`autostartupmanager onAutoStartupOn, data: ${JSON.stringify(data)}.`); 114 }, 115 onAutoStartupOff(data: common.AutoStartupInfo) { 116 console.info(`autostartupmanager onAutoStartupOff, data: ${JSON.stringify(data)}.`); 117 } 118 }); 119} catch (err) { 120 let code = (err as BusinessError).code; 121 let msg = (err as BusinessError).message; 122 console.error(`autostartupmanager on success, err code: ${code}, err msg: ${msg}.`); 123} 124``` 125 126## setApplicationAutoStartup 127 128setApplicationAutoStartup(info: AutoStartupInfo, callback: AsyncCallback\<void\>): void 129 130Sets an application component to automatically start upon system boot. This API uses an asynchronous callback to return the result. 131 132**Required permissions**: ohos.permission.MANAGE_APP_BOOT 133 134**System capability**: SystemCapability.Ability.AbilityRuntime.Core 135 136**Device behavior differences** 137- Starting from API version 18, this API can be properly called on 2-in-1 devices and wearables. If it is called on other device types, error code 16000050 is returned. 138- For versions earlier than API version 18, this API can be properly called only on 2-in-1 devices. If it is called on other device types, error code 16000050 is returned. 139 140**Parameters** 141 142| Name | Type | Mandatory | Description | 143| --------- | ---------------------------------------- | ---- | -------------- | 144| info | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md) | Yes | Information about the target application component.| 145| callback | AsyncCallback\<void\> | Yes| Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.| 146 147**Error codes** 148 149For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 150 151| ID| Error Message | 152| -------- | -------------------------------------------- | 153| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 154| 202 | Permission denied, non-system app called system api. | 155| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 156| 16000004 | Cannot start an invisible component. | 157| 16000013 | The application is controlled by EDM. | 158| 16000050 | Internal error. | 159 160**Example** 161 162```ts 163import { autoStartupManager } from '@kit.AbilityKit'; 164import { BusinessError } from '@kit.BasicServicesKit'; 165 166try { 167 autoStartupManager.setApplicationAutoStartup({ 168 bundleName: 'com.example.autostartupapp', 169 abilityName: 'EntryAbility' 170 }, (err: BusinessError) => { 171 if (err) { 172 console.error(`setApplicationAutoStartup failed, err code: ${err.code}, err msg: ${err.message}.`); 173 return; 174 } 175 console.info(`setApplicationAutoStartup success.`); 176 }); 177} catch (err) { 178 let code = (err as BusinessError).code; 179 let msg = (err as BusinessError).message; 180 console.error(`setApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`); 181} 182``` 183 184## setApplicationAutoStartup 185 186setApplicationAutoStartup(info: AutoStartupInfo): Promise\<void\> 187 188Sets an application component to automatically start upon system boot. This API uses a promise to return the result. 189 190**Required permissions**: ohos.permission.MANAGE_APP_BOOT 191 192**System capability**: SystemCapability.Ability.AbilityRuntime.Core 193 194**Device behavior differences** 195- Starting from API version 18, this API can be properly called on 2-in-1 devices and wearables. If it is called on other device types, error code 16000050 is returned. 196- For versions earlier than API version 18, this API can be properly called only on 2-in-1 devices. If it is called on other device types, error code 16000050 is returned. 197 198**Parameters** 199 200| Name| Type | Mandatory| Description | 201| ------ | --------------- | ---- | ---------------------------- | 202| info | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md) | Yes | Information about the target application component.| 203 204**Return value** 205 206| Type | Description | 207| ------------- | ------------------------------------------------------------ | 208| Promise\<void\> | Promise that returns no value.| 209 210**Error codes** 211 212For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 213 214| ID| Error Message | 215| -------- | -------------------------------------------- | 216| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 217| 202 | Permission denied, non-system app called system api. | 218| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 219| 16000004 | Cannot start an invisible component. | 220| 16000013 | The application is controlled by EDM. | 221| 16000050 | Internal error. | 222 223**Example** 224 225```ts 226import { autoStartupManager } from '@kit.AbilityKit'; 227import { BusinessError } from '@kit.BasicServicesKit'; 228 229try { 230 autoStartupManager.setApplicationAutoStartup({ 231 bundleName: 'com.example.autostartupapp', 232 abilityName: 'EntryAbility' 233 }).then((data: void) => { 234 console.info(`setApplicationAutoStartup success.`); 235 }).catch((err: BusinessError) => { 236 console.error(`setApplicationAutoStartup failed, err code: ${err.code}, err msg: ${err.message}.`); 237 }); 238} catch (err) { 239 let code = (err as BusinessError).code; 240 let msg = (err as BusinessError).message; 241 console.error(`setApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`); 242} 243``` 244 245## cancelApplicationAutoStartup 246 247cancelApplicationAutoStartup(info: AutoStartupInfo, callback: AsyncCallback\<void\>): void 248 249Cancels the auto-startup setting for an application component. This API uses an asynchronous callback to return the result. 250 251**Required permissions**: ohos.permission.MANAGE_APP_BOOT 252 253**System capability**: SystemCapability.Ability.AbilityRuntime.Core 254 255**Device behavior differences** 256- Starting from API version 18, this API can be properly called on 2-in-1 devices and wearables. If it is called on other device types, error code 16000050 is returned. 257- For versions earlier than API version 18, this API can be properly called only on 2-in-1 devices. If it is called on other device types, error code 16000050 is returned. 258 259**Parameters** 260 261| Name | Type | Mandatory | Description | 262| --------- | ---------------------------------------- | ---- | -------------- | 263| info | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md) | Yes| Information about the target application component.| 264| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the cancellation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 265 266**Error codes** 267 268For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 269 270| ID| Error Message | 271| -------- | -------------------------------------------- | 272| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 273| 202 | Permission denied, non-system app called system api. | 274| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 275| 16000004 | Cannot start an invisible component. | 276| 16000013 | The application is controlled by EDM. | 277| 16000050 | Internal error. | 278 279**Example** 280 281```ts 282import { autoStartupManager } from '@kit.AbilityKit'; 283import { BusinessError } from '@kit.BasicServicesKit'; 284 285try { 286 autoStartupManager.cancelApplicationAutoStartup({ 287 bundleName: 'com.example.autostartupapp', 288 abilityName: 'EntryAbility' 289 }, (err: BusinessError) => { 290 if (err) { 291 console.error(`cancelApplicationAutoStartup failed, err code: ${err.code}, msg: ${err.message}.`); 292 return; 293 } 294 console.info(`cancelApplicationAutoStartup success.`); 295 }); 296} catch (err) { 297 let code = (err as BusinessError).code; 298 let msg = (err as BusinessError).message; 299 console.error(`cancelApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`); 300} 301``` 302 303## cancelApplicationAutoStartup 304 305cancelApplicationAutoStartup(info: AutoStartupInfo): Promise\<void\> 306 307Cancels the auto-startup setting for an application component. This API uses a promise to return the result. 308 309**Required permissions**: ohos.permission.MANAGE_APP_BOOT 310 311**System capability**: SystemCapability.Ability.AbilityRuntime.Core 312 313**Device behavior differences** 314- Starting from API version 18, this API can be properly called on 2-in-1 devices and wearables. If it is called on other device types, error code 16000050 is returned. 315- For versions earlier than API version 18, this API can be properly called only on 2-in-1 devices. If it is called on other device types, error code 16000050 is returned. 316 317**Parameters** 318 319| Name | Type | Mandatory | Description | 320| --------- | ---------------------------------------- | ---- | -------------- | 321| info | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md) | Yes| Information about the target application component.| 322 323**Return value** 324 325| Type | Description | 326| ------------- | ------------------------------------------------------------ | 327| Promise\<void\> | Promise that returns no value.| 328 329**Error codes** 330 331For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 332 333| ID| Error Message | 334| -------- | -------------------------------------------- | 335| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 336| 202 | Permission denied, non-system app called system api. | 337| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 338| 16000004 | Cannot start an invisible component. | 339| 16000013 | The application is controlled by EDM. | 340| 16000050 | Internal error. | 341 342**Example** 343 344```ts 345import { autoStartupManager } from '@kit.AbilityKit'; 346import { BusinessError } from '@kit.BasicServicesKit'; 347 348try { 349 autoStartupManager.cancelApplicationAutoStartup({ 350 bundleName: 'com.example.autostartupapp', 351 abilityName: 'EntryAbility' 352 }).then(() => { 353 console.info(`cancelApplicationAutoStartup success.`); 354 }).catch((err: BusinessError) => { 355 console.error(`cancelApplicationAutoStartup failed, err code: ${err.code}, msg: ${err.message}.`); 356 }); 357} catch (err) { 358 let code = (err as BusinessError).code; 359 let msg = (err as BusinessError).message; 360 console.error(`cancelApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`); 361} 362``` 363 364## queryAllAutoStartupApplications 365 366queryAllAutoStartupApplications(callback: AsyncCallback\<Array\<AutoStartupInfo\>\>): void 367 368Obtains information about all auto-startup application components. This API uses an asynchronous callback to return the result. 369 370**Required permissions**: ohos.permission.MANAGE_APP_BOOT 371 372**System capability**: SystemCapability.Ability.AbilityRuntime.Core 373 374**Device behavior differences** 375- Starting from API version 18, this API can be properly called on 2-in-1 devices and wearables. If it is called on other device types, error code 16000050 is returned. 376- For versions earlier than API version 18, this API can be properly called only on 2-in-1 devices. If it is called on other device types, error code 16000050 is returned. 377 378**Parameters** 379 380| Name | Type | Mandatory | Description | 381| --------- | ---------------------------------------- | ---- | -------------- | 382| callback | AsyncCallback\<Array\<[AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)\>\> | Yes | Callback used to return the result. If the information is obtained, **err** is **undefined** and **data** is **Array\<[AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)\>**; otherwise, **err** is an error object. | 383 384**Error codes** 385 386For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 387 388| ID| Error Message | 389| -------- | -------------------------------------------- | 390| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 391| 202 | Permission denied, non-system app called system api. | 392| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 393| 16000050 | Internal error. | 394 395**Example** 396 397```ts 398import { autoStartupManager, common } from '@kit.AbilityKit'; 399import { BusinessError } from '@kit.BasicServicesKit'; 400 401try { 402 autoStartupManager.queryAllAutoStartupApplications((err, data: common.AutoStartupInfo[]) => { 403 if (err) { 404 console.error(`queryAllAutoStartupApplications failed, err code: ${err.code}, err msg: ${err.message}.`); 405 return; 406 } 407 console.info(`queryAllAutoStartupApplications success, data: ${JSON.stringify(data)}.`); 408 }); 409} catch (err) { 410 let code = (err as BusinessError).code; 411 let msg = (err as BusinessError).message; 412 console.error(`queryAllAutoStartupApplications failed, err code: ${code}, err msg: ${msg}.`); 413} 414``` 415 416## queryAllAutoStartupApplications 417 418 queryAllAutoStartupApplications(): Promise\<Array\<AutoStartupInfo\>\> 419 420Obtains information about all auto-startup application components. This API uses a promise to return the result. 421 422**Required permissions**: ohos.permission.MANAGE_APP_BOOT 423 424**System capability**: SystemCapability.Ability.AbilityRuntime.Core 425 426**Device behavior differences** 427- Starting from API version 18, this API can be properly called on 2-in-1 devices and wearables. If it is called on other device types, error code 16000050 is returned. 428- For versions earlier than API version 18, this API can be properly called only on 2-in-1 devices. If it is called on other device types, error code 16000050 is returned. 429 430**Return value** 431 432| Type | Description | 433| ------------------------------- | ------------------------------------------------------------ | 434| Promise\<Array\<[AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)\>\> | Promise used to return the information obtained.| 435 436**Error codes** 437 438For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 439 440| ID| Error Message | 441| -------- | -------------------------------------------- | 442| 201 | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". | 443| 202 | Permission denied, non-system app called system api. | 444| 401 | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 445| 16000050 | Internal error. | 446 447**Example** 448 449```ts 450import { autoStartupManager, common } from '@kit.AbilityKit'; 451import { BusinessError } from '@kit.BasicServicesKit'; 452 453try { 454 autoStartupManager.queryAllAutoStartupApplications().then((data: common.AutoStartupInfo[]) => { 455 console.info(`queryAllAutoStartupApplications success, data: ${JSON.stringify(data)}.`); 456 }).catch((err: BusinessError) => { 457 console.error(`queryAllAutoStartupApplications failed, err code: ${err.code}, err msg: ${err.message}.`); 458 }); 459} catch (err) { 460 let code = (err as BusinessError).code; 461 let msg = (err as BusinessError).message; 462 console.error(`queryAllAutoStartupApplications failed, err code: ${code}, err msg: ${msg}.`); 463} 464``` 465