This lesson teaches you to
- Receive File Requests
- Create a File Selection Activity
- Respond to a File Selection
- Grant Permissions for the File
- Share the File with the Requesting App
You should also read
Once you have set up your app to share files using content URIs, you can respond to other apps' requests for those files. One way to respond to these requests is to provide a file selection interface from the server app that other applications can invoke. This approach allows a client application to let users select a file from the server app and then receive the selected file's content URI.
This lesson shows you how to create a file selection Activity
in your app
that responds to requests for files.
Receive File Requests
To receive requests for files from client apps and respond with a content URI, your app should
provide a file selection Activity
. Client apps start this
Activity
by calling startActivityForResult()
with an Intent
containing the action
ACTION_PICK
. When the client app calls
startActivityForResult()
, your app can
return a result to the client app, in the form of a content URI for the file the user selected.
To learn how to implement a request for a file in a client app, see the lesson Requesting a Shared File.
Create a File Selection Activity
To set up the file selection Activity
, start by specifying the
Activity
in your manifest, along with an intent filter
that matches the action ACTION_PICK
and the
categories CATEGORY_DEFAULT
and
CATEGORY_OPENABLE
. Also add MIME type filters
for the files your app serves to other apps. The following snippet shows you how to specify the
new Activity
and intent filter:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <application> ... <activity android:name=".FileSelectActivity" android:label="@"File Selector" > <intent-filter> <action android:name="android.intent.action.PICK"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.OPENABLE"/> <data android:mimeType="text/plain"/> <data android:mimeType="image/*"/> </intent-filter> </activity>
Define the file selection Activity in code
Next, define an Activity
subclass that displays the files available from
your app's files/images/
directory in internal storage and allows the user to pick
the desired file. The following snippet demonstrates how to define this
Activity
and respond to the user's selection:
public class MainActivity extends Activity { // The path to the root of this app's internal storage private File mPrivateRootDir; // The path to the "images" subdirectory private File mImagesDir; // Array of files in the images subdirectory File[] mImageFiles; // Array of filenames corresponding to mImageFiles String[] mImageFilenames; // Initialize the Activity @Override protected void onCreate(Bundle savedInstanceState) { ... // Set up an Intent to send back to apps that request a file mResultIntent = new Intent("com.example.myapp.ACTION_RETURN_FILE"); // Get the files/ subdirectory of internal storage mPrivateRootDir = getFilesDir(); // Get the files/images subdirectory; mImagesDir = new File(mPrivateRootDir, "images"); // Get the files in the images subdirectory mImageFiles = mImagesDir.listFiles(); // Set the Activity's result to null to begin with setResult(Activity.RESULT_CANCELED, null); /* * Display the file names in the ListView mFileListView. * Back the ListView with the array mImageFilenames, which * you can create by iterating through mImageFiles and * calling File.getAbsolutePath() for each File */ ... } ... }
Respond to a File Selection
Once a user selects a shared file, your application must determine what file was selected and
then generate a content URI for the file. Since the Activity
displays the
list of available files in a ListView
, when the user clicks a file name
the system calls the method onItemClick()
, in which you can get the selected file.
In onItemClick()
, get a
File
object for the file name of the selected file and pass it as an argument to
getUriForFile()
, along with the
authority that you specified in the
<provider>
element for the FileProvider
.
The resulting content URI contains the authority, a path segment corresponding to the file's
directory (as specified in the XML meta-data), and the name of the file including its
extension. How FileProvider
maps directories to path
segments based on XML meta-data is described in the section
Specify Sharable Directories.
The following snippet shows you how to detect the selected file and get a content URI for it:
protected void onCreate(Bundle savedInstanceState) { ... // Define a listener that responds to clicks on a file in the ListView mFileListView.setOnItemClickListener( new AdapterView.OnItemClickListener() { @Override /* * When a filename in the ListView is clicked, get its * content URI and send it to the requesting app */ public void onItemClick(AdapterView<?> adapterView, View view, int position, long rowId) { /* * Get a File for the selected file name. * Assume that the file names are in the * mImageFilename array. */ File requestFile = new File(mImageFilename[position]); /* * Most file-related method calls need to be in * try-catch blocks. */ // Use the FileProvider to get a content URI try { fileUri = FileProvider.getUriForFile( MainActivity.this, "com.example.myapp.fileprovider", requestFile); } catch (IllegalArgumentException e) { Log.e("File Selector", "The selected file can't be shared: " + clickedFilename); } ... } }); ... }
Remember that you can only generate content URIs for files that reside in a directory
you've specified in the meta-data file that contains the <paths>
element, as
described in the section Specify Sharable Directories. If you call
getUriForFile()
for a
File
in a path that you haven't specified, you receive an
IllegalArgumentException
.
Grant Permissions for the File
Now that you have a content URI for the file you want to share with another app, you need to
allow the client app to access the file. To allow access, grant permissions to the client app by
adding the content URI to an Intent
and then setting permission flags on
the Intent
. The permissions you grant are temporary and expire
automatically when the receiving app's task stack is finished.
The following code snippet shows you how to set read permission for the file:
protected void onCreate(Bundle savedInstanceState) { ... // Define a listener that responds to clicks in the ListView mFileListView.setOnItemClickListener( new AdapterView.OnItemClickListener() { @Override public void onItemClick(AdapterView<?> adapterView, View view, int position, long rowId) { ... if (fileUri != null) { // Grant temporary read permission to the content URI mResultIntent.addFlags( Intent.FLAG_GRANT_READ_URI_PERMISSION); } ... } ... }); ... }
Caution: Calling setFlags()
is the only
way to securely grant access to your files using temporary access permissions. Avoid calling
Context.grantUriPermission()
method for a
file's content URI, since this method grants access that you can only revoke by
calling Context.revokeUriPermission()
.
Share the File with the Requesting App
To share the file with the app that requested it, pass the Intent
containing the content URI and permissions to setResult()
. When the Activity
you have just defined is finished, the
system sends the Intent
containing the content URI to the client app.
The following code snippet shows you how to do this:
protected void onCreate(Bundle savedInstanceState) { ... // Define a listener that responds to clicks on a file in the ListView mFileListView.setOnItemClickListener( new AdapterView.OnItemClickListener() { @Override public void onItemClick(AdapterView<?> adapterView, View view, int position, long rowId) { ... if (fileUri != null) { ... // Put the Uri and MIME type in the result Intent mResultIntent.setDataAndType( fileUri, getContentResolver().getType(fileUri)); // Set the result MainActivity.this.setResult(Activity.RESULT_OK, mResultIntent); } else { mResultIntent.setDataAndType(null, ""); MainActivity.this.setResult(RESULT_CANCELED, mResultIntent); } } });
Provide users with an way to return immediately to the client app once they have chosen a file.
One way to do this is to provide a checkmark or Done button. Associate a method with
the button using the button's
android:onClick
attribute. In the method, call
finish()
. For example:
public void onDoneClick(View v) { // Associate a method with the Done button finish(); }