Merge to master (#102)

* Added support for file types across platforms (#26)

* Added support for file types across platforms

- Added per platform file type support, so you can specify what kind of files you want the picker to support
- Updated iOS's picker to use the non-deprecated `UIDocumentPickerViewController`
- Minor tweaks, such as package updates

* Fixed an issue with the iOS implementation, where the returned path wasn't properly formatted/absolute, which in turn meant that the path wasn't valid as is.

* A few iOS specific improvements

* Get latest changes to master (#51)

* pull master into develop before merging back (#47)

* Resolved issues with referencing from NuGet package (#29)

Simplified the nuspec file to work with wildcards and fixed macOS assembly name.
Also added development NuGet feed to readme along with some other tweaks

* Project fixes (#35)

* fixed paths to NuGet packages folder; always relative to the .sln file

* converted samples solution file to VS 2017 and fixed "Deploy" flag for Android app

* ignore Android Resource designer generated files

# Conflicts:
#	.gitignore

* changes automatically applied by VS 2017 when opening iOS project file

* Added issue template

* fixes crash in Xamarin.Forms sample when user doesn't select file; also added example code in README file (#50)

* fixed picking files from the download folder; on newer devices the document ID may not be a number, but the real filename prefixed with "raw:" (#49)

* Updated dependencies

* Revert "Fixed Path" (#65)



* Revert "Fixed Path (#54)"

* when opening files with the sample app, ignore if filename extension is uppercase or lowercase

* removed unused method DidPickDocumentPicker() in iOS implementation

* added troubleshooting chapter to readme with common errors and their solutions

* updated sample projects to use PackageReference to reference NuGet packages

* removed obsolete project property AndroidUseLatestPlatformSdk and set target framework to Android 9.0 (API 28)

* updated Plugin.FilePicker.UWP to use PackageReference

* removed obsolete property AndroidUseLatestPlatformSdk and target Android 9.0, in Plugin.FilePicker.Android project

* updated sample projects to use Xamarin.Forms 3.3.0 NuGet package

* updated UWP project to latest stable UWP NuGet package

* fixed Android sample project by re-adding Xamarin.Forms NuGet package

* added UWP sample project

* find correct view controller to present document picker, by finding currently presented view controller

* Android: return from task with Exception that was thrown during file picking

before that, the caller only got a null FileData object without knowing what happened

* Android: also pass exception to task when setting up picking

* iOS: pass exceptions in DocumentPicker handler to picker task

* renamed Forms project folder to a shorter name and renamed the only page to MainPage

* added try-catch to call to PickFile() in order to display exceptions from picking

* delete Resource.designer.cs file from repository that is being regenerated by the compiler

* converted Xamarin.Forms sample project to use Project Sdk style .csproj proect file

* added second button to samples to pick image files

* added check if Android permission was granted

* fix android mime types implementation (#85)

(cherry picked from commit 04a5292)

* added explanation for requesting permissions on Android (#89)

* fixed exception when trying to pick a downloaded file; the Android DownloadManager won't return an actual file path; downloaded files can only be resolved using ContentResolver (#86)

* added solution folders to organize projects

* added UTType.Image file types value for picking on iOS

* Forms sample project can use .NET Standard 1.0; no need for version 2.0, which might not be installed

* added README.md for samples folder

* added Plugin.Permissions NuGet package to sample project, in order to check for permissions

* added checking Storage permission when on Android device

* iOS: simplified getting filename from pathname

* iOS: fixed getting pathname from FileUrl (fix of PR #54 that was reverted in PR #65); tested on iOS 11 device

* added documentation about FileData class to README

* Fix FileName for Mac

FileName on Mac returned the path instead.

* Fix OpenFile for Mac

* fixed getting path from OneDrive (#79)

the content provider only returned a relative filename in the data column, so it's better to use the content:// uri to access the file

* fixed indentation of release notes text in .nuspec - it should look nice on the nuget.org page now

* Android: file bytes are not read directly after picking, but only when FileData.DataArray is accessed or FileData.GetStream() is called; this fixes accessing large files that wouldn't fit in the device's memory, e.g. videos (#38)

* iOS: also removed getting data bytes when it's not used in FilePickerEventArgs

* added a troubleshooting section to explain why picked files on iOS may be gone after some time (#87, #74)

* added SourceLink integration, see https://github.com/dotnet/sourcelink

* added documentation for method PickFile(), in order to document how to use allowedTypes (#59)

* Revert "added SourceLink integration, see https://github.com/dotnet/sourcelink"

This reverts commit 1ca5796.

* documented classes in Plugin.FilePicker.Abstractions and fixed line endings

Author: vividos

README.md

@@ -55,6 +55,23 @@ Call **CrossFilePicker.Current** from any platform or .NET Standard project to g
                 System.Console.WriteLine("Exception choosing file: " + ex.ToString());
             }
 
+### Methods
+
+#### `async Task<FileData> PickFile(string[] allowedTypes = null)`
+
+Starts file picking and returns file data for picked file. File types can be
+specified in order to limit files that can be selected. Note that this method
+may throw exceptions that occured during file picking.
+
+Parameter `allowedTypes`:
+Specifies one or multiple allowed types. When null, all file types can be
+selected while picking.
+
+On Android you can specify one or more MIME types, e.g. "image/png"; also wild
+card characters can be used, e.g. "image/*".
+
+On iOS you can specify UTType constants, e.g. UTType.Image.
+
 ### Data structures
 
 The returned `FileData` object contains multiple properties that can be accessed:
@@ -119,6 +136,17 @@ before) but the permission must be requested and granted by the user at runtime
 the user denied the permission, don't call PickFile(). Check out the sample project in the github
 repository for an example how to check for permission.
 
+### iOS
+
+**Picked file path is invalid, file doesn't exist**
+
+On iOS the plugin uses UIDocumentPickerViewController and specifies the mode
+UIDocumentPickerMode.Import. After picking is done, iOS copies the picked file
+to the app's "Inbox" folder where it can be accessed. iOS also cleans up the
+temporary inbox folder regularly. After picking the file you have to either
+copy the file to another folder or access the data by getting the property
+DataBytes or opening a stream to the file by calling GetStream().
+
 ## Contributors
 * [jfversluis](https://github.com/jfversluis)
 * [rafaelrmou](https://github.com/rafaelrmou) (original author)

nuget/Plugin.FilePicker.nuspec

@@ -15,13 +15,12 @@
        </description>
        <summary>Simple cross-platform plug-in that allows you to pick files  and work with them. View full project page for README
        </summary>
-     <releaseNotes>
-       [2.0] - Support for .NET Standard, removed Windows Phone 8 and Windows 8/8.1 support
-       [1.4] - Support Xamarin.Mac
-       [1.3] - FileData now has a GetStream() method to retrieve the binary data as a Stream
-       [1.2] - Retrieve full file path from selected file
-       [1.1] - Support Windows Phone 8, 8.1 e Windows Store.
-       [1.0] - Pick files, save files and open the archive in Default App.
+     <releaseNotes>[2.0] - Support for .NET Standard, removed Windows Phone 8 and Windows 8/8.1 support
+[1.4] - Support Xamarin.Mac
+[1.3] - FileData now has a GetStream() method to retrieve the binary data as a Stream
+[1.2] - Retrieve full file path from selected file
+[1.1] - Support Windows Phone 8, 8.1 e Windows Store.
+[1.0] - Pick files, save files and open the archive in Default App.
      </releaseNotes>
     <tags>xamarin, file, picker, filepicker, filebrowser, netstandard, plugin, plugin for xamarin, android, xamarin.forms, ios</tags>
    </metadata>

src/Plugin.FilePicker/Plugin.FilePicker.Abstractions/FileData.cs

@@ -4,19 +4,57 @@
 namespace Plugin.FilePicker.Abstractions
 {
     /// <summary>
-    /// The object used as a wrapper for the file picked by the user
+    /// File data that specifies a file that was picked by the user.
     /// </summary>
     public class FileData : IDisposable
     {
+        /// <summary>
+        /// Backing store for the FileName property
+        /// </summary>
         private string _fileName;
+
+        /// <summary>
+        /// Backing store for the FilePath property
+        /// </summary>
         private string _filePath;
+
+        /// <summary>
+        /// Indicates if the object is already disposed
+        /// </summary>
         private bool _isDisposed;
+
+        /// <summary>
+        /// Action to dispose of underlying resources of the picked file.
+        /// </summary>
         private readonly Action<bool> _dispose;
+
+        /// <summary>
+        /// Function to get a stream to the picked file.
+        /// </summary>
         private readonly Func<Stream> _streamGetter;
 
+        /// <summary>
+        /// Creates a new and empty file data object
+        /// </summary>
         public FileData()
-        { }
+        {
+        }
 
+        /// <summary>
+        /// Creates a new file data object with property values
+        /// </summary>
+        /// <param name="filePath">
+        /// Full file path to the picked file.
+        /// </param>
+        /// <param name="fileName">
+        /// File name of the picked file.
+        /// </param>
+        /// <param name="streamGetter">
+        /// Function to get a stream to the picked file.
+        /// </param>
+        /// <param name="dispose">
+        /// Action to dispose of the underlying resources of the picked file.
+        /// </param>
         public FileData(string filePath, string fileName, Func<Stream> streamGetter, Action<bool> dispose = null)
         {
             _filePath = filePath;
@@ -40,6 +78,12 @@ public static byte[] ReadFully(Stream input)
             }
         }
 
+        /// <summary>
+        /// Returns the raw data bytes for the picked file.
+        /// Note that due to how this property is implemented, you may only
+        /// call this once.  You can always access the underlying stream by
+        /// directly calling GetStream().
+        /// </summary>
         public byte[] DataArray
         {
             get
@@ -52,7 +96,7 @@ public byte[] DataArray
         }
 
         /// <summary>
-        /// Filename of the picked file
+        /// Filename of the picked file, without path
         /// </summary>
         public string FileName
         {
@@ -74,7 +118,10 @@ public string FileName
         }
 
         /// <summary>
-        /// Full filepath of the picked file
+        /// Full filepath of the picked file.
+        /// Note that on specific platforms this can also contain an URI that
+        /// can't be opened with file related APIs. Use DataArray property or
+        /// GetStream() method in this cases.
         /// </summary>
         public string FilePath
         {
@@ -96,7 +143,9 @@ public string FilePath
         }
 
         /// <summary>
-        /// Get stream if available
+        /// Gets stream to access the picked file.
+        /// Note that when DataArray property was already accessed, the stream
+        /// must be rewinded to the beginning.
         /// </summary>
         /// <returns>stream object</returns>
         public Stream GetStream()
@@ -107,24 +156,40 @@ public Stream GetStream()
             return _streamGetter();
         }
 
+        #region IDispose implementation
+        /// <summary>
+        /// Disposes of all resources in the object
+        /// </summary>
         public void Dispose()
         {
             Dispose(true);
             GC.SuppressFinalize(this);
         }
 
+        /// <summary>
+        /// Disposes of managed resources
+        /// </summary>
+        /// <param name="disposing">
+        /// True when called from Dispose(), false when called from the destructor
+        /// </param>
         private void Dispose(bool disposing)
         {
             if (_isDisposed)
+            {
                 return;
+            }
 
             _isDisposed = true;
             _dispose?.Invoke(disposing);
         }
 
+        /// <summary>
+        /// Finalizer for this object
+        /// </summary>
         ~FileData()
         {
             Dispose(false);
         }
+        #endregion
     }
-}
+}

src/Plugin.FilePicker/Plugin.FilePicker.Abstractions/FilePickerEventArgs.cs

@@ -2,34 +2,36 @@
 
 namespace Plugin.FilePicker.Abstractions
 {
+    /// <summary>
+    /// Event arguments for the event when file picking was completed.
+    /// </summary>
     public class FilePickerEventArgs : EventArgs
     {
-        public byte [] FileByte { get; set; }
+        public byte[] FileByte { get; set; }
 
         public string FileName { get; set; }
 
         public string FilePath { get; set; }
 
-        public FilePickerEventArgs ()
+        public FilePickerEventArgs()
         {
-
         }
 
-        public FilePickerEventArgs (byte [] fileByte)
+        public FilePickerEventArgs(byte[] fileByte)
         {
             FileByte = fileByte;
         }
 
-        public FilePickerEventArgs (byte [] fileByte, string fileName)
-            : this (fileByte)
+        public FilePickerEventArgs(byte[] fileByte, string fileName)
+            : this(fileByte)
         {
             FileName = fileName;
         }
 
-        public FilePickerEventArgs (byte [] fileByte, string fileName, string filePath)
-            : this (fileByte, fileName)
+        public FilePickerEventArgs(byte[] fileByte, string fileName, string filePath)
+            : this(fileByte, fileName)
         {
             FilePath = filePath;
         }
     }
-}
+}

src/Plugin.FilePicker/Plugin.FilePicker.Abstractions/IFilePicker.cs

@@ -1,18 +1,61 @@
 using System.Threading.Tasks;
 
 namespace Plugin.FilePicker.Abstractions
-{
+{
     /// <summary>
-    /// Interface for FilePicker
+    /// Interface for FilePicker plugin. Access the platform specific instance
+    /// of this interface by using CrossFilePicker.Current.
     /// </summary>
-    public interface IFilePicker
-    {
-        Task<FileData> PickFile (string[] allowedTypes = null);
-
-        Task<bool> SaveFile (FileData fileToSave);
-
-        void OpenFile (string fileToOpen);
-
-        void OpenFile (FileData fileToOpen);
+    public interface IFilePicker
+    {
+        /// <summary>
+        /// Starts file picking and returns file data for picked file. File
+        /// types can be specified in order to limit files that can be
+        /// selected. Note that this method may throw exceptions that occured
+        /// during file picking.
+        /// </summary>
+        /// <param name="allowedTypes">
+        /// Specifies one or multiple allowed types. When null, all file types
+        /// can be selected while picking.
+        /// On Android you can specify one or more MIME types, e.g.
+        /// "image/png"; also wild card characters can be used, e.g. "image/*".
+        /// On iOS you can specify UTType constants, e.g. UTType.Image.
+        /// </param>
+        /// <returns>
+        /// File data object, or null when user cancelled picking file
+        /// </returns>
+        Task<FileData> PickFile(string[] allowedTypes = null);
+
+        /// <summary>
+        /// Saves the file that was picked to external storage.
+        /// </summary>
+        /// <param name="fileToSave">
+        /// File data from a call to PickFile() that should be saved.
+        /// </param>
+        /// <returns>
+        /// True when file was saved successfully, false when there was an
+        /// error
+        /// </returns>
+        Task<bool> SaveFile(FileData fileToSave);
+
+        /// <summary>
+        /// Opens the file with given filename in an external application that
+        /// is registered for this file type.
+        /// </summary>
+        /// <param name="fileToOpen">
+        /// Full filename of the file to open
+        /// </param>
+        void OpenFile(string fileToOpen);
+
+        /// <summary>
+        /// Opens the file specified by first storing the file to external
+        /// storage, then opening it in an external application that is
+        /// registered for this file type. This is a combination of SaveFile()
+        /// and OpenFile() above.
+        /// </summary>
+        /// <param name="fileToOpen">
+        /// File data from a call to PickFile() that should be opened.
+        /// </param>
+        void OpenFile(FileData fileToOpen);
     }
-}
+}

src/Plugin.FilePicker/Plugin.FilePicker.Android/FilePickerActivity.cs

@@ -59,15 +59,10 @@ protected override void OnActivityResult (int requestCode, [GeneratedEnum] Resul
 
                     if (string.IsNullOrEmpty (filePath))
                         filePath = IOUtil.isMediaStore(_uri.Scheme) ? _uri.ToString() : _uri.Path;
-                    byte[] file;
-                    if (IOUtil.isMediaStore(_uri.Scheme))
-                        file = IOUtil.readFile(context, _uri);
-                    else
-                        file = IOUtil.readFile (filePath);
 
                     var fileName = GetFileName (context, _uri);
 
-                    OnFilePicked (new FilePickerEventArgs (file, fileName, filePath));
+                    OnFilePicked (new FilePickerEventArgs (null, fileName, filePath));
                 } catch (Exception readEx) {
                     System.Diagnostics.Debug.Write(readEx);
                     // Notify user file picking failed.

src/Plugin.FilePicker/Plugin.FilePicker.Android/FilePickerImplementation.cs

@@ -72,7 +72,10 @@ private Task<FileData> TakeMediaAsync(string[] allowedTypes, string action)
                         () =>
                         {
                             if (IOUtil.isMediaStore(e.FilePath))
-                                return new System.IO.MemoryStream(e.FileByte);
+                            {
+                                var contentUri = Android.Net.Uri.Parse(e.FilePath);
+                                return Application.Context.ContentResolver.OpenInputStream(contentUri);
+                            }
                             else
                                 return System.IO.File.OpenRead (e.FilePath);
                         }));