This is an automated email from the ASF dual-hosted git repository.
GitToTheHub pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-plugin-file.git
The following commit(s) were added to refs/heads/master by this push:
new 5e14b9a fix(ios): exlude `CDVAssetLibrary` on `deploymentTarget` 26,
add documentation (#660)
5e14b9a is described below
commit 5e14b9aec3756e5b3fff001605993681350f90cc
Author: Manuel Beck <[email protected]>
AuthorDate: Tue Sep 8 19:29:30 2026 +0200
fix(ios): exlude `CDVAssetLibrary` on `deploymentTarget` 26, add
documentation (#660)
- 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 8128f7f..ab1061a 100644
--- a/README.md
+++ b/README.md
@@ -149,6 +149,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 |
@@ -448,6 +461,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]
