This is an automated email from the ASF dual-hosted git repository. GitToTheHub pushed a commit to branch pr-ios-exclude-CDVAssetLibrary-on-deploymentTarget-ios-26 in repository https://gitbox.apache.org/repos/asf/cordova-plugin-file.git
commit 8d2ac8e78f5073ac5fda35ad0723c70e3fb06a9c Author: Manuel Beck <[email protected]> AuthorDate: Tue Aug 4 08:59:46 2026 +0200 fix(ios): exlude `CDVAssetLibrary` on `deploymentTarget` 26, add documentation - The Assets Library by Apple is deprecated since iOS 9 and removed completly when targeting iOS 26. - Suppress deprecation warnings for `CDVAssetLibrary.m` - Document `CDVAssetLibraryFilesystem.h` - Add documentation to `README.md` about `asset-library://...` urls --- README.md | 15 +++++++++++++++ src/ios/CDVAssetLibraryFilesystem.h | 18 ++++++++++++++++++ src/ios/CDVAssetLibraryFilesystem.m | 15 +++++++++++++++ src/ios/CDVFile.m | 16 ++++++++++++++-- 4 files changed, 62 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bfa3679..48d0b8e 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,19 @@ the `cordova.file.*` properties map to physical paths on a real device. necessary, but do not rely on this. You should clear this directory as appropriate for your application. +#### iOS `assets-library` compatibility root + +On iOS, this plugin also registers a read-only `assets-library` filesystem root. It maps native `asset-library://...` URLs to internal `cdvfile://localhost/assets-library/...` URLs so they can be resolved through the File plugin APIs. This behavior is implemented by the iOS class `CDVAssetLibraryFilesystem`. + +These URLs are legacy identifiers from Apple's deprecated [AssetsLibrary API](https://developer.apple.com/documentation/assetslibrary). The AssetsLibrary API is for accessing pictures and videos managed by the Photos application. +They typically appear when another plugin, custom native code, or older application code passes an `asset-library://` URL for an item in the user's photo library into the File plugin. + +This compatibility root is limited to reading metadata and file contents for an existing asset. Operations that would create, modify, remove, list, or otherwise manage directories are not supported for `assets-library` URLs. + +Apple has deprecated `AssetsLibrary` in favor of the Photos framework. New code should not introduce dependencies on `asset-library://` URLs. This plugin currently preserves support only as a compatibility layer for existing integrations that still provide those legacy URLs. + +When building an app with an iOS deployment target of 26.0 or later, Apple obsoletes the underlying `AssetsLibrary` APIs. In that configuration this compatibility layer is not registered and `asset-library://` URLs are not supported by this plugin. + ### Android File System Layout | Device Path | `cordova.file.*` | `AndroidExtraFileSystems` | r/w? | persistent? | OS clears | private | @@ -478,6 +491,8 @@ Otherwise it will return the app's scheme path. `cdvfile://localhost/persistent|temporary|another-fs-root*/path/to/file` can be used for platform-independent file paths. cdvfile paths are supported by core plugins - for example you can download an mp3 file to cdvfile-path via `cordova-plugin-file-transfer` and play it via `cordova-plugin-media`. +On iOS, `cdvfile://localhost/assets-library/...` is also recognized as a legacy compatibility form for native `asset-library://...` photo-library URLs. This root is read-only and exists only for older integrations that still surface `asset-library://` identifiers. + __*Note__: See [Where to Store Files](#where-to-store-files), [File System Layouts](#file-system-layouts) and [Configuring the Plugin](#configuring-the-plugin-optional) for more details about available fs roots. To use `cdvfile` as a tag' `src` you can convert it to native path via `toURL()` method of the resolved fileEntry, which you can get via `resolveLocalFileSystemURL` - see examples below. diff --git a/src/ios/CDVAssetLibraryFilesystem.h b/src/ios/CDVAssetLibraryFilesystem.h index e09e225..169cde3 100644 --- a/src/ios/CDVAssetLibraryFilesystem.h +++ b/src/ios/CDVAssetLibraryFilesystem.h @@ -22,6 +22,24 @@ extern NSString* const kCDVAssetsLibraryPrefix; extern NSString* const kCDVAssetsLibraryScheme; +/* + Compatibility filesystem for legacy iOS photo-library URLs. + + This filesystem maps native `asset-library://...` resources to the internal + `cdvfile://localhost/assets-library/...` namespace so they can be resolved by + Cordova's File plugin APIs. + + This legacy API provides access to pictures and videos managed by the + Photos application, not arbitrary document files. + + It is intentionally read-only. Write and directory-management operations are + unsupported for this filesystem root. + + The implementation is based on Apple's AssetsLibrary API, which was + deprecated in iOS 9.0, and exists to preserve behavior for older + integrations. For apps with a deployment target of 26.0 or later, + AssetsLibrary is removed and this filesystem is not registered. + */ @interface CDVAssetLibraryFilesystem : NSObject<CDVFileSystem> { } diff --git a/src/ios/CDVAssetLibraryFilesystem.m b/src/ios/CDVAssetLibraryFilesystem.m index 8486b7b..8c251e4 100644 --- a/src/ios/CDVAssetLibraryFilesystem.m +++ b/src/ios/CDVAssetLibraryFilesystem.m @@ -20,11 +20,16 @@ #import "CDVFile.h" #import "CDVAssetLibraryFilesystem.h" #import <Cordova/CDV.h> +#if __IPHONE_OS_VERSION_MIN_REQUIRED < 260000 #import <AssetsLibrary/ALAsset.h> #import <AssetsLibrary/ALAssetRepresentation.h> #import <AssetsLibrary/ALAssetsLibrary.h> +#endif #import <MobileCoreServices/MobileCoreServices.h> +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wdeprecated-declarations" + NSString* const kCDVAssetsLibraryPrefix = @"assets-library://"; NSString* const kCDVAssetsLibraryScheme = @"assets-library"; @@ -190,6 +195,7 @@ NSString* const kCDVAssetsLibraryScheme = @"assets-library"; - (void)readFileAtURL:(CDVFilesystemURL *)localURL start:(NSInteger)start end:(NSInteger)end callback:(void (^)(NSData*, NSString* mimeType, CDVFileError))callback { +#if __IPHONE_OS_VERSION_MIN_REQUIRED < 260000 ALAssetsLibraryAssetForURLResultBlock resultBlock = ^(ALAsset* asset) { if (asset) { // We have the asset! Get the data and send it off. @@ -214,10 +220,14 @@ NSString* const kCDVAssetsLibraryScheme = @"assets-library"; ALAssetsLibrary* assetsLibrary = [[ALAssetsLibrary alloc] init]; [assetsLibrary assetForURL:[self assetLibraryURLForLocalURL:localURL] resultBlock:resultBlock failureBlock:failureBlock]; +#else + callback(nil, nil, NOT_FOUND_ERR); +#endif } - (void)getFileMetadataForURL:(CDVFilesystemURL *)localURL callback:(void (^)(CDVPluginResult *))callback { +#if __IPHONE_OS_VERSION_MIN_REQUIRED < 260000 // In this case, we need to use an asynchronous method to retrieve the file. // Because of this, we can't just assign to `result` and send it at the end of the method. // Instead, we return after calling the asynchronous method and send `result` in each of the blocks. @@ -249,5 +259,10 @@ NSString* const kCDVAssetsLibraryScheme = @"assets-library"; ALAssetsLibrary* assetsLibrary = [[ALAssetsLibrary alloc] init]; [assetsLibrary assetForURL:[self assetLibraryURLForLocalURL:localURL] resultBlock:resultBlock failureBlock:failureBlock]; return; +#else + callback([CDVPluginResult resultWithStatus:CDVCommandStatus_IO_EXCEPTION messageAsString:@"assets-library URLs are not supported when the iOS deployment target is 26.0 or later."]); +#endif } @end + +#pragma clang diagnostic pop diff --git a/src/ios/CDVFile.m b/src/ios/CDVFile.m index 59e7d64..a0023a7 100644 --- a/src/ios/CDVFile.m +++ b/src/ios/CDVFile.m @@ -20,7 +20,11 @@ #import <Cordova/CDV.h> #import "CDVFile.h" #import "CDVLocalFilesystem.h" +// AssetsLibrary was deprecated in iOS 9 and is unavailable when the app's +// minimum deployment target is iOS 26 or later. +#if __IPHONE_OS_VERSION_MIN_REQUIRED < 260000 #import "CDVAssetLibraryFilesystem.h" +#endif #import <objc/message.h> static NSString* toBase64(NSData* data) { @@ -89,9 +93,12 @@ NSString* const kCDVFilesystemURLPrefix = @"cdvfile"; if (pathComponents != nil && pathComponents.count > 1) { return [pathComponents objectAtIndex:1]; } - } else if ([[uri scheme] isEqualToString:kCDVAssetsLibraryScheme]) { + } +#if __IPHONE_OS_VERSION_MIN_REQUIRED < 260000 + else if ([[uri scheme] isEqualToString:kCDVAssetsLibraryScheme]) { return @"assets-library"; } +#endif return nil; } @@ -114,9 +121,12 @@ NSString* const kCDVFilesystemURLPrefix = @"cdvfile"; return @""; } return [path substringFromIndex:slashRange.location]; - } else if ([[uri scheme] isEqualToString:kCDVAssetsLibraryScheme]) { + } +#if __IPHONE_OS_VERSION_MIN_REQUIRED < 260000 + else if ([[uri scheme] isEqualToString:kCDVAssetsLibraryScheme]) { return [[uri absoluteString] substringFromIndex:[kCDVAssetsLibraryScheme length]+2]; } +#endif return nil; } @@ -366,7 +376,9 @@ NSString* const kCDVFilesystemURLPrefix = @"cdvfile"; NSAssert(false, @"File plugin configuration error: Please set iosPersistentFileLocation in config.xml to one of \"library\" (for new applications) or \"compatibility\" (for compatibility with previous versions)"); } +#if __IPHONE_OS_VERSION_MIN_REQUIRED < 260000 [self registerFilesystem:[[CDVAssetLibraryFilesystem alloc] initWithName:@"assets-library"]]; +#endif [self registerExtraFileSystems:[self getExtraFileSystemsPreference:self.viewController] fromAvailableSet:[self getAvailableFileSystems]]; --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
