1/* 2 * Copyright (C) 2024 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 Helper functions to access image and video assets 18 * @kit MediaLibraryKit 19 */ 20 21import type Context from './application/Context'; 22import type image from './@ohos.multimedia.image'; 23import lang from '../arkts/@arkts.lang'; 24import photoAccessHelper from './@ohos.file.photoAccessHelper'; 25 26/** 27 * Helper functions to access image and video assets 28 * 29 * @namespace sendablePhotoAccessHelper 30 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 31 * @atomicservice 32 * @since 12 33 */ 34declare namespace sendablePhotoAccessHelper { 35 /** 36 * Returns an instance of PhotoAccessHelper 37 * 38 * @param { Context } context - Hap context information 39 * @returns { PhotoAccessHelper } Instance of PhotoAccessHelper 40 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 41 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 42 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 43 * @StageModelOnly 44 * @atomicservice 45 * @since 12 46 */ 47 function getPhotoAccessHelper(context: Context): PhotoAccessHelper; 48 49 /** 50 * Returns an instance of PhotoAccessHelper 51 * 52 * @permission ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 53 * @param { Context } context - Hap context information 54 * @param { number } userId - Target userId 55 * @returns { PhotoAccessHelper } Instance of PhotoAccessHelper 56 * @throws { BusinessError } 201 - Permission denied 57 * @throws { BusinessError } 202 - Called by non-system application 58 * @throws { BusinessError } 13900020 - Invalid argument 59 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 60 * @systemapi 61 * @StageModelOnly 62 * @since 19 63 */ 64 function getPhotoAccessHelper(context: Context, userId: number): PhotoAccessHelper; 65 66 /** 67 * Enumerates media file types. 68 * 69 * @enum { number } PhotoType 70 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 71 * @atomicservice 72 * @since 12 73 */ 74 const enum PhotoType { 75 /** 76 * Image. 77 * 78 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 79 * @atomicservice 80 * @since 12 81 */ 82 IMAGE = 1, 83 /** 84 * Video. 85 * 86 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 87 * @atomicservice 88 * @since 12 89 */ 90 VIDEO = 2 91 } 92 93 /** 94 * Enumerates the PhotoAsset types. 95 * 96 * @enum { number } PhotoSubtype 97 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 98 * @atomicservice 99 * @since 14 100 */ 101 enum PhotoSubtype { 102 /** 103 * Photo, which is the default type. 104 * 105 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 106 * @atomicservice 107 * @since 14 108 */ 109 DEFAULT = 0, 110 /** 111 * Screenshot Photo Type 112 * 113 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 114 * @systemapi 115 * @since 14 116 */ 117 SCREENSHOT = 1, 118 /** 119 * Moving photo. 120 * 121 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 122 * @atomicservice 123 * @since 14 124 */ 125 MOVING_PHOTO = 3, 126 /** 127 * Burst photo. 128 * 129 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 130 * @atomicservice 131 * @since 14 132 */ 133 BURST = 4, 134 } 135 136 /** 137 * Enumerates the dynamic range types of media assets. 138 * 139 * @enum { number } DynamicRangeType 140 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 141 * @since 14 142 */ 143 enum DynamicRangeType { 144 /** 145 * Standard dynamic range (SDR). 146 * 147 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 148 * @since 14 149 */ 150 SDR = 0, 151 /** 152 * High dynamic range (HDR). 153 * 154 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 155 * @since 14 156 */ 157 HDR = 1 158 } 159 160 /** 161 * Ability to access thumbnail 162 * 163 * @enum { number } ThumbnailVisibility 164 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 165 * @systemapi 166 * @since 14 167 */ 168 enum ThumbnailVisibility { 169 /** 170 * Unable to access thumbnail 171 * 172 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 173 * @systemapi 174 * @since 14 175 */ 176 INVISIBLE = 0, 177 /** 178 * able to access thumbnail 179 * 180 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 181 * @systemapi 182 * @since 14 183 */ 184 VISIBLE = 1 185 } 186 187 /** 188 * Photo asset position 189 * 190 * @enum { number } Photo asset position, such as local device or cloud 191 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 192 * @systemapi 193 * @since 14 194 */ 195 enum PositionType { 196 /** 197 * Asset exists only in local device 198 * 199 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 200 * @systemapi 201 * @since 14 202 */ 203 LOCAL = 1 << 0, 204 /** 205 * Asset exists only in cloud 206 * 207 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 208 * @systemapi 209 * @since 14 210 */ 211 CLOUD = 1 << 1 212 } 213 214 /** 215 * Enumeration of moving photo effect mode. 216 * 217 * @enum { number } MovingPhotoEffectMode 218 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 219 * @systemapi 220 * @since 14 221 */ 222 enum MovingPhotoEffectMode { 223 /** 224 * Default 225 * 226 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 227 * @systemapi 228 * @since 14 229 */ 230 DEFAULT = 0, 231 232 /** 233 * Bounce play 234 * 235 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 236 * @systemapi 237 * @since 14 238 */ 239 BOUNCE_PLAY = 1, 240 241 /** 242 * Loop play 243 * 244 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 245 * @systemapi 246 * @since 14 247 */ 248 LOOP_PLAY = 2, 249 250 /** 251 * Long exposure 252 * 253 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 254 * @systemapi 255 * @since 14 256 */ 257 LONG_EXPOSURE = 3, 258 259 /** 260 * Multi exposure 261 * 262 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 263 * @systemapi 264 * @since 14 265 */ 266 MULTI_EXPOSURE = 4, 267 268 /** 269 * Cinema graph 270 * 271 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 272 * @systemapi 273 * @since 14 274 */ 275 CINEMA_GRAPH = 5, 276 277 /** 278 * Image only 279 * 280 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 281 * @systemapi 282 * @since 14 283 */ 284 IMAGE_ONLY = 10 285 } 286 287 /** 288 * Defines the photo asset 289 * 290 * @interface PhotoAsset 291 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 292 * @atomicservice 293 * @since 12 294 */ 295 interface PhotoAsset extends lang.ISendable { 296 /** 297 * uri of the asset. 298 * 299 * @type { string } 300 * @readonly 301 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 302 * @atomicservice 303 * @since 12 304 */ 305 readonly uri: string; 306 /** 307 * Photo type, image or video 308 * 309 * @type { PhotoType } 310 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 311 * @since 12 312 */ 313 readonly photoType: PhotoType; 314 /** 315 * Display name (with a file name extension) of the asset. 316 * 317 * @type { string } 318 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 319 * @since 12 320 */ 321 readonly displayName: string; 322 /** 323 * Obtains a PhotoAsset member parameter. 324 * 325 * @param { string } member - Name of the member parameter to obtain. 326 * Except 'uri', 'media_type', 'subtype', and 'display_name', you must pass in PhotoKeys in fetchColumns. 327 * For example, to obtain the title, pass in fetchColumns: ['title']. 328 * @returns { MemberType } Returns the value of the specified photo asset member 329 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 330 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 331 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 332 * @since 12 333 */ 334 get(member: string): photoAccessHelper.MemberType; 335 /** 336 * Sets a PhotoAsset member parameter. 337 * 338 * @param { string } member - Name of the parameter to set, for example, PhotoKeys.TITLE. The value contains 1 to 255 characters. 339 * @param { string } value - Value to set. Only the value of PhotoKeys. TITLE can be changed. 340 * The title must meet the following requirements: 341 * - It does not contain a file name extension. 342 * - The file name, which is in the format of title+file name extension, does not exceed 255 characters. 343 * - The title does not contain any of the following characters:\ / : * ? " ' ` < > | { } [ ] 344 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 345 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 346 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 347 * @since 12 348 * @example : set(PhotoKeys.TITLE, "newTitle"), call commitModify after set 349 */ 350 set(member: string, value: string): void; 351 /** 352 * Commits the modification on the file metadata to the database. This API uses a promise to return the result. 353 * 354 * @permission ohos.permission.WRITE_IMAGEVIDEO 355 * @returns { Promise<void> } Returns void 356 * @throws { BusinessError } 201 - Permission denied 357 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 358 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 359 * @throws { BusinessError } 14000011 - Internal system error 360 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 361 * @atomicservice 362 * @since 12 363 */ 364 commitModify(): Promise<void>; 365 /** 366 * Obtains the file thumbnail of the given size. This API uses a promise to return the result. 367 * 368 * @permission ohos.permission.READ_IMAGEVIDEO 369 * @param { image.Size } [size] - Size of the thumbnail. 370 * @returns { Promise<image.PixelMap> } Returns the thumbnail's pixelMap. 371 * @throws { BusinessError } 201 - Permission denied 372 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 373 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 374 * @throws { BusinessError } 14000011 - Internal system error 375 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 376 * @since 12 377 */ 378 getThumbnail(size?: image.Size): Promise<image.PixelMap>; 379 /** 380 * Get analysis data of the asset. 381 * 382 * @permission ohos.permission.READ_IMAGEVIDEO 383 * @param { AnalysisType } analysisType - Analysis type 384 * @returns { Promise<string> } Returns analysis info into a json string 385 * @throws { BusinessError } 201 - Permission denied 386 * @throws { BusinessError } 202 - Called by non-system application 387 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 388 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 389 * @throws { BusinessError } 14000011 - Internal system error 390 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 391 * @systemapi 392 * @since 12 393 */ 394 getAnalysisData(analysisType: photoAccessHelper.AnalysisType): Promise<string>; 395 /** 396 * Opens the source file to obtain the file descriptor (FD). This API uses a promise to return the result. 397 * 398 * @permission ohos.permission.READ_IMAGEVIDEO 399 * @returns { Promise<number> } Returns opened source asset fd. 400 * @throws { BusinessError } 201 - Permission denied. 401 * @throws { BusinessError } 202 - Called by non-system application. 402 * @throws { BusinessError } 14000011 - Internal system error 403 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 404 * @systemapi 405 * @since 12 406 */ 407 requestSource(): Promise<number>; 408 /** 409 * Converts a Sendable PhotoAsset object to a non-Sendable PhotoAsset object. 410 * 411 * @returns { photoAccessHelper.PhotoAsset } Returns the instance if the operation is successful. 412 * @throws { BusinessError } 201 - Permission denied. 413 * @throws { BusinessError } 14000011 - Internal system error 414 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 415 * @since 12 416 */ 417 convertToPhotoAsset(): photoAccessHelper.PhotoAsset; 418 } 419 420 /** 421 * Provides APIs to manage the file retrieval result. 422 * 423 * @interface FetchResult 424 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 425 * @since 12 426 */ 427 interface FetchResult<T> extends lang.ISendable { 428 /** 429 * Obtains the total number of files in the result set. 430 * 431 * @returns { number } Total number of objects. 432 * @throws { BusinessError } 14000011 - Internal system error 433 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 434 * @since 12 435 */ 436 getCount(): number; 437 /** 438 * Checks whether the cursor is in the last row of the result set. 439 * 440 * @returns { boolean } Whether the object is the last one in the fetch result. 441 * @throws { BusinessError } 14000011 - Internal system error 442 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 443 * @since 12 444 */ 445 isAfterLast(): boolean; 446 /** 447 * Obtains the first asset in the result set. This API uses a promise to return the result. 448 * 449 * @returns { Promise<T> } Returns the first object in the fetch result. 450 * @throws { BusinessError } 14000011 - Internal system error 451 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 452 * @since 12 453 */ 454 getFirstObject(): Promise<T>; 455 /** 456 * Obtains the next asset in the result set. This API uses a promise to return the result. 457 * Before using this API, you must use isAfterLast() to check whether the current position is the end of the result set. 458 * 459 * @returns { Promise<T> } Returns the next object 460 * @throws { BusinessError } 14000011 - Internal system error 461 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 462 * @since 12 463 */ 464 getNextObject(): Promise<T>; 465 /** 466 * Obtains the last asset in the result set. This API uses a promise to return the result. 467 * 468 * @returns { Promise<T> } Returns the last object 469 * @throws { BusinessError } 14000011 - Internal system error 470 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 471 * @since 12 472 */ 473 getLastObject(): Promise<T>; 474 /** 475 * Obtains the asset with the given index in the result set. This API uses a promise to return the result. 476 * 477 * @param { number } index - Index of the asset to obtain. The value starts from 0. 478 * @returns { Promise<T> } Returns the object 479 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 480 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 481 * @throws { BusinessError } 14000011 - Internal system error 482 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 483 * @since 12 484 */ 485 getObjectByPosition(index: number): Promise<T>; 486 /** 487 * Obtains all the file assets in the result set. This API uses a promise to return the result. 488 * 489 * @returns { Promise<Array<T>> } Returns all the objects 490 * @throws { BusinessError } 14000011 - Internal system error 491 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 492 * @since 12 493 */ 494 getAllObjects(): Promise<Array<T>>; 495 /** 496 * Closes this FetchFileResult instance to invalidate it. 497 * After this instance is closed, the APIs in this instance cannot be invoked. 498 * 499 * @throws { BusinessError } 14000011 - Internal system error 500 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 501 * @since 12 502 */ 503 close(): void; 504 } 505 506 /** 507 * Enumerates the album types. 508 * 509 * @enum { number } AlbumType 510 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 511 * @since 12 512 */ 513 const enum AlbumType { 514 /** 515 * User album. 516 * 517 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 518 * @since 12 519 */ 520 USER = 0, 521 /** 522 * System album. 523 * 524 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 525 * @since 12 526 */ 527 SYSTEM = 1024, 528 /** 529 * Smart analysis album. System API: This is a system API. 530 * 531 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 532 * @systemapi 533 * @since 12 534 */ 535 SMART = 4096 536 } 537 538 /** 539 * Album subtype 540 * 541 * @enum { number } AlbumSubtype 542 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 543 * @since 12 544 */ 545 const enum AlbumSubtype { 546 /** 547 * User album. 548 * 549 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 550 * @since 12 551 */ 552 USER_GENERIC = 1, 553 /** 554 * Favorites. 555 * 556 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 557 * @since 12 558 */ 559 FAVORITE = 1025, 560 /** 561 * Video album, which contains all video assets. 562 * 563 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 564 * @since 12 565 */ 566 VIDEO, 567 /** 568 * Hidden album, which assets are marked as hidden. 569 * 570 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 571 * @systemapi 572 * @since 12 573 */ 574 HIDDEN, 575 /** 576 * Trash album, which assets are deleted. 577 * 578 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 579 * @systemapi 580 * @since 12 581 */ 582 TRASH, 583 /** 584 * Screenshot album 585 * 586 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 587 * @systemapi 588 * @since 12 589 */ 590 SCREENSHOT, 591 /** 592 * Camera album 593 * 594 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 595 * @systemapi 596 * @since 12 597 */ 598 CAMERA, 599 /** 600 * Image album 601 * 602 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 603 * @since 12 604 */ 605 IMAGE = 1031, 606 /** 607 * Source album 608 * 609 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 610 * @systemapi 611 * @since 12 612 */ 613 SOURCE_GENERIC = 2049, 614 /** 615 * Classify album 616 * 617 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 618 * @systemapi 619 * @since 12 620 */ 621 CLASSIFY = 4097, 622 /** 623 * Location album 624 * 625 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 626 * @systemapi 627 * @since 12 628 */ 629 GEOGRAPHY_LOCATION = 4099, 630 /** 631 * City album 632 * 633 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 634 * @systemapi 635 * @since 12 636 */ 637 GEOGRAPHY_CITY, 638 /** 639 * ShootingMode album 640 * 641 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 642 * @systemapi 643 * @since 12 644 */ 645 SHOOTING_MODE, 646 /** 647 * Portrait album 648 * 649 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 650 * @systemapi 651 * @since 12 652 */ 653 PORTRAIT, 654 /** 655 * Group photo album 656 * 657 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 658 * @systemapi 659 * @since 12 660 */ 661 GROUP_PHOTO, 662 /** 663 * Highlight album 664 * 665 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 666 * @systemapi 667 * @since 12 668 */ 669 HIGHLIGHT = 4104, 670 /** 671 * Highlight suggestions album 672 * 673 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 674 * @systemapi 675 * @since 12 676 */ 677 HIGHLIGHT_SUGGESTIONS, 678 /** 679 * Any album 680 * 681 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 682 * @since 12 683 */ 684 ANY = 2147483647 685 } 686 687 /** 688 * Defines the abstract interface of albums. 689 * 690 * @interface AbsAlbum 691 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 692 * @since 12 693 */ 694 interface AbsAlbum extends lang.ISendable { 695 /** 696 * Album type 697 * 698 * @type { AlbumType } 699 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 700 * @since 12 701 */ 702 readonly albumType: AlbumType; 703 /** 704 * Album subtype 705 * 706 * @type { AlbumSubtype } 707 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 708 * @since 12 709 */ 710 readonly albumSubtype: AlbumSubtype; 711 /** 712 * Album name. 713 * 714 * @type { string } 715 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 716 * @since 12 717 */ 718 albumName: string; 719 /** 720 * Album uri. 721 * 722 * @type { string } 723 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 724 * @since 12 725 */ 726 readonly albumUri: string; 727 /** 728 * Number of assets in the album 729 * 730 * @type { number } 731 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 732 * @since 12 733 */ 734 readonly count: number; 735 /** 736 * Cover uri for the album 737 * 738 * @type { string } 739 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 740 * @since 12 741 */ 742 readonly coverUri: string; 743 /** 744 * Obtains media assets. This API uses a promise to return the result. 745 * 746 * @permission ohos.permission.READ_IMAGEVIDEO 747 * @param { FetchOptions } options - Options for fetching the media assets. 748 * @returns { Promise<FetchResult<PhotoAsset>> } Returns the fetch result 749 * @throws { BusinessError } 201 - Permission denied. 750 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 751 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 752 * @throws { BusinessError } 14000011 - Internal system error 753 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 754 * @since 12 755 */ 756 getAssets(options: photoAccessHelper.FetchOptions): Promise<FetchResult<PhotoAsset>>; 757 /** 758 * Fetch shared photo assets in an album. 759 * 760 * @permission ohos.permission.ACCESS_MEDIALIB_THUMB_DB 761 * @param { FetchOptions } options - Fetch options. 762 * @returns { Array<SharedPhotoAsset> } Returns the shared photo assets 763 * @throws { BusinessError } 201 - Permission denied 764 * @throws { BusinessError } 202 - Called by non-system application 765 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 766 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 767 * @throws { BusinessError } 14000011 - Internal system error 768 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 769 * @systemapi 770 * @since 14 771 */ 772 getSharedPhotoAssets(options: photoAccessHelper.FetchOptions): Array<SharedPhotoAsset>; 773 } 774 775 /** 776 * Defines the album. 777 * 778 * @interface Album 779 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 780 * @since 12 781 */ 782 interface Album extends AbsAlbum { 783 /** 784 * Number of image assets in the album 785 * 786 * @type { ?number } 787 * @readonly 788 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 789 * @since 12 790 */ 791 readonly imageCount?: number; 792 /** 793 * Number of video assets in the album 794 * 795 * @type { ?number } 796 * @readonly 797 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 798 * @since 12 799 */ 800 readonly videoCount?: number; 801 /** 802 * Commits the modification on the album attributes to the database. This API uses a promise to return the result. 803 * 804 * @permission ohos.permission.WRITE_IMAGEVIDEO 805 * @returns { Promise<void> } Returns void 806 * @throws { BusinessError } 201 - Permission denied. 807 * @throws { BusinessError } 14000011 - Internal system error 808 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 809 * @since 12 810 */ 811 commitModify(): Promise<void>; 812 /** 813 * Converts this Sendable album to a non-Sendable album. 814 * 815 * @returns { photoAccessHelper.Album } Returns the instance if the operation is successful. 816 * @throws { BusinessError } 201 - Permission denied. 817 * @throws { BusinessError } 14000011 - Internal system error 818 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 819 * @since 12 820 */ 821 convertToPhotoAlbum(): photoAccessHelper.Album; 822 /** 823 * Obtains the face identifier on the cover of a portrait album or group photo album. 824 * 825 * @permission ohos.permission.READ_IMAGEVIDEO 826 * @returns { Promise<string> } Returns tag_id if portrait album, Returns group_tag if group photo album, 827 * <br>Returns empty if not found. 828 * @throws { BusinessError } 201 - Permission denied 829 * @throws { BusinessError } 202 - Called by non-system application 830 * @throws { BusinessError } 14000011 - Internal system error 831 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 832 * @systemapi 833 * @since 13 834 */ 835 getFaceId(): Promise<string>; 836 } 837 838 /** 839 * Defines the shared photo asset 840 * 841 * @interface SharedPhotoAsset 842 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 843 * @systemapi 844 * @since 14 845 */ 846 interface SharedPhotoAsset extends lang.ISendable { 847 /** 848 * File id of photo asset 849 * 850 * @type { number } 851 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 852 * @systemapi 853 * @since 14 854 */ 855 fileId: number; 856 /** 857 * URI of photo asset 858 * 859 * @type { string } 860 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 861 * @systemapi 862 * @since 14 863 */ 864 uri: string; 865 /** 866 * Path data of photo asset 867 * 868 * @type { string } 869 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 870 * @systemapi 871 * @since 14 872 */ 873 data: string; 874 /** 875 * Media type of photo asset 876 * 877 * @type { PhotoType } 878 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 879 * @systemapi 880 * @since 14 881 */ 882 mediaType: PhotoType; 883 /** 884 * Display name of photo asset 885 * 886 * @type { string } 887 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 888 * @systemapi 889 * @since 14 890 */ 891 displayName: string; 892 /** 893 * Size of photo asset 894 * 895 * @type { number } 896 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 897 * @systemapi 898 * @since 14 899 */ 900 size: number; 901 /** 902 * Added date of photo asset 903 * 904 * @type { number } 905 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 906 * @systemapi 907 * @since 14 908 */ 909 dateAdded: number; 910 /** 911 * Modify date of photo asset 912 * 913 * @type { number } 914 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 915 * @systemapi 916 * @since 14 917 */ 918 dateModified: number; 919 /** 920 * Duration of video photo asset 921 * 922 * @type { number } 923 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 924 * @systemapi 925 * @since 14 926 */ 927 duration: number; 928 /** 929 * Width of photo asset 930 * 931 * @type { number } 932 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 933 * @systemapi 934 * @since 14 935 */ 936 width: number; 937 /** 938 * Height of photo asset 939 * 940 * @type { number } 941 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 942 * @systemapi 943 * @since 14 944 */ 945 height: number; 946 /** 947 * DateTaken of photo asset 948 * 949 * @type { number } 950 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 951 * @systemapi 952 * @since 14 953 */ 954 dateTaken: number; 955 /** 956 * Orientation of photo asset 957 * 958 * @type { number } 959 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 960 * @systemapi 961 * @since 14 962 */ 963 orientation: number; 964 /** 965 * Favorite state of photo asset 966 * 967 * @type { boolean } 968 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 969 * @systemapi 970 * @since 14 971 */ 972 isFavorite: boolean; 973 /** 974 * Title of photo asset 975 * 976 * @type { string } 977 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 978 * @systemapi 979 * @since 14 980 */ 981 title: string; 982 /** 983 * Position of photo asset 984 * 985 * @type { PositionType } 986 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 987 * @systemapi 988 * @since 14 989 */ 990 position: PositionType; 991 /** 992 * Trashed date of photo asset 993 * 994 * @type { number } 995 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 996 * @systemapi 997 * @since 14 998 */ 999 dateTrashed: number; 1000 /** 1001 * Hidden state of photo asset 1002 * 1003 * @type { boolean } 1004 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1005 * @systemapi 1006 * @since 14 1007 */ 1008 hidden: boolean; 1009 /** 1010 * User comment info of photo asset 1011 * 1012 * @type { string } 1013 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1014 * @systemapi 1015 * @since 14 1016 */ 1017 userComment: string; 1018 /** 1019 * Camera shot key of photo asset 1020 * 1021 * @type { string } 1022 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1023 * @systemapi 1024 * @since 14 1025 */ 1026 cameraShotKey: string; 1027 /** 1028 * The year of the file created 1029 * 1030 * @type { string } 1031 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1032 * @systemapi 1033 * @since 14 1034 */ 1035 dateYear: string; 1036 /** 1037 * The month of the file created 1038 * 1039 * @type { string } 1040 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1041 * @systemapi 1042 * @since 14 1043 */ 1044 dateMonth: string; 1045 /** 1046 * The day of the file created 1047 * 1048 * @type { string } 1049 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1050 * @systemapi 1051 * @since 14 1052 */ 1053 dateDay: string; 1054 /** 1055 * Pending state of the asset, true means asset is pending 1056 * 1057 * @type { boolean } 1058 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1059 * @systemapi 1060 * @since 14 1061 */ 1062 pending: boolean; 1063 /** 1064 * Added date of photo asset in milliseconds 1065 * 1066 * @type { number } 1067 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1068 * @systemapi 1069 * @since 14 1070 */ 1071 dateAddedMs: number; 1072 /** 1073 * Modified time of the asset in milliseconds 1074 * 1075 * @type { number } 1076 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1077 * @systemapi 1078 * @since 14 1079 */ 1080 dateModifiedMs: number; 1081 /** 1082 * Trashed time of the asset in milliseconds 1083 * 1084 * @type { number } 1085 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1086 * @systemapi 1087 * @since 14 1088 */ 1089 dateTrashedMs: number; 1090 /** 1091 * Subtype of photo asset 1092 * 1093 * @type { PhotoSubtype } 1094 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1095 * @systemapi 1096 * @since 14 1097 */ 1098 subtype: PhotoSubtype; 1099 /** 1100 * Effect mode of moving photo 1101 * 1102 * @type { MovingPhotoEffectMode } 1103 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1104 * @systemapi 1105 * @since 14 1106 */ 1107 movingPhotoEffectMode: MovingPhotoEffectMode; 1108 /** 1109 * Dynamic range type of the asset 1110 * 1111 * @type { DynamicRangeType } 1112 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1113 * @systemapi 1114 * @since 14 1115 */ 1116 dynamicRangeType: DynamicRangeType; 1117 /** 1118 * Ready state of thumbnail 1119 * 1120 * @type { boolean } 1121 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1122 * @systemapi 1123 * @since 14 1124 */ 1125 thumbnailReady: boolean; 1126 /** 1127 * Width and height information of lcd picture 1128 * 1129 * @type { string } 1130 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1131 * @systemapi 1132 * @since 14 1133 */ 1134 lcdSize: string; 1135 /** 1136 * Width and height information of thumbnail picture 1137 * 1138 * @type { string } 1139 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1140 * @systemapi 1141 * @since 14 1142 */ 1143 thmSize: string; 1144 /** 1145 * modified time of thumbnail status 1146 * 1147 * @type { number } 1148 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1149 * @systemapi 1150 * @since 14 1151 */ 1152 thumbnailModifiedMs: number; 1153 /** 1154 * visibility of thumbnails 1155 * 1156 * @type { ThumbnailVisibility } 1157 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1158 * @systemapi 1159 * @since 14 1160 */ 1161 thumbnailVisible: ThumbnailVisibility; 1162 } 1163 1164 /** 1165 * Helper functions to access photos and albums. 1166 * 1167 * @interface PhotoAccessHelper 1168 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1169 * @atomicservice 1170 * @since 12 1171 */ 1172 interface PhotoAccessHelper extends lang.ISendable { 1173 /** 1174 * Obtains media assets. This API uses a promise to return the result. 1175 * 1176 * @permission ohos.permission.READ_IMAGEVIDEO 1177 * @param { FetchOptions } options - Options for fetching the media assets. 1178 * @returns { Promise<FetchResult<PhotoAsset>> } Returns the fetch result. 1179 * @throws { BusinessError } 201 - Permission denied. 1180 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1181 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1182 * @throws { BusinessError } 14000011 - Internal system error 1183 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1184 * @since 12 1185 */ 1186 getAssets(options: photoAccessHelper.FetchOptions): Promise<FetchResult<PhotoAsset>>; 1187 /** 1188 * Obtains burst assets. This API uses a promise to return the result. 1189 * 1190 * @permission ohos.permission.READ_IMAGEVIDEO 1191 * @param { string } burstKey - Burst asset options. 1192 * @returns { Promise<FetchResult<PhotoAsset>> } Returns the fetch result. 1193 * @throws { BusinessError } 201 - Permission denied 1194 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1195 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1196 * @throws { BusinessError } 14000011 - Internal system error 1197 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1198 * @since 12 1199 */ 1200 getBurstAssets(burstKey: string, options: photoAccessHelper.FetchOptions): Promise<FetchResult<PhotoAsset>>; 1201 /** 1202 * Creates an asset with the specified file name. This API uses a promise to return the result. 1203 * 1204 * @permission ohos.permission.WRITE_IMAGEVIDEO 1205 * @param { string } displayName - File name of the asset to create. 1206 * @returns { Promise<PhotoAsset> } Returns the newly created asset 1207 * @throws { BusinessError } 201 - Permission denied 1208 * @throws { BusinessError } 202 - Called by non-system application. 1209 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1210 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1211 * @throws { BusinessError } 14000011 - Internal system error 1212 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1213 * @systemapi 1214 * @since 12 1215 */ 1216 createAsset(displayName: string): Promise<PhotoAsset>; 1217 /** 1218 * Create a photo asset 1219 * 1220 * @permission ohos.permission.WRITE_IMAGEVIDEO 1221 * @param { string } displayName - Asset name 1222 * @param { PhotoCreateOptions } options - Create operation 1223 * @throws { BusinessError } 201 - Permission denied 1224 * @returns { Promise<PhotoAsset> } Returns the newly created asset 1225 * @throws { BusinessError } 202 - Called by non-system application. 1226 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1227 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1228 * @throws { BusinessError } 14000011 - Internal system error 1229 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1230 * @systemapi 1231 * @since 12 1232 */ 1233 createAsset(displayName: string, options: photoAccessHelper.PhotoCreateOptions): Promise<PhotoAsset>; 1234 /** 1235 * Creates an image or video asset with the specified file type, file name extension, and options. 1236 * This API uses a promise to return the result. If the caller does not have the ohos.permission.WRITE_IMAGEVIDEO permission, 1237 * you can create a media asset by using a security component. For details, see Creating a Media Asset Using a Security Component. 1238 * 1239 * @permission ohos.permission.WRITE_IMAGEVIDEO 1240 * @param { PhotoType } photoType - Type of the file to create, which can be IMAGE or VIDEO. 1241 * @param { string } extension - File name extension, for example, 'jpg'. The value contains 1 to 255 characters. 1242 * @param { CreateOptions } [options] - Options for creating the media asset, for example, {title: 'testPhoto'}. 1243 * @returns { Promise<string> } Returns the uri of the newly created asset 1244 * @throws { BusinessError } 201 - Permission denied 1245 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1246 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1247 * @throws { BusinessError } 14000011 - Internal system error 1248 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1249 * @atomicservice 1250 * @since 12 1251 */ 1252 createAsset(photoType: PhotoType, extension: string, options?: photoAccessHelper.CreateOptions): Promise<string>; 1253 /** 1254 * Obtains albums. This API uses a promise to return the result. 1255 * 1256 * @permission ohos.permission.READ_IMAGEVIDEO 1257 * @param { FetchOptions } [options] - Options for fetching the albums. 1258 * @returns { Promise<FetchResult<Album>> } - Returns the fetch result 1259 * @throws { BusinessError } 201 - Permission denied 1260 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1261 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1262 * @throws { BusinessError } 14000011 - Internal system error 1263 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1264 * @since 12 1265 */ 1266 getAlbums(options: photoAccessHelper.FetchOptions): Promise<FetchResult<Album>>; 1267 /** 1268 * Obtains albums based on the specified options and album type. This API uses a promise to return the result. 1269 * 1270 * @permission ohos.permission.READ_IMAGEVIDEO 1271 * @param { AlbumType } type - Type of the albums to obtain. 1272 * @param { AlbumSubtype } subtype - Subtype of the album. 1273 * @param { FetchOptions } [options] - Options for fetching the albums. 1274 * If this parameter is not specified, the albums are obtained based on the album type by default. 1275 * @returns { Promise<FetchResult<Album>> } - Returns the fetch result 1276 * @throws { BusinessError } 201 - Permission denied 1277 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1278 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1279 * @throws { BusinessError } 14000011 - Internal system error 1280 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1281 * @since 12 1282 */ 1283 getAlbums( 1284 type: AlbumType, 1285 subtype: AlbumSubtype, 1286 options?: photoAccessHelper.FetchOptions 1287 ): Promise<FetchResult<Album>>; 1288 /** 1289 * Obtains hidden albums based on the specified display mode and retrieval options. 1290 * This API uses a promise to return the result. 1291 * 1292 * @permission ohos.permission.READ_IMAGEVIDEO and ohos.permission.MANAGE_PRIVATE_PHOTOS 1293 * @param { HiddenPhotosDisplayMode } mode - Display mode of hidden albums. 1294 * @param { FetchOptions } [options] - Options for retrieving the albums. 1295 * If this parameter is not specified, the albums are retrieved based on the display mode. 1296 * @returns { Promise<FetchResult<Album>> } Returns fetchResult of albums containing hidden assets. 1297 * @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken. 1298 * @throws { BusinessError } 202 - Called by non-system application 1299 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1300 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1301 * @throws { BusinessError } 14000011 - Internal system error 1302 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1303 * @systemapi 1304 * @since 12 1305 */ 1306 getHiddenAlbums( 1307 mode: photoAccessHelper.HiddenPhotosDisplayMode, 1308 options?: photoAccessHelper.FetchOptions 1309 ): Promise<FetchResult<Album>>; 1310 /** 1311 * Releases this PhotoAccessHelper instance. This API uses a promise to return the result. 1312 * Call this API when the APIs of the PhotoAccessHelper instance are no longer used. 1313 * 1314 * @returns { Promise<void> } Returns void 1315 * @throws { BusinessError } 14000011 - Internal system error 1316 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1317 * @since 12 1318 */ 1319 release(): Promise<void>; 1320 /** 1321 * Fetch shared photo assets. 1322 * 1323 * @permission ohos.permission.ACCESS_MEDIALIB_THUMB_DB 1324 * @param { FetchOptions } options - Fetch options. 1325 * @returns { Array<SharedPhotoAsset> } Returns the shared photo assets 1326 * @throws { BusinessError } 201 - Permission denied 1327 * @throws { BusinessError } 202 - Called by non-system application 1328 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1329 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1330 * @throws { BusinessError } 14000011 - Internal system error 1331 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 1332 * @systemapi 1333 * @since 14 1334 */ 1335 getSharedPhotoAssets(options: photoAccessHelper.FetchOptions): Array<SharedPhotoAsset>; 1336 } 1337} 1338 1339export default sendablePhotoAccessHelper;