diff --git a/packages/path_provider/path_provider/CHANGELOG.md b/packages/path_provider/path_provider/CHANGELOG.md index 47f9da7e2deb..e1fc0658d030 100644 --- a/packages/path_provider/path_provider/CHANGELOG.md +++ b/packages/path_provider/path_provider/CHANGELOG.md @@ -1,10 +1,12 @@ -## NEXT +## 2.1.6 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10. * Updates README to reflect currently supported OS versions for the latest versions of the endorsed platform implementations. * Applications built with older versions of Flutter will continue to use compatible versions of the platform implementations. +* Documents the difference between a `null` return and an `UnsupportedError` + from `getDownloadsDirectory`. ## 2.1.5 diff --git a/packages/path_provider/path_provider/lib/path_provider.dart b/packages/path_provider/path_provider/lib/path_provider.dart index d855c260889e..1e1d299cf55c 100644 --- a/packages/path_provider/path_provider/lib/path_provider.dart +++ b/packages/path_provider/path_provider/lib/path_provider.dart @@ -217,8 +217,13 @@ Future?> getExternalStorageDirectories({ /// The returned directory is not guaranteed to exist, so clients should verify /// that it does before using it, and potentially create it if necessary. /// -/// Throws an [UnsupportedError] if this is not supported on the current -/// platform. +/// Returns `null` when the current platform supports the concept of a +/// downloads directory but no such directory is currently available. For +/// example, on Linux this can happen when `xdg-user-dir` is not installed +/// or fails when called. +/// +/// Throws an [UnsupportedError] when the current platform has no concept of +/// a downloads directory at all. Future getDownloadsDirectory() async { final String? path = await _platform.getDownloadsPath(); if (path == null) { diff --git a/packages/path_provider/path_provider/pubspec.yaml b/packages/path_provider/path_provider/pubspec.yaml index bb3acf4907cb..92b660ef2cae 100644 --- a/packages/path_provider/path_provider/pubspec.yaml +++ b/packages/path_provider/path_provider/pubspec.yaml @@ -2,7 +2,7 @@ name: path_provider description: Flutter plugin for getting commonly used locations on host platform file systems, such as the temp and app data directories. repository: https://github.com/flutter/packages/tree/main/packages/path_provider/path_provider issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22 -version: 2.1.5 +version: 2.1.6 environment: sdk: ^3.10.0 diff --git a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md index f7c254e96335..08cc4c826617 100644 --- a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md +++ b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md @@ -1,6 +1,8 @@ -## NEXT +## 2.1.3 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10. +* Documents the implementation contract for `null` versus `UnsupportedError` + return semantics on `getDownloadsPath`. ## 2.1.2 diff --git a/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart b/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart index 22a1676cc84b..8ee796bf1b36 100644 --- a/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart +++ b/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart @@ -105,6 +105,14 @@ abstract class PathProviderPlatform extends PlatformInterface { /// Path to the directory where downloaded files can be stored. /// This is typically only relevant on desktop operating systems. + /// + /// Implementations should return `null` when the platform supports the + /// concept of a downloads directory but no such directory is currently + /// available (for example, on Linux when `xdg-user-dir` is not installed + /// or fails when called). + /// + /// Implementations should throw an [UnsupportedError] when the platform + /// has no concept of a downloads directory at all. Future getDownloadsPath() { throw UnimplementedError('getDownloadsPath() has not been implemented.'); } diff --git a/packages/path_provider/path_provider_platform_interface/pubspec.yaml b/packages/path_provider/path_provider_platform_interface/pubspec.yaml index 37dd1c72b895..d65d8fe1e898 100644 --- a/packages/path_provider/path_provider_platform_interface/pubspec.yaml +++ b/packages/path_provider/path_provider_platform_interface/pubspec.yaml @@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/path_provider issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22 # NOTE: We strongly prefer non-breaking changes, even at the expense of a # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes -version: 2.1.2 +version: 2.1.3 environment: sdk: ^3.10.0