# User File URI As a unique identifier of a user file, the uniform resource identifier (URI) is usually used to specify the user file to be accessed or modified. Avoid using part of an URI for service code development. ## URI Types The URIs in the system can be classified into the following types: - Document URI: URI of a file selected or saved by the file manager started by picker, or obtained via the **fileAccess** module. For details, see [Obtaining a Document URI](#obtaining-a-document-uri). - Media file URI: URI of an image or video selected from **Gallery** by picker ; URI of an image or video obtained via the **photoAccessHelper** module; URI of an image, video, or audio file obtained via the **userFileManager** module. For details, see [Obtaining a Media File URI](#obtaining-a-media-file-uri). ![user-file-uri-intro](figures/user-file-uri-intro.png) ## Document URI ### Document URI Overview The document URIs are in the following format: 'file://docs/storage/Users/currentUser/\/test.txt' The following table describes the fields in a document URI. | URI Field | Description | | ------------- | ------------------- | | 'file://docs/storage/Users/currentUser/' | Indicates the root directory of the file manager.| | '\/' | Indicates the relative path of the file, for example, **Download/** and **Documents/**.| | 'test.txt' | Indicates the name of the file in the user file system. The supported file types vary with the file manager, for example, TXT, JPG, MP4, and MP3.| ### Obtaining a Document URI - Use **select()** or **save()** of [DocumentViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#documentviewpicker) to select or save a document. - Use **select()** or **save()** of [AudioViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#audioviewpicker) to select or save an audio file. - Use [PhotoViewPicker.save](../reference/apis-core-file-kit/js-apis-file-picker.md#photoviewpickerdeprecated) to save an image or video. The URI of the image or video saved is returned. - Use [@ohos.file.fileAccess](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md). The [FileInfo](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md#fileinfo) object contains the URI of the file or directory. Note that the APIs of [@ohos.file.fileAccess](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md) can be called only by a system application. You can obtain the document URIs of the files and folders in the following directories: - External storage directory - **Docs** directory - **Download** directory - **Desktop** directory - **Documents** directory - **Share** directory of the shared disk ### Using a Document URI Applications of the normal APL can call [@ohos.file.fs](../reference/apis-core-file-kit/js-apis-file-fs.md) APIs only to access files based on document URIs. "Permission denied" will be reported if an API of other modules is used. For details about the sample code, see [Selecting Documents](./select-user-file.md#selecting-documents) and [Saving Documents](./save-user-file.md#saving-documents). Applications of the system_basic or system_core APL can call **@ohos.file.fs** and [@ohos.file.fileAccess](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md) APIs to access files based on the URIs. To call **@ohos.file.fileAccess** APIs, the application must have the ohos.permission.FILE_ACCESS_MANAGER and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED permissions declared in **module.json5** file. "Permission denied" will be reported if an API of other modules is used. The following example walks you through on how to use **@ohos.file.fileAccess** APIs to create a document and rename the document based on the URI. 1. Use [@ohos.file.fileAccess](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md) to create a document. The document URI is returned. 2. Rename the document based on its URI. ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { Want } from '@kit.AbilityKit'; import { common } from '@kit.AbilityKit'; import { fileAccess } from '@kit.CoreFileKit'; // context is passed by EntryAbility. let context = getContext(this) as common.UIAbilityContext; async function example() { let fileAccessHelper: fileAccess.FileAccessHelper; // Obtain wantInfos by using getFileAccessAbilityInfo(). let wantInfos: Array = [ { bundleName: "com.ohos.UserFile.ExternalFileManager", abilityName: "FileExtensionAbility", }, ] try { fileAccessHelper = fileAccess.createFileAccessHelper(context, wantInfos); if (!fileAccessHelper) { console.error("createFileAccessHelper interface returns an undefined object"); } // A built-in storage directory is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // Use the URI obtained. let sourceUri: string = "file://docs/storage/Users/currentUser/Download"; let displayName: string = "file1.txt"; let fileUri: string; try { // Create a document. The URI of the document created is returned. fileUri = await fileAccessHelper.createFile(sourceUri, displayName); if (!fileUri) { console.error("createFile return undefined object"); } console.log("createFile success, fileUri: " + JSON.stringify(fileUri)); // Rename the document. The URI of the renamed document is returned. let renameUri = await fileAccessHelper.rename(fileUri, "renameFile.txt"); console.log("rename success, renameUri: " + JSON.stringify(renameUri)); } catch (err) { let error: BusinessError = err as BusinessError; console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message); } } catch (err) { let error: BusinessError = err as BusinessError; console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message); } } ``` ## Media File URI ### Media File URI Overview The URI format varies depending on the media file type. - Image URI format: 'file://media/Photo/\/IMG_datetime_0001/displayName.jpg' - Video URI format: 'file://media/Photo/\/VID_datetime_0001/displayName.mp4' - Audio file URI format: 'file://media/Audio/\/AUD_datetime_0001/displayName.mp3' The following table describes the fields in a media file URI. | URI Field | Description | | ------------- | ------------------- | | 'file://media' | Indicates a URI of a media file.| | 'Photo' | Indicates a URI of an image or video.| | 'Audio' | Indicates a URI of an audio file.| | '\' | Indicates the ID of the file after being processed in multiple tables in the database. It is not the value in the **file_id** column in the table. Do not use this ID to query a file in the database.| | 'IMG_datetime_0001' | Indicates the name of the image stored in the user file system without the file name extension.| | 'VID_datetime_0001' | Indicates the name of the video stored in the user file system without the file name extension.| | 'AUD_datetime_0001' | Indicates the name of the audio file stored in the user file system without the file name extension.| | 'displayName.jpg' | Indicates the image name displayed. You can use [userFileManager.commitModify](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#commitmodify) to rename it. Note that the URI of the new image name is also changed.| | 'displayName.mp4' | Indicates the video name displayed. You can use [userFileManager.commitModify](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#commitmodify) to rename it. Note that the URI of the new video name is also changed.| | 'displayName.mp3' | Indicates the audio file name displayed. You can use [userFileManager.commitModify](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#commitmodify) to rename it. Note that the URI of the new audio name is also changed.| ### Obtaining a Media File URI - Use [PhotoViewPicker.select](../reference/apis-core-file-kit/js-apis-file-picker.md#select) to select a media file. - Use [getAssets](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets) or [createAsset](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#createasset) of [photoAccessHelper](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md). - Use [getPhotoAssets](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#getphotoassets), [getAudioAssets](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#getaudioassets), [createAudioAsset](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#createaudioasset10), or [createPhotoAsset](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#createphotoasset) of [userFileManager](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md). ### Using a Media File URI Applications of the normal APL can call [photoAccessHelper](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md) APIs to process media files based on their URI. For details about the sample code, see [Obtaining an Image or Video by URI](../media/medialibrary/photoAccessHelper-photoviewpicker.md#obtaining-an-image-or-video-by-uri). To call the APIs, the application must have the ohos.permission.READ_IMAGEVIDEO permission. Applications of the system_basic or system_core APL can call **photoAccessHelper** and [userFileManager](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md) APIs to process media files based on their URI. For details about how to use the APIs, see the API reference document. Without the ohos.permission.READ_IMAGEVIDEO permission, the application of the normal APL can use [PhotoViewPicker.select](../reference/apis-core-file-kit/js-apis-file-picker.md#selectdeprecated-1) to obtain the URI, and use [photoAccessHelper.getAssets](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets) to obtain the **PhotoAsset** object corresponding to the URI. The **PhotoAsset** object can be used to call [getThumbnail](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getthumbnail) to obtain the thumbnail and call [get](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#get) to read certain information in [PhotoKeys](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#photokeys). The following information can be obtained from **PhotoKeys** through temporary authorization: | Name | Value | Description | | ------------- | ------------------- | ---------------------------------------------------------- | | URI | 'uri' | URI of the file. | | PHOTO_TYPE | 'media_type' | Type of the media file. | | DISPLAY_NAME | 'display_name' | File name displayed. | | SIZE | 'size' | Size of the file. | | DATE_ADDED | 'date_added' | Date when the file was added. The value is the number of seconds elapsed since the Epoch time. | | DATE_MODIFIED | 'date_modified' | Date when the file content (not the file name) was last modified. The value is the number of seconds elapsed since the Epoch time.| | DURATION | 'duration' | Duration, in ms. | | WIDTH | 'width' | Image width, in pixels. | | HEIGHT | 'height' | Image height, in pixels. | | DATE_TAKEN | 'date_taken' | Date when the photo was taken. The value is the number of seconds elapsed since the Epoch time. | | ORIENTATION | 'orientation' | Orientation of the image file. | | TITLE | 'title' | Title in the file. | The following example shows how to obtain the thumbnail and file information based on the media file URI with temporary authorization. ```ts import { picker } from '@kit.CoreFileKit'; import { photoAccessHelper } from '@kit.MediaLibraryKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { dataSharePredicates } from '@kit.ArkData'; // Define an array of URIs to hold the URIs returned by PhotoViewPicker.select. let uris: Array = []; const context = getContext(this); // Call PhotoViewPicker.select to select an image. async function photoPickerGetUri() { try { let PhotoSelectOptions = new picker.PhotoSelectOptions(); PhotoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE; PhotoSelectOptions.maxSelectNumber = 1; let photoPicker = new picker.PhotoViewPicker(); photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult: picker.PhotoSelectResult) => { console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult)); uris = PhotoSelectResult.photoUris; }).catch((err: BusinessError) => { console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err)); }); } catch (error) { let err: BusinessError = error as BusinessError; console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err)); } } async function uriGetAssets() { try { let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context); let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); // Configure search criteria to query the image based on the URI returned by PhotoViewPicker.select. predicates.equalTo('uri', uris[0]); let fetchOption: photoAccessHelper.FetchOptions = { fetchColumns: [photoAccessHelper.PhotoKeys.WIDTH, photoAccessHelper.PhotoKeys.HEIGHT, photoAccessHelper.PhotoKeys.TITLE, photoAccessHelper.PhotoKeys.DURATION], predicates: predicates }; let fetchResult: photoAccessHelper.FetchResult = await phAccessHelper.getAssets(fetchOption); // Obtain the PhotoAsset object corresponding to the URI. The file information is obtained from the PhotoAsset object. const asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); console.info('asset displayName: ', asset.displayName); console.info('asset uri: ', asset.uri); console.info('asset photoType: ', asset.photoType); console.info('asset width: ', asset.get(photoAccessHelper.PhotoKeys.WIDTH)); console.info('asset height: ', asset.get(photoAccessHelper.PhotoKeys.HEIGHT)); console.info('asset title: ' + asset.get(photoAccessHelper.PhotoKeys.TITLE)); // Obtain the thumbnail. asset.getThumbnail((err, pixelMap) => { if (err == undefined) { console.info('getThumbnail successful ' + JSON.stringify(pixelMap)); } else { console.error('getThumbnail fail', err); } }); } catch (error){ console.error('uriGetAssets failed with err: ' + JSON.stringify(error)); } } ``` ## Copying A File by URI (for System Applications Only) To copy a file to the specified directory based on the URI, perform the following: 1. Use [createFileAccessHelper](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md#fileaccesscreatefileaccesshelper) to create a **fileAccessHelper** instance. 2. Obtain **srcUri** of the file to copy. 3. Obtain **destUri** of the file. 4. Obtain the alternative file name **fileName**. 5. Use helper.[copyFile](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md#copyfile11)(srcUri, destUri, fileName) to copy the file to the specified directory. Sample code: ``` import { BusinessError } from '@kit.BasicServicesKit'; import { Want } from '@kit.AbilityKit'; import { common } from '@kit.AbilityKit'; import { fileAccess } from '@kit.CoreFileKit'; // context is passed by EntryAbility. let context = getContext(this) as common.UIAbilityContext; async function example() { let fileAccessHelper: fileAccess.FileAccessHelper; // Obtain wantInfos by using getFileAccessAbilityInfo(). let wantInfos: Array = [ { bundleName: "com.ohos.UserFile.ExternalFileManager", abilityName: "FileExtensionAbility", }, ] try { fileAccessHelper = fileAccess.createFileAccessHelper(context, wantInfos); if (!fileAccessHelper) { console.error("createFileAccessHelper interface returns an undefined object"); } // A built-in storage directory is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // Use the URI obtained. let sourceUri: string = "file://docs/storage/Users/currentUser/Download/one.txt"; // URI of the directory to which the file is copied. let destUri: string = "file://docs/storage/Users/currentUser/Documents"; // File name to use if a file name conflict occurs. let displayName: string = "file1.txt"; // URI of the file to return. let fileUri: string; try { // Copy a file and return the URI of the file generated. fileUri = await fileAccessHelper.copyFile(sourceUri, destUri, displayName); if (!fileUri) { console.error("copyFile return undefined object"); } console.log("copyFile success, fileUri: " + JSON.stringify(fileUri)); } catch (err) { let error: BusinessError = err as BusinessError; console.error("copyFile failed, errCode:" + error.code + ", errMessage:" + error.message); } } catch (err) { let error: BusinessError = err as BusinessError; console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message); } } ```