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