1# Interface (PhotoAsset) 2<!--Kit: Media Library Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @yixiaoff--> 5<!--SE: @liweilu1--> 6<!--TSE: @xchaosioda--> 7 8> **NOTE** 9> 10> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 11 12PhotoAsset provides APIs for encapsulating file asset attributes. 13 14## Modules to Import 15 16```ts 17import { photoAccessHelper } from '@kit.MediaLibraryKit'; 18``` 19 20## Properties 21 22**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 23 24| Name | Type | Readable| Writable| Description | 25| ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ | 26| uri | string | Yes | No | Media asset URI, for example, **file://media/Photo/1/IMG_datetime_0001/displayName.jpg**. For details, see [Media File URI](../../file-management/user-file-uri-intro.md#media-file-uri).<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 27| photoType | [PhotoType](arkts-apis-photoAccessHelper-e.md#phototype) | Yes | No | Type of the file.<br>**Atomic service API**: This API can be used in atomic services since API version 20. | 28| displayName | string | Yes | No | File name, including the file name extension, to display. The value contains 1 to 255 characters.<br>**Atomic service API**: This API can be used in atomic services since API version 20. | 29 30## get 31 32get(member: string): MemberType 33 34Obtains a **PhotoAsset** member parameter. 35 36**Atomic service API**: This API can be used in atomic services since API version 20. 37 38**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 39 40**Parameters** 41 42| Name | Type | Mandatory | Description | 43| -------- | ------------------------- | ---- | ----- | 44| member | string | Yes | Name of the member parameter to obtain. Except **'uri'**, **'media_type'**, **'subtype'**, and **'display_name'**, you need to pass in [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys) in **fetchColumns**. For example, to obtain the title, pass in **fetchColumns: ['title']**.| 45 46**Return value** 47 48| Type | Description | 49| ------------------- | --------------------------------- | 50| [MemberType](arkts-apis-photoAccessHelper-t.md#membertype) | **PhotoAsset** member parameter obtained.| 51 52**Error codes** 53 54For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 55 56| ID| Error Message| 57| -------- | ---------------------------------------- | 58| 13900020 | Invalid argument. | 59| 14000014 | The provided member must be a property name of PhotoKey. | 60 61**Example** 62 63For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 64 65```ts 66import { dataSharePredicates } from '@kit.ArkData'; 67 68async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 69 console.info('photoAssetGetDemo'); 70 try { 71 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 72 let fetchOption: photoAccessHelper.FetchOptions = { 73 fetchColumns: ['title'], 74 predicates: predicates 75 }; 76 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 77 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 78 let title: photoAccessHelper.PhotoKeys = photoAccessHelper.PhotoKeys.TITLE; 79 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title.toString()); 80 console.info('photoAsset Get photoAssetTitle = ', photoAssetTitle); 81 } catch (err) { 82 console.error(`release failed. error: ${err.code}, ${err.message}`); 83 } 84} 85``` 86 87## set 88 89set(member: string, value: string): void 90 91Sets a **PhotoAsset** member parameter. 92 93**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 94 95**Parameters** 96 97| Name | Type | Mandatory | Description | 98| -------- | ------------------------- | ---- | ----- | 99| member | string | Yes | Name of the member parameter to set, for example, [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys).TITLE. The value contains 1 to 255 characters.| 100| value | string | Yes | Value of the member parameter to set. Only the value of [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys).TITLE can be changed. The title must meet the following requirements:<br>- It does not contain a file name extension.<br>- The file name, which is in the format of title+file name extension, does not exceed 255 characters.<br>- The title does not contain any of the following characters:\ / : * ? " ' ` < > \| { } [ ] | 101 102**Error codes** 103 104For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 105 106| ID| Error Message| 107| -------- | ---------------------------------------- | 108| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 109| 13900020 | Invalid argument. | 110| 14000014 | The provided member must be a property name of PhotoKey. | 111 112**Example** 113 114For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 115 116```ts 117import { dataSharePredicates } from '@kit.ArkData'; 118 119async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 120 console.info('photoAssetSetDemo'); 121 try { 122 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 123 let fetchOption: photoAccessHelper.FetchOptions = { 124 fetchColumns: ['title'], 125 predicates: predicates 126 }; 127 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 128 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 129 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 130 photoAsset.set(title, 'newTitle'); 131 } catch (err) { 132 console.error(`release failed. error: ${err.code}, ${err.message}`); 133 } 134} 135``` 136 137## commitModify 138 139commitModify(callback: AsyncCallback<void>): void 140 141Commits the modification on the file metadata to the database. This API uses an asynchronous callback to return the result. 142 143**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO 144 145**Atomic service API**: This API can be used in atomic services since API version 11. 146 147**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 148 149**Parameters** 150 151| Name | Type | Mandatory | Description | 152| -------- | ------------------------- | ---- | ----- | 153| callback | AsyncCallback<void> | Yes | Callback that returns no value.| 154 155**Error codes** 156 157For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 158 159If error code 14000001 is returned, refer to [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys) to learn about the format and length requirements of the file name. 160 161If error code 13900012 is returned, follow the instructions provided in [Before You Start](../../media/medialibrary/photoAccessHelper-preparation.md). 162 163| ID| Error Message| 164| -------- | ---------------------------------------- | 165| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 166| 201 | Permission denied. | 167| 13900020 | Invalid argument. | 168| 14000001 | Invalid display name. | 169| 14000011 | System inner fail. | 170 171**Example** 172 173For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 174 175```ts 176import { dataSharePredicates } from '@kit.ArkData'; 177 178async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 179 console.info('commitModifyDemo'); 180 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 181 let fetchOption: photoAccessHelper.FetchOptions = { 182 fetchColumns: ['title'], 183 predicates: predicates 184 }; 185 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 186 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 187 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 188 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 189 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 190 photoAsset.set(title, 'newTitle2'); 191 photoAsset.commitModify((err) => { 192 if (err === undefined) { 193 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 194 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 195 } else { 196 console.error(`commitModify failed, error: ${err.code}, ${err.message}`); 197 } 198 }); 199} 200``` 201 202## commitModify 203 204commitModify(): Promise<void> 205 206Commits the modification on the file metadata to the database. This API uses a promise to return the result. 207 208**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO 209 210**Atomic service API**: This API can be used in atomic services since API version 11. 211 212**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 213 214**Return value** 215 216| Type | Description | 217| ------------------- | ---------- | 218| Promise<void> | Promise that returns no value.| 219 220**Error codes** 221 222For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 223 224If error code 14000001 is returned, refer to [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys) to learn about the format and length requirements of the file name. 225 226In API version 13 and earlier versions, if the caller does not have the required permission, error code 13900012 is returned. Starting from API version 14, the same situation raises error code 201. 227 228| ID| Error Message| 229| -------- | ---------------------------------------- | 230| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 231| 201 | Permission denied. | 232| 13900020 | Invalid argument. | 233| 14000001 | Invalid display name. | 234| 14000011 | System inner fail. | 235 236**Example** 237 238For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 239 240```ts 241import { dataSharePredicates } from '@kit.ArkData'; 242 243async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 244 console.info('commitModifyDemo'); 245 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 246 let fetchOption: photoAccessHelper.FetchOptions = { 247 fetchColumns: ['title'], 248 predicates: predicates 249 }; 250 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 251 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 252 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 253 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 254 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 255 photoAsset.set(title, 'newTitle3'); 256 try { 257 await photoAsset.commitModify(); 258 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 259 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 260 } catch (err) { 261 console.error(`release failed. error: ${err.code}, ${err.message}`); 262 } 263} 264``` 265 266## close<sup>(deprecated)</sup> 267 268close(fd: number, callback: AsyncCallback<void>): void 269 270Closes a file. This API uses an asynchronous callback to return the result. 271 272> **NOTE** 273> 274> This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided, and the corresponding **close** API is also deprecated. 275 276**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 277 278**Parameters** 279 280| Name | Type | Mandatory | Description | 281| -------- | ------------------------- | ---- | ----- | 282| fd | number | Yes | FD of the file to close.| 283| callback | AsyncCallback<void> | Yes | Callback that returns no value.| 284 285**Error codes** 286 287For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 288 289| ID| Error Message| 290| -------- | ---------------------------------------- | 291| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 292| 13900020 | Invalid argument. | 293| 14000011 | System inner fail. | 294 295**Example** 296 297For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 298 299```ts 300import { dataSharePredicates } from '@kit.ArkData'; 301 302async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 303 console.info('closeDemo'); 304 try { 305 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 306 let fetchOption: photoAccessHelper.FetchOptions = { 307 fetchColumns: [], 308 predicates: predicates 309 }; 310 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 311 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 312 let fd: number = await photoAsset.open('rw'); 313 console.info('file fd', fd); 314 photoAsset.close(fd, (err) => { 315 if (err === undefined) { 316 console.info('asset close succeed.'); 317 } else { 318 console.error(`close failed, error: ${err.code}, ${err.message}`); 319 } 320 }); 321 } catch (err) { 322 console.error(`close failed, error: ${err.code}, ${err.message}`); 323 } 324} 325``` 326 327## close<sup>(deprecated)</sup> 328 329close(fd: number): Promise<void> 330 331Closes a file. This API uses a promise to return the result. 332 333> **NOTE** 334> 335> This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided, and the corresponding **close** API is also deprecated. 336 337**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 338 339**Parameters** 340 341| Name | Type | Mandatory | Description | 342| ---- | ------ | ---- | ----- | 343| fd | number | Yes | FD of the file to close.| 344 345**Return value** 346 347| Type | Description | 348| ------------------- | ---------- | 349| Promise<void> | Promise that returns no value.| 350 351**Error codes** 352 353For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 354 355| ID| Error Message| 356| -------- | ---------------------------------------- | 357| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 358| 13900020 | Invalid argument. | 359| 14000011 | System inner fail. | 360 361**Example** 362 363For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 364 365```ts 366import { dataSharePredicates } from '@kit.ArkData'; 367 368async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 369 console.info('closeDemo'); 370 try { 371 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 372 let fetchOption: photoAccessHelper.FetchOptions = { 373 fetchColumns: [], 374 predicates: predicates 375 }; 376 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 377 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 378 let fd = await asset.open('rw'); 379 console.info('file fd', fd); 380 await asset.close(fd); 381 console.info('asset close succeed.'); 382 } catch (err) { 383 console.error(`close failed, error: ${err.code}, ${err.message}`); 384 } 385} 386``` 387 388## getThumbnail 389 390getThumbnail(callback: AsyncCallback<image.PixelMap>): void 391 392Obtains the thumbnail of this file. This API uses an asynchronous callback to return the result. 393 394**Required permissions**: ohos.permission.READ_IMAGEVIDEO 395 396**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 397 398**Parameters** 399 400| Name | Type | Mandatory | Description | 401| -------- | ----------------------------------- | ---- | ---------------- | 402| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Yes | Callback used to return the PixelMap of the thumbnail.| 403 404**Error codes** 405 406For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 407 408If error code 13900012 is returned, follow the instructions provided in [Before You Start](../../media/medialibrary/photoAccessHelper-preparation.md). 409 410| ID| Error Message| 411| -------- | ---------------------------------------- | 412| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 413| 13900012 | Permission denied. | 414| 13900020 | Invalid argument. | 415| 14000011 | System inner fail. | 416 417**Example** 418 419For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 420 421```ts 422import { dataSharePredicates } from '@kit.ArkData'; 423 424async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 425 console.info('getThumbnailDemo'); 426 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 427 let fetchOption: photoAccessHelper.FetchOptions = { 428 fetchColumns: [], 429 predicates: predicates 430 }; 431 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 432 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 433 console.info('asset displayName = ', asset.displayName); 434 asset.getThumbnail((err, pixelMap) => { 435 if (err === undefined) { 436 console.info('getThumbnail successful ' + pixelMap); 437 } else { 438 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 439 } 440 }); 441} 442``` 443 444## getThumbnail 445 446getThumbnail(size: image.Size, callback: AsyncCallback<image.PixelMap>): void 447 448Obtains the file thumbnail of the given size. This API uses an asynchronous callback to return the result. 449 450**Required permissions**: ohos.permission.READ_IMAGEVIDEO 451 452**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 453 454**Parameters** 455 456| Name | Type | Mandatory | Description | 457| -------- | ----------------------------------- | ---- | ---------------- | 458| size | [image.Size](../apis-image-kit/arkts-apis-image-i.md#size) | Yes | Size of the thumbnail. | 459| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Yes | Callback used to return the PixelMap of the thumbnail.| 460 461**Error codes** 462 463For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 464 465If error code 13900012 is returned, follow the instructions provided in [Before You Start](../../media/medialibrary/photoAccessHelper-preparation.md). 466 467| ID| Error Message| 468| -------- | ---------------------------------------- | 469| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 470| 13900012 | Permission denied. | 471| 13900020 | Invalid argument. | 472| 14000011 | System inner fail. | 473 474**Example** 475 476For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 477 478```ts 479import { dataSharePredicates } from '@kit.ArkData'; 480import { image } from '@kit.ImageKit'; 481 482async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 483 console.info('getThumbnailDemo'); 484 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 485 let fetchOption: photoAccessHelper.FetchOptions = { 486 fetchColumns: [], 487 predicates: predicates 488 }; 489 let size: image.Size = { width: 720, height: 720 }; 490 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 491 let asset = await fetchResult.getFirstObject(); 492 console.info('asset displayName = ', asset.displayName); 493 asset.getThumbnail(size, (err, pixelMap) => { 494 if (err === undefined) { 495 console.info('getThumbnail successful ' + pixelMap); 496 } else { 497 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 498 } 499 }); 500} 501``` 502 503## getThumbnail 504 505getThumbnail(size?: image.Size): Promise<image.PixelMap> 506 507Obtains the file thumbnail of the given size. This API uses a promise to return the result. 508 509**Required permissions**: ohos.permission.READ_IMAGEVIDEO 510 511**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 512 513**Parameters** 514 515| Name | Type | Mandatory | Description | 516| ---- | -------------- | ---- | ----- | 517| size | [image.Size](../apis-image-kit/arkts-apis-image-i.md#size) | No | Size of the thumbnail.| 518 519**Return value** 520 521| Type | Description | 522| ----------------------------- | --------------------- | 523| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return the PixelMap of the thumbnail.| 524 525**Error codes** 526 527For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 528 529If error code 13900012 is returned, follow the instructions provided in [Before You Start](../../media/medialibrary/photoAccessHelper-preparation.md). 530 531| ID| Error Message| 532| -------- | ---------------------------------------- | 533| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 534| 13900012 | Permission denied. | 535| 13900020 | Invalid argument. | 536| 14000011 | System inner fail. | 537 538**Example** 539 540For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 541 542```ts 543import { dataSharePredicates } from '@kit.ArkData'; 544import { image } from '@kit.ImageKit'; 545import { BusinessError } from '@kit.BasicServicesKit'; 546 547async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 548 console.info('getThumbnailDemo'); 549 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 550 let fetchOption: photoAccessHelper.FetchOptions = { 551 fetchColumns: [], 552 predicates: predicates 553 }; 554 let size: image.Size = { width: 720, height: 720 }; 555 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 556 let asset = await fetchResult.getFirstObject(); 557 console.info('asset displayName = ', asset.displayName); 558 asset.getThumbnail(size).then((pixelMap) => { 559 console.info('getThumbnail successful ' + pixelMap); 560 }).catch((err: BusinessError) => { 561 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 562 }); 563} 564``` 565 566## clone<sup>14+</sup> 567 568clone(title: string): Promise<PhotoAsset> 569 570Clones a media asset. The file name can be set, but the file type cannot be changed. 571 572**Required permissions**: ohos.permission.WRITE\_IMAGEVIDEO 573 574**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 575 576**Parameters** 577 578| Name | Type | Mandatory | Description | 579| ---------- | ------- | ---- | ---------------------------------- | 580| title| string | Yes | Title of the cloned asset. The title must meet the following requirements:<br>- It does not contain a file name extension.<br>- The file name, which is in the format of title+file name extension, does not exceed 255 characters.<br>- The title does not contain any of the following characters:\ / : * ? " ' ` < > \| { } [ ] | 581 582**Return value** 583 584| Type | Description | 585| ------------------- | ----------------------- | 586| Promise<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | Promise used to return the [PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md) instance.| 587 588**Error codes** 589 590For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 591 592| ID | Error Message | 593| :------- | :-------------------------------- | 594| 201 | Permission denied. | 595| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 596| 14000011 | Internal system error. It is recommended to retry and check the logs.Possible causes: 1. Database corrupted; 2. The file system is abnormal; 3. The IPC request timed out. | 597 598**Example** 599 600For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 601 602```ts 603import { dataSharePredicates } from '@kit.ArkData'; 604import { systemDateTime } from '@kit.BasicServicesKit'; 605 606async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 607 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 608 let fetchOptions: photoAccessHelper.FetchOptions = { 609 fetchColumns: [], 610 predicates: predicates 611 }; 612 try { 613 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 614 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 615 let title: string = systemDateTime.getTime().toString(); 616 let newAsset: photoAccessHelper.PhotoAsset = await photoAsset.clone(title); 617 console.info('get new asset successfully'); 618 } catch (error) { 619 console.error(`failed to get new asset. message = ${error.code}, ${error.message}`); 620 } 621} 622``` 623 624## getReadOnlyFd<sup>(deprecated)</sup> 625 626getReadOnlyFd(callback: AsyncCallback<number>): void 627 628Opens this file in read-only mode. This API uses an asynchronous callback to return the result. 629 630> **NOTE** 631> 632> - This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided. 633> 634> - The returned FD must be closed when it is not required. 635 636**Required permissions**: ohos.permission.READ_IMAGEVIDEO 637 638**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 639 640**Parameters** 641 642| Name | Type | Mandatory | Description | 643| -------- | --------------------------- | ---- | ----------------------------------- | 644| callback | AsyncCallback<number> | Yes | Callback used to return the file descriptor (FD) of the file opened. | 645 646**Error codes** 647 648For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 649 650In API version 13 and earlier versions, if the caller does not have the required permission, error code 13900012 is returned. Starting from API version 14, the same situation raises error code 201. 651 652| ID| Error Message| 653| -------- | ---------------------------------------- | 654| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 655| 201 | Permission denied. | 656| 13900020 | Invalid argument. | 657| 14000011 | System inner fail. | 658 659**Example** 660 661For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 662 663```ts 664import { dataSharePredicates } from '@kit.ArkData'; 665 666async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 667 console.info('getReadOnlyFdDemo'); 668 // Ensure that there are images and video files in the device. 669 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 670 let fetchOptions: photoAccessHelper.FetchOptions = { 671 fetchColumns: [], 672 predicates: predicates 673 }; 674 let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 675 let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject(); 676 photoAsset.getReadOnlyFd((err, fd) => { 677 if (fd !== undefined) { 678 console.info('File fd' + fd); 679 photoAsset.close(fd); 680 } else { 681 console.error(`getReadOnlyFd err: ${err.code}, ${err.message}`); 682 } 683 }); 684} 685``` 686 687## getReadOnlyFd<sup>(deprecated)</sup> 688 689getReadOnlyFd(): Promise<number> 690 691Opens this file in read-only mode. This API uses a promise to return the result. 692 693> **NOTE** 694> 695> - This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided. 696> 697> - The returned FD must be closed when it is not required. 698 699**Required permissions**: ohos.permission.READ_IMAGEVIDEO 700 701**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 702 703**Return value** 704 705| Type | Description | 706| --------------------- | ------------- | 707| Promise<number> | Promise used to return the FD of the file opened.| 708 709**Error codes** 710 711For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 712 713In API version 13 and earlier versions, if the caller does not have the required permission, error code 13900012 is returned. Starting from API version 14, the same situation raises error code 201. 714 715| ID| Error Message| 716| -------- | ---------------------------------------- | 717| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 718| 201 | Permission denied. | 719| 13900020 | Invalid argument. | 720| 14000011 | System inner fail. | 721 722**Example** 723 724For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 725 726```ts 727import { dataSharePredicates } from '@kit.ArkData'; 728 729async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 730 console.info('getReadOnlyFdDemo'); 731 try { 732 // Ensure that there are images and video files in the device. 733 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 734 let fetchOptions: photoAccessHelper.FetchOptions = { 735 fetchColumns: [], 736 predicates: predicates 737 }; 738 let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 739 let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject(); 740 let fd: number = await photoAsset.getReadOnlyFd(); 741 if (fd !== undefined) { 742 console.info('File fd' + fd); 743 photoAsset.close(fd); 744 } else { 745 console.error('getReadOnlyFd fail'); 746 } 747 } catch (err) { 748 console.error(`getReadOnlyFd demo err: ${err.code}, ${err.message}`); 749 } 750} 751``` 752
