ContentProvider.OpenFile Method

  • Reference

Definition

Namespace:
Android.Content
Assembly:
Mono.Android.dll

Overloads

OpenFile(Uri, String)

Override this to handle requests to open a file blob.
OpenFile(Uri, String, CancellationSignal)

Override this to handle requests to open a file blob.

OpenFile(Uri, String)

Override this to handle requests to open a file blob.

[Android.Runtime.Register("openFile", "(Landroid/net/Uri;Ljava/lang/String;)Landroid/os/ParcelFileDescriptor;", "GetOpenFile_Landroid_net_Uri_Ljava_lang_String_Handler")]
public virtual Android.OS.ParcelFileDescriptor? OpenFile (Android.Net.Uri uri, string mode);
[<Android.Runtime.Register("openFile", "(Landroid/net/Uri;Ljava/lang/String;)Landroid/os/ParcelFileDescriptor;", "GetOpenFile_Landroid_net_Uri_Ljava_lang_String_Handler")>]
abstract member OpenFile : Android.Net.Uri * string -> Android.OS.ParcelFileDescriptor
override this.OpenFile : Android.Net.Uri * string -> Android.OS.ParcelFileDescriptor

Parameters

uri
Uri

The URI whose file is to be opened.

mode
String

The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" or "rwt". Please note the exact implementation of these may differ for each Provider implementation - for example, "w" may or may not truncate.

Returns

ParcelFileDescriptor

Returns a new ParcelFileDescriptor which you can use to access the file.

Attributes
RegisterAttribute

Exceptions

FileNotFoundException

Throws FileNotFoundException if there is no file associated with the given URI or the mode is invalid.

SecurityException

Throws SecurityException if the caller does not have permission to access the file.

Remarks

Override this to handle requests to open a file blob. The default implementation always throws FileNotFoundException. This method can be called from multiple threads, as described in Processes and Threads.

This method returns a ParcelFileDescriptor, which is returned directly to the caller. This way large data (such as images and documents) can be returned without copying the content.

The returned ParcelFileDescriptor is owned by the caller, so it is their responsibility to close it when done. That is, the implementation of this method should create a new ParcelFileDescriptor for each call.

If opened with the exclusive "r" or "w" modes, the returned ParcelFileDescriptor can be a pipe or socket pair to enable streaming of data. Opening with the "rw" or "rwt" modes implies a file on disk that supports seeking.

If you need to detect when the returned ParcelFileDescriptor has been closed, or if the remote process has crashed or encountered some other error, you can use ParcelFileDescriptor#open(File, int, android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener), ParcelFileDescriptor#createReliablePipe(), or ParcelFileDescriptor#createReliableSocketPair().

If you need to return a large file that isn't backed by a real file on disk, such as a file on a network share or cloud storage service, consider using StorageManager#openProxyFileDescriptor(int, android.os.ProxyFileDescriptorCallback, android.os.Handler) which will let you to stream the content on-demand.

<p class="note">For use in Intents, you will want to implement #getType to return the appropriate MIME type for the data returned here with the same URI. This will allow intent resolution to automatically determine the data MIME type and select the appropriate matching targets as part of its operation.

<p class="note">For better interoperability with other applications, it is recommended that for any URIs that can be opened, you also support queries on them containing at least the columns specified by android.provider.OpenableColumns. You may also want to support other common columns if you have additional meta-data to supply, such as android.provider.MediaStore.MediaColumns#DATE_ADDED in android.provider.MediaStore.MediaColumns.</p>

Java documentation for android.content.ContentProvider.openFile(android.net.Uri, java.lang.String).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

See also

  • <xref:Android.Content.ContentProvider.OpenAssetFile(Android.Net.Uri%2c+System.String)>
  • <xref:Android.Content.ContentProvider.OpenFileHelper(Android.Net.Uri%2c+System.String)>
  • GetType(Uri)
  • ParseMode(String)

Applies to

OpenFile(Uri, String, CancellationSignal)

Override this to handle requests to open a file blob.

[Android.Runtime.Register("openFile", "(Landroid/net/Uri;Ljava/lang/String;Landroid/os/CancellationSignal;)Landroid/os/ParcelFileDescriptor;", "GetOpenFile_Landroid_net_Uri_Ljava_lang_String_Landroid_os_CancellationSignal_Handler")]
public virtual Android.OS.ParcelFileDescriptor? OpenFile (Android.Net.Uri uri, string mode, Android.OS.CancellationSignal? signal);
[<Android.Runtime.Register("openFile", "(Landroid/net/Uri;Ljava/lang/String;Landroid/os/CancellationSignal;)Landroid/os/ParcelFileDescriptor;", "GetOpenFile_Landroid_net_Uri_Ljava_lang_String_Landroid_os_CancellationSignal_Handler")>]
abstract member OpenFile : Android.Net.Uri * string * Android.OS.CancellationSignal -> Android.OS.ParcelFileDescriptor
override this.OpenFile : Android.Net.Uri * string * Android.OS.CancellationSignal -> Android.OS.ParcelFileDescriptor

Parameters

uri
Uri

The URI whose file is to be opened.

mode
String

The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" or "rwt". Please note the exact implementation of these may differ for each Provider implementation - for example, "w" may or may not truncate.

signal
CancellationSignal

A signal to cancel the operation in progress, or null if none. For example, if you are downloading a file from the network to service a "rw" mode request, you should periodically call CancellationSignal#throwIfCanceled() to check whether the client has canceled the request and abort the download.

Returns

ParcelFileDescriptor

Returns a new ParcelFileDescriptor which you can use to access the file.

Attributes
RegisterAttribute

Exceptions

FileNotFoundException

Throws FileNotFoundException if there is no file associated with the given URI or the mode is invalid.

SecurityException

Throws SecurityException if the caller does not have permission to access the file.

Remarks

Override this to handle requests to open a file blob. The default implementation always throws FileNotFoundException. This method can be called from multiple threads, as described in Processes and Threads.

This method returns a ParcelFileDescriptor, which is returned directly to the caller. This way large data (such as images and documents) can be returned without copying the content.

The returned ParcelFileDescriptor is owned by the caller, so it is their responsibility to close it when done. That is, the implementation of this method should create a new ParcelFileDescriptor for each call.

If opened with the exclusive "r" or "w" modes, the returned ParcelFileDescriptor can be a pipe or socket pair to enable streaming of data. Opening with the "rw" or "rwt" modes implies a file on disk that supports seeking.

If you need to detect when the returned ParcelFileDescriptor has been closed, or if the remote process has crashed or encountered some other error, you can use ParcelFileDescriptor#open(File, int, android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener), ParcelFileDescriptor#createReliablePipe(), or ParcelFileDescriptor#createReliableSocketPair().

<p class="note">For use in Intents, you will want to implement #getType to return the appropriate MIME type for the data returned here with the same URI. This will allow intent resolution to automatically determine the data MIME type and select the appropriate matching targets as part of its operation.

<p class="note">For better interoperability with other applications, it is recommended that for any URIs that can be opened, you also support queries on them containing at least the columns specified by android.provider.OpenableColumns. You may also want to support other common columns if you have additional meta-data to supply, such as android.provider.MediaStore.MediaColumns#DATE_ADDED in android.provider.MediaStore.MediaColumns.</p>

Java documentation for android.content.ContentProvider.openFile(android.net.Uri, java.lang.String, android.os.CancellationSignal).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

See also

  • <xref:Android.Content.ContentProvider.OpenAssetFile(Android.Net.Uri%2c+System.String)>
  • <xref:Android.Content.ContentProvider.OpenFileHelper(Android.Net.Uri%2c+System.String)>
  • GetType(Uri)
  • ParseMode(String)

Applies to