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 16import Want from '../../@ohos.app.ability.Want'; 17import { ResultSet } from '../../data/rdb/resultSet'; 18import { AbilityInfo } from '../../bundle/abilityInfo'; 19import { DataAbilityResult } from '../../ability/dataAbilityResult'; 20import { DataAbilityOperation } from '../../ability/dataAbilityOperation'; 21import dataAbility from '../../@ohos.data.dataAbility'; 22import formBindingData from '../../@ohos.application.formBindingData'; 23import formInfo from '../../@ohos.app.form.formInfo'; 24import rdb from '../../@ohos.data.rdb'; 25import rpc from '../../@ohos.rpc'; 26import resourceManager from '../../@ohos.resourceManager'; 27import { PacMap } from '../../ability/dataAbilityHelper'; 28import { AsyncCallback } from '../../@ohos.base'; 29 30/** 31 * interface of form lifecycle. 32 * 33 * @interface LifecycleForm 34 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 35 * @FAModelOnly 36 * @since 7 37 */ 38export declare interface LifecycleForm { 39 /** 40 * Called to return a {@link formBindingData.FormBindingData} object. 41 * 42 * @param { Want } want - Indicates the detailed information for creating a {@link formBindingData#FormBindingData}. 43 * The {@code Want} object must include the form ID, form name, and grid style of the form, 44 * which can be obtained from {@link formInfo#FormParam#IDENTITY_KEY}, 45 * {@link formInfo#FormParam#NAME_KEY}, and {@link formInfo#FormParam#DIMENSION_KEY}, 46 * respectively. Such form information must be managed as persistent data for further form 47 * acquisition, update, and deletion. 48 * @returns { formBindingData.FormBindingData } Returns the created {@link formBindingData#FormBindingData} object. 49 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 50 * @FAModelOnly 51 * @since 8 52 */ 53 onCreate?(want: Want): formBindingData.FormBindingData; 54 55 /** 56 * Called when the form provider is notified that a temporary form is successfully converted to a normal form. 57 * 58 * @param { string } formId - Indicates the ID of the form. 59 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 60 * @FAModelOnly 61 * @since 8 62 */ 63 onCastToNormal?(formId: string): void; 64 65 /** 66 * Called to notify the form provider to update a specified form. 67 * 68 * @param { string } formId - Indicates the ID of the form to update. 69 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 70 * @FAModelOnly 71 * @since 8 72 */ 73 onUpdate?(formId: string): void; 74 75 /** 76 * Called when the form provider receives form events from the system. 77 * 78 * @param { object } newStatus - Indicates the form events occurred. The key in the {@code Map} object indicates 79 * form ID,and the value indicates the event type, which can be either 80 * {@link formInfo#VisibilityType#FORM_VISIBLE} or 81 * {@link formInfo#VisibilityType#FORM_INVISIBLE}. 82 * {@link formInfo#VisibilityType#FORM_VISIBLE} 83 * means that the form becomes visible, and 84 * {@link formInfo#VisibilityType#FORM_INVISIBLE} 85 * means that the form becomes invisible. 86 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 87 * @FAModelOnly 88 * @since 8 89 */ 90 onVisibilityChange?(newStatus: { [key: string]: number }): void; 91 92 /** 93 * Called when a specified message event defined by the form provider is triggered. This method is valid only for 94 * JS forms. 95 * 96 * @param { string } formId - Indicates the ID of the form on which the message event is triggered, which is 97 * provided by the client to the form provider. 98 * @param { string } message - Indicates the value of the {@code params} field of the message event. This parameter 99 * is used to identify the specific component on which the event is triggered. 100 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 101 * @FAModelOnly 102 * @since 8 103 */ 104 onEvent?(formId: string, message: string): void; 105 106 /** 107 * Called to notify the form provider that a specified form has been deleted. Override this method if 108 * you want your application, as the form provider, to be notified of form deletion. 109 * 110 * @param { string } formId - Indicates the ID of the deleted form. 111 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 112 * @FAModelOnly 113 * @since 8 114 */ 115 onDestroy?(formId: string): void; 116 117 /** 118 * Called to return a {@link FormState} object. 119 * <p>You must override this callback if you want this ability to return the actual form state. Otherwise, 120 * this method returns {@link FormState#DEFAULT} by default.</p> 121 * 122 * @param { Want } want - Indicates the description of the form for which the {@link formInfo#FormState} is obtained. 123 * The description covers the bundle name, ability name, module name, form name, form 124 * dimensions. 125 * @returns { formInfo.FormState } Returns the {@link formInfo#FormState} object. 126 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 127 * @FAModelOnly 128 * @since 8 129 */ 130 onAcquireFormState?(want: Want): formInfo.FormState; 131 132 /** 133 * Called when the system shares the form. 134 * 135 * @param { string } formId - Indicates the ID of the deleted form. 136 * @returns { { [key: string]: any } } Returns the wantParams object. 137 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 138 * @systemapi 139 * @FAModelOnly 140 * @since 9 141 */ 142 onShare?(formId: string): { [key: string]: any }; 143} 144 145/** 146 * interface of app lifecycle. 147 * 148 * @interface LifecycleApp 149 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 150 * @FAModelOnly 151 * @since 7 152 */ 153export declare interface LifecycleApp { 154 /** 155 * Called back when the state of an ability changes from <b>BACKGROUND</b> to <b>INACTIVE</b>. 156 * 157 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 158 * @FAModelOnly 159 * @since 7 160 */ 161 onShow?(): void; 162 163 /** 164 * Called back when an ability enters the <b>BACKGROUND</b> state. 165 * 166 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 167 * @FAModelOnly 168 * @since 7 169 */ 170 onHide?(): void; 171 172 /** 173 * Called back before an ability is destroyed. 174 * 175 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 176 * @FAModelOnly 177 * @since 7 178 */ 179 onDestroy?(): void; 180 181 /** 182 * Called back when an ability is started for initialization. 183 * 184 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 185 * @FAModelOnly 186 * @since 7 187 */ 188 onCreate?(): void; 189 190 /** 191 * Called when the window display mode of this ability changes, for example, from fullscreen mode 192 * to multi-window mode or from multi-window mode to fullscreen mode. 193 * 194 * @param { boolean } isShownInMultiWindow - Specifies whether this ability is currently in multi-window mode.The 195 * value {@code true} indicates the multi-window mode, and {@code false} 196 * indicates another mode. 197 * @param { resourceManager.Configuration } newConfig - Indicates the new configuration information about Page ability. 198 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 199 * @systemapi 200 * @FAModelOnly 201 * @since 7 202 */ 203 onWindowDisplayModeChanged?(isShownInMultiWindow: boolean, newConfig: resourceManager.Configuration): void; 204 205 /** 206 * Asks a user whether to start the migration. 207 * 208 * @returns { boolean } Returns {@code true} if the user allows the migration; returns {@code false} otherwise. 209 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 210 * @FAModelOnly 211 * @since 7 212 */ 213 onStartContinuation?(): boolean; 214 215 /** 216 * Saves the user data of a local ability generated during runtime. 217 * After the migration is triggered and the local ability is ready, this method is called when the Distributed 218 * Scheduler Service requests data from the local ability. 219 * 220 * @param { Object } data - Indicates the user data to save. 221 * @returns { boolean } Returns {@code true} if the data is successfully saved; returns {@code false} otherwise. 222 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 223 * @FAModelOnly 224 * @since 7 225 */ 226 onSaveData?(data: Object): boolean; 227 228 /** 229 * Called back when a local ability migration is complete. 230 * <p>You can define the processing logic after the migration is complete. For example, you can display a prompt to 231 * notify the user of the successful migration and then exit the local ability.</p> 232 * 233 * @param { number } result - Indicates the migration result code. The value {@code 0} indicates that the migration is 234 * successful, and {@code -1} indicates that the migration fails. 235 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 236 * @FAModelOnly 237 * @since 7 238 */ 239 onCompleteContinuation?(result: number): void; 240 241 /** 242 * Restores the user data saved during the migration for an ability on the remote device immediately after the 243 * ability is created on the remote device. Lifecycle scheduling for the ability starts only after the user data 244 * is restored. 245 * 246 * @param { Object } data - Indicates the user data to restore. 247 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 248 * @FAModelOnly 249 * @since 7 250 */ 251 onRestoreData?(data: Object): void; 252 253 /** 254 * Called to notify the local device when a running ability on the remote device is destroyed after a reversible 255 * migration is performed for the ability from the local device to the remote device. 256 * 257 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 258 * @FAModelOnly 259 * @since 7 260 */ 261 onRemoteTerminated?(): void; 262 263 /** 264 * This method is called when the system determines that the ability may be destroyed in an unexpected 265 * situation, for example, when the screen orientation changes or the user touches the Home key. Generally, 266 * this method is used only to save temporary states. 267 * 268 * @param { PacMap } outState - Indicates the {@code PacMap} object used for storing user data and states. This 269 * parameter cannot be null. 270 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 271 * @FAModelOnly 272 * @since 7 273 */ 274 onSaveAbilityState?(outState: PacMap): void; 275 276 /** 277 * This method is called if an ability was destroyed at a certain time due to resource reclaim or was 278 * unexpectedly destroyed and the {@link #onSaveAbilityState(PacMap)} method was called to save its user data and 279 * states. Generally, this method is called after the {@link #onStart(Want)} method. 280 * 281 * @param { PacMap } inState - Indicates the {@code PacMap} object used for storing data and states. This 282 * parameter can not be null. 283 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 284 * @FAModelOnly 285 * @since 7 286 */ 287 onRestoreAbilityState?(inState: PacMap): void; 288 289 /** 290 * Called back when an ability enters the <b>INACTIVE</b> state (an ability in this state is not interactive and may 291 * change to the <b>BACKGROUND</b> or <b>ACTIVE</b> state). 292 * 293 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 294 * @FAModelOnly 295 * @since 7 296 */ 297 onInactive?(): void; 298 299 /** 300 * Called back when an ability enters the <b>ACTIVE</b> state. 301 * 302 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 303 * @FAModelOnly 304 * @since 7 305 */ 306 onActive?(): void; 307 308 /** 309 * Called when the launch mode of an ability is set to singleton. 310 * 311 * @param { Want } want - Indicates the new {@code want} containing information about the ability. 312 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 313 * @FAModelOnly 314 * @since 7 315 */ 316 onNewWant?(want: Want): void; 317 318 /** 319 * Called when the system has determined to trim the memory, for example, when the ability is running in the 320 * background and there is no enough memory for running as many background processes as possible. 321 * 322 * @param { number } level - Indicates the memory trim level, which shows the current memory usage status. 323 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 324 * @FAModelOnly 325 * @since 7 326 */ 327 onMemoryLevel?(level: number): void; 328} 329 330/** 331 * interface of service lifecycle. 332 * 333 * @interface LifecycleService 334 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 335 * @FAModelOnly 336 * @since 7 337 */ 338export declare interface LifecycleService { 339 /** 340 * Called back when an ability is started for initialization (it can be called only once in the entire lifecycle of 341 * an ability). 342 * 343 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 344 * @FAModelOnly 345 * @since 7 346 */ 347 onStart?(): void; 348 349 /** 350 * Called back when Service is started. 351 * 352 * @param { Want } want - Indicates the want of Service to start. 353 * @param { number } startId - Indicates the number of times the Service ability has been started. {@code startId} is 354 * incremented by 1 every time the ability is started. For example, if the ability 355 * has been started for six times. 356 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 357 * @FAModelOnly 358 * @since 7 359 */ 360 onCommand?(want: Want, startId: number): void; 361 362 /** 363 * Called back before an ability is destroyed. 364 * 365 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 366 * @FAModelOnly 367 * @since 7 368 */ 369 onStop?(): void; 370 371 /** 372 * Called back when a Service ability is first connected to an ability. 373 * 374 * @param { Want } want - Indicates connection information about the Service ability. 375 * @returns { rpc.RemoteObject } Returns the proxy of the Service ability. 376 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 377 * @FAModelOnly 378 * @since 7 379 */ 380 onConnect?(want: Want): rpc.RemoteObject; 381 382 /** 383 * Called back when all abilities connected to a Service ability are disconnected. 384 * 385 * @param { Want } want - Indicates disconnection information about the Service ability. 386 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 387 * @FAModelOnly 388 * @since 7 389 */ 390 onDisconnect?(want: Want): void; 391 392 /** 393 * Called when a new client attempts to connect to a Service ability after all previous client connections to it 394 * are disconnected. 395 * <p>The Service ability must have been started but not been destroyed, that is, {@link #startAbility} has been 396 * called but {@link #terminateSelf} has not.</p> 397 * 398 * @param { Want } want - Indicates the want of the Service ability being connected. 399 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 400 * @FAModelOnly 401 * @since 7 402 */ 403 onReconnect?(want: Want): void; 404} 405 406/** 407 * interface of data lifecycle. 408 * 409 * @interface LifecycleData 410 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 411 * @FAModelOnly 412 * @since 7 413 */ 414export declare interface LifecycleData { 415 /** 416 * Updates one or more data records in the database. This method should be implemented by a Data ability. 417 * 418 * @param { string } uri - Indicates the database table storing the data to update. 419 * @param { rdb.ValuesBucket } valueBucket - Indicates the data to update. This parameter can be null. 420 * @param { dataAbility.DataAbilityPredicates } predicates - Indicates filter criteria. If this parameter is null, 421 * all data records will be updated by default. 422 * @param { AsyncCallback<number> } callback - function specified by framework to receive the result, developer should 423 * call this function to return the result to framework. 424 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 425 * @FAModelOnly 426 * @since 7 427 */ 428 update?( 429 uri: string, 430 valueBucket: rdb.ValuesBucket, 431 predicates: dataAbility.DataAbilityPredicates, 432 callback: AsyncCallback<number> 433 ): void; 434 435 /** 436 * Queries one or more data records in the database. This method should be implemented by a Data ability. 437 * 438 * @param { string } uri - Indicates the database table storing the data to query. 439 * @param { Array<string> } columns - Indicates the columns to be queried, in array, for example, {"name","age"}. 440 * You should define the processing logic when this parameter is null. 441 * @param { dataAbility.DataAbilityPredicates } predicates - Indicates filter criteria. If this parameter is null, 442 * all data records will be queried by default. 443 * @param { AsyncCallback<ResultSet> } callback - function specified by framework to receive the result, developer 444 * should call this function to return the result to framework. 445 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 446 * @FAModelOnly 447 * @since 7 448 */ 449 query?( 450 uri: string, 451 columns: Array<string>, 452 predicates: dataAbility.DataAbilityPredicates, 453 callback: AsyncCallback<ResultSet> 454 ): void; 455 456 /** 457 * Deletes one or more data records. This method should be implemented by a Data ability. 458 * 459 * @param { string } uri - Indicates the database table storing the data to delete. 460 * @param { dataAbility.DataAbilityPredicates } predicates - Indicates filter criteria. If this parameter is null, 461 * all data records will be deleted by default. 462 * @param { AsyncCallback<number> } callback - function specified by framework to receive the result, developer should 463 * call this function to return the result to framework. 464 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 465 * @FAModelOnly 466 * @since 7 467 */ 468 delete?(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void; 469 470 /** 471 * Converts the given {@code uri} that refer to the Data ability into a normalized URI. A normalized URI can be 472 * used across devices, persisted, backed up, and restored. It can refer to the same item in the Data ability 473 * even if the context has changed. 474 * 475 * @param { string } uri - Indicates the uri to normalize. 476 * @param { AsyncCallback<string> } callback - function specified by framework to receive the result, developer 477 * should call this function to return the result to framework. 478 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 479 * @FAModelOnly 480 * @since 7 481 */ 482 normalizeUri?(uri: string, callback: AsyncCallback<string>): void; 483 484 /** 485 * Inserts multiple data records into the database. This method should be implemented by a Data ability. 486 * 487 * @param { string } uri - Indicates the position where the data is to insert. 488 * @param { Array<rdb.ValuesBucket> } valueBuckets - Indicates the data to insert. 489 * @param { AsyncCallback<number> } callback - function specified by framework to receive the result, developer should 490 * call this function to return the result to framework. 491 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 492 * @FAModelOnly 493 * @since 7 494 */ 495 batchInsert?(uri: string, valueBuckets: Array<rdb.ValuesBucket>, callback: AsyncCallback<number>): void; 496 497 /** 498 * Converts the given normalized {@code uri} generated by {@link #normalizeUri(uri)} into a denormalized one. 499 * The default implementation of this method returns the original uri passed to it. 500 * 501 * @param { string } uri - Indicates the uri to denormalize. 502 * @param { AsyncCallback<string> } callback - function specified by framework to receive the result, developer 503 * should call this function to return the result to framework. 504 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 505 * @FAModelOnly 506 * @since 7 507 */ 508 denormalizeUri?(uri: string, callback: AsyncCallback<string>): void; 509 510 /** 511 * Inserts a data record into the database. This method should be implemented by a Data ability. 512 * 513 * @param { string } uri - Indicates the position where the data is to insert. 514 * @param { rdb.ValuesBucket } valueBucket - Indicates the data to insert. 515 * @param { AsyncCallback<number> } callback - function specified by framework to receive the result, developer 516 * should call this function to return the result to framework. 517 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 518 * @FAModelOnly 519 * @since 7 520 */ 521 insert?(uri: string, valueBucket: rdb.ValuesBucket, callback: AsyncCallback<number>): void; 522 523 /** 524 * Opens a file. This method should be implemented by a Data ability. 525 * 526 * @param { string } uri - Indicates the path of the file to open. 527 * @param { string } mode - Indicates the open mode, which can be "r" for read-only access, "w" for write-only access 528 * (erasing whatever data is currently in the file), "wt" for write access that truncates any 529 * existing file,"wa" for write-only access to append to any existing data, "rw" for read and 530 * write access on any existing data, or "rwt" for read and write access that truncates any 531 * existing file. 532 * @param { AsyncCallback<number> } callback - function specified by framework to receive the result, developer should 533 * call this function to return the result to framework. 534 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 535 * @FAModelOnly 536 * @since 7 537 */ 538 openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void; 539 540 /** 541 * Obtains the MIME type of files. This method should be implemented by a Data ability. 542 * 543 * @param { string } uri - Indicates the path of the files to obtain. 544 * @param { string } mimeTypeFilter - Indicates the MIME type of the files to obtain. This parameter cannot be set to 545 * {@code null}. 546 * <p>1. "*/*": Obtains all types supported by a Data ability. 547 * <p>2. "image/*": Obtains files whose main type is image of any subtype. 548 * <p>3. "*/jpg": Obtains files whose subtype is JPG of any main type. 549 * @param { AsyncCallback<Array<string>> } callback - function specified by framework to receive the result, developer 550 * should call this function to return the result to framework. 551 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 552 * @FAModelOnly 553 * @since 7 554 */ 555 getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void; 556 557 /** 558 * Called to carry {@code AbilityInfo} to this ability after the ability is initialized. 559 * 560 * @param { AbilityInfo } info - Indicates the {@code AbilityInfo} object containing information about this ability. 561 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 562 * @FAModelOnly 563 * @since 7 564 */ 565 onInitialized?(info: AbilityInfo): void; 566 567 /** 568 * Obtains the MIME type matching the data specified by the URI of the Data ability. This method should be 569 * implemented by a Data ability. 570 * <p>Data abilities supports general data types, including text, HTML, and JPEG.</p> 571 * 572 * @param { string } uri - Indicates the uri of the data. 573 * @param { AsyncCallback<string> } callback - function specified by framework to receive the result, developer should 574 * call this function to return the result to framework. 575 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 576 * @FAModelOnly 577 * @since 7 578 */ 579 getType?(uri: string, callback: AsyncCallback<string>): void; 580 581 /** 582 * Performs batch operations on the database. This method should be implemented by a Data ability. 583 * 584 * @param { Array<DataAbilityOperation> } ops - Indicates the data operation list, which can contain multiple operations 585 * on the database. 586 * @param { AsyncCallback<Array<DataAbilityResult>> } callback - specified by framework to receive the result, 587 * developer should call this function to return 588 * the result to framework. 589 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 590 * @FAModelOnly 591 * @since 7 592 */ 593 executeBatch?(ops: Array<DataAbilityOperation>, callback: AsyncCallback<Array<DataAbilityResult>>): void; 594 595 /** 596 * Defines a method in this Data ability (implementation depending on child classes). 597 * 598 * @param { string } method - Indicates the method name. 599 * @param { string } arg - Indicates the parameter transferred by the method. 600 * @param { PacMap } extras - Indicates the parameter transferred by the method. 601 * @param { AsyncCallback<PacMap> } callback - function specified by framework to receive the result, developer 602 * should call this function to return the result to framework. 603 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 604 * @FAModelOnly 605 * @since 7 606 */ 607 call?(method: string, arg: string, extras: PacMap, callback: AsyncCallback<PacMap>): void; 608} 609