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