For more information about sending and receiving {@link android.content.Intent#ACTION_SEND} intents that perform social sharing behaviors, see the lesson about Receiving Content from Other Apps.
+href="{@docRoot}training/sharing/receive.html">Receiving Simple Data from Other Apps.When the user is done with the subsequent activity and returns, the system calls your activity's +
When the user is done with the subsequent activity and returns, the system calls your activity's {@link android.app.Activity#onActivityResult onActivityResult()} method. This method includes three arguments:
diff --git a/docs/html/training/basics/intents/sending.jd b/docs/html/training/basics/intents/sending.jd index aba3896825b19..79c017b3ae9f2 100644 --- a/docs/html/training/basics/intents/sending.jd +++ b/docs/html/training/basics/intents/sending.jd @@ -22,7 +22,7 @@ next.link=result.htmlThese classes teach you how to create apps that share data between apps and devices.
diff --git a/docs/html/training/secure-file-sharing/index.jd b/docs/html/training/secure-file-sharing/index.jd new file mode 100644 index 0000000000000..19a10428176d6 --- /dev/null +++ b/docs/html/training/secure-file-sharing/index.jd @@ -0,0 +1,80 @@ +page.title=Sharing Files + +trainingnavtop=true +startpage=true + + +@jd:body + ++ Apps often have a need to offer one or more of their files to another app. For example, an image + gallery may want to offer files to image editors, or a file management app may want to allow + users to copy and paste files between areas in external storage. One way a sending app can + share a file is to respond to a request from the receiving app. +
++ In all cases, the only secure way to offer a file from your app to another app is to send the + receiving app the file's content URI and grant temporary access permissions to that URI. + Content URIs with temporary URI access permissions are secure because they apply only to the + app that receives the URI, and they expire automatically. The Android + {@link android.support.v4.content.FileProvider} component provides the method + {@link android.support.v4.content.FileProvider#getUriForFile getUriForFile()} for + generating a file's content URI. +
++ If you want to share small amounts of text or numeric data between apps, you should send an + {@link android.content.Intent} that contains the data. To learn how to send simple data with an + {@link android.content.Intent}, see the training class + Sharing Simple Data. +
++ This class explains how to securely share files from your app to another app using content URIs + generated by the Android {@link android.support.v4.content.FileProvider} component and + temporary permissions that you grant to the receiving app for the content URI. +
++ When an app wants to access a file shared by another app, the requesting app (the client) + usually sends a request to the app sharing the files (the server). In most cases, the request + starts an {@link android.app.Activity} in the server app that displays the files it can share. + The user picks a file, after which the server app returns the file's content URI to the + client app. +
++ This lesson shows you how a client app requests a file from a server app, receives the file's + content URI from the server app, and opens the file using the content URI. +
+ ++ To request a file from the server app, the client app calls + {@link android.app.Activity#startActivityForResult startActivityForResult} with an + {@link android.content.Intent} containing the action such as + {@link android.content.Intent#ACTION_PICK ACTION_PICK} and a MIME type that the client app + can handle. +
++ For example, the following code snippet demonstrates how to send an + {@link android.content.Intent} to a server app in order to start the + {@link android.app.Activity} described in Sharing a File: +
+
+public class MainActivity extends Activity {
+ private Intent mRequestFileIntent;
+ private ParcelFileDescriptor mInputPFD;
+ ...
+ @Override
+ protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.activity_main);
+ mRequestFileIntent = new Intent(Intent.ACTION_PICK);
+ mRequestFileIntent.setType("image/jpg");
+ ...
+ }
+ ...
+ protected void requestFile() {
+ /**
+ * When the user requests a file, send an Intent to the
+ * server app.
+ * files.
+ */
+ startActivityForResult(mRequestFileIntent, 0);
+ ...
+ }
+ ...
+}
+
++ The server app sends the file's content URI back to the client app in an + {@link android.content.Intent}. This {@link android.content.Intent} is passed to the client + app in its override of {@link android.app.Activity#onActivityResult onActivityResult()}. Once + the client app has the file's content URI, it can access the file by getting its + {@link java.io.FileDescriptor}. +
++
+ File security is preserved in this process because the content URI is the only piece of data + that the client app receives. Since this URI doesn't contain a directory path, the client app + can't discover and open any other files in the server app. Only the client app gets access to + the file, and only for the permissions granted by the server app. The permissions are temporary, + so once the client app's task stack is finished, the file is no longer accessible outside the + server app. +
++ The next snippet demonstrates how the client app handles the + {@link android.content.Intent} sent from the server app, and how the client app gets the + {@link java.io.FileDescriptor} using the content URI: +
+
+ /*
+ * When the Activity of the app that hosts files sets a result and calls
+ * finish(), this method is invoked. The returned Intent contains the
+ * content URI of a selected file. The result code indicates if the
+ * selection worked or not.
+ */
+ @Override
+ public void onActivityResult(int requestCode, int resultCode,
+ Intent returnIntent) {
+ // If the selection didn't work
+ if (resultCode != RESULT_OK) {
+ // Exit without doing anything else
+ return;
+ } else {
+ // Get the file's content URI from the incoming Intent
+ Uri returnUri = returnIntent.getData();
+ /*
+ * Try to open the file for "read" access using the
+ * returned URI. If the file isn't found, write to the
+ * error log and return.
+ */
+ try {
+ /*
+ * Get the content resolver instance for this context, and use it
+ * to get a ParcelFileDescriptor for the file.
+ */
+ mInputPFD = getContentResolver().openFileDescriptor(returnUri, "r");
+ } catch (FileNotFoundException e) {
+ e.printStackTrace();
+ Log.e("MainActivity", "File not found.");
+ return;
+ }
+ // Get a regular file descriptor for the file
+ FileDescriptor fd = mInputPFD.getFileDescriptor();
+ ...
+ }
+ }
+
++ The method {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()} + returns a {@link android.os.ParcelFileDescriptor} for the file. From this object, the client + app gets a {@link java.io.FileDescriptor} object, which it can then use to read the file. +
diff --git a/docs/html/training/secure-file-sharing/retrieve-info.jd b/docs/html/training/secure-file-sharing/retrieve-info.jd new file mode 100644 index 0000000000000..4a2b7d86b4a04 --- /dev/null +++ b/docs/html/training/secure-file-sharing/retrieve-info.jd @@ -0,0 +1,110 @@ +page.title=Retrieving File Information + +trainingnavtop=true +@jd:body + + ++ Before a client app tries to work with a file for which it has a content URI, the app can + request information about the file from the server app, including the file's data type and + file size. The data type helps the client app to determine if it can handle the file, and the + file size helps the client app set up buffering and caching for the file. +
++ This lesson demonstrates how to query the server app's + {@link android.support.v4.content.FileProvider} to retrieve a file's MIME type and size. +
++ A file's data type indicates to the client app how it should handle the file's contents. To get + the data type of a shared file given its content URI, the client app calls + {@link android.content.ContentResolver#getType ContentResolver.getType()}. This method returns + the file's MIME type. By default, a + {@link android.support.v4.content.FileProvider} determines the file's MIME type from its + filename extension. +
++ The following code snippet demonstrates how a client app retrieves the MIME type of a file once + the server app has returned the content URI to the client: +
++ ... + /* + * Get the file's content URI from the incoming Intent, then + * get the file's MIME type + */ + Uri returnUri = returnIntent.getData(); + String mimeType = getContentResolver().getType(returnUri); + ... ++
+ The {@link android.support.v4.content.FileProvider} class has a default implementation of the + {@link android.support.v4.content.FileProvider#query query()} method that returns the + name and size of the file associated with a content URI in a + {@link android.database.Cursor}. The default implementation returns two columns: +
++ The client app can get both the {@link android.provider.OpenableColumns#DISPLAY_NAME + DISPLAY_NAME} and {@link android.provider.OpenableColumns#SIZE SIZE} for a file by setting all + of the arguments of {@link android.support.v4.content.FileProvider#query query()} to + {@code null} except for the content URI. For example, this code snippet retrieves a file's + {@link android.provider.OpenableColumns#DISPLAY_NAME DISPLAY_NAME} and + {@link android.provider.OpenableColumns#SIZE SIZE} and displays each one in separate + {@link android.widget.TextView}: +
++ ... + /* + * Get the file's content URI from the incoming Intent, + * then query the server app to get the file's display name + * and size. + */ + Uri returnUri = returnIntent.getData(); + Cursor returnCursor = + getContentResolver().query(returnUri, null, null, null, null); + /* + * Get the column indexes of the data in the Cursor, + * move to the first row in the Cursor, get the data, + * and display it. + */ + int nameIndex = returnCursor.getColumnIndex(OpenableColumns.DISPLAY_NAME); + int sizeIndex = returnCursor.getColumnIndex(OpenableColumns.SIZE); + returnCursor.moveToFirst(); + TextView nameView = (TextView) findViewById(R.id.filename_text); + TextView sizeView = (TextView) findViewById(R.id.filesize_text); + nameView.setText(returnCursor.getString(nameIndex)); + sizeView.setText(Long.toString(returnCursor.getLong(sizeIndex))); + ... +diff --git a/docs/html/training/secure-file-sharing/setup-sharing.jd b/docs/html/training/secure-file-sharing/setup-sharing.jd new file mode 100644 index 0000000000000..d1ab99317ea9b --- /dev/null +++ b/docs/html/training/secure-file-sharing/setup-sharing.jd @@ -0,0 +1,136 @@ +page.title=Setting Up File Sharing +trainingnavtop=true +@jd:body + + +
+ To securely offer a file from your app to another app, you need to configure your app to offer + a secure handle to the file, in the form of a content URI. The Android + {@link android.support.v4.content.FileProvider} component generates content URIs for + files, based on specifications you provide in XML. This lesson shows you how to add the default + implementation of {@link android.support.v4.content.FileProvider} to your app, and how to + specify the files you want to offer to other apps. +
++ Defining a {@link android.support.v4.content.FileProvider} for your app requires an entry in + your manifest. This entry specifies the authority to use in generating content URIs, as well as + the name of an XML file that specifies the directories your app can share. +
+
+ The following snippet shows you how to add to your manifest the
+ <provider> element that specifies the
+ {@link android.support.v4.content.FileProvider} class, the authority, and the
+ XML file name:
+
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.myapp"> + <application + ...> + <provider + android:name="android.support.v4.content.FileProvider" + android:authorities="com.example.myapp.fileprovider" + android:grantUriPermissions="true" + android:exported="false"> + <meta-data + android:name="android.support.FILE_PROVIDER_PATHS" + android:resource="@xml/filepaths" /> + </provider> + ... + </application> +</manifest>+
+ In this example, the android:authorities attribute specifies the URI authority
+ that you want to use for content URIs generated by the
+ {@link android.support.v4.content.FileProvider}.
+ In the example, the authority is com.example.myapp.fileprovider. For your own
+ app, specify an authority consisting of the app's
+ android:package value with the string "fileprovider" appended to it. To learn more
+ about the authority value, see the topic
+ Content URIs and the documentation for the
+ android:authorities attribute.
+
+ The <meta-data> child element of the
+ <provider> points to an XML file that specifies the directories you want to
+ share. The android:resource attribute is the path and name of the file, without
+ the .xml extension.The contents of this file are described in the next section.
+
+ Once you have added the {@link android.support.v4.content.FileProvider} to your app manifest,
+ you need to specify the directories that contain the files you want to share. To specify the
+ directories, start by creating the file filepaths.xml in the res/xml/
+ subdirectory of your project. In this file, specify the directories by adding an XML element for
+ each directory. The following snippet shows you an example of the contents of
+ res/xml/filepaths.xml. The snippet also demonstrates how to share a subdirectory
+ of the files/ directory in your internal storage area:
+
+<paths> + <files-path path="images/" name="myimages" /> +</paths>+
+ In this example, the <files-path> tag shares directories within the
+ files/ directory of your app's internal storage. The path attribute
+ shares the images/ subdirectory of files/. The name
+ attribute tells the {@link android.support.v4.content.FileProvider} to add the path segment
+ myimages to content URIs for files in the files/images/ subdirectory.
+
+ The <paths> element can have multiple children, each specifying a different
+ directory to share. In addition to the <files-path> element, you can
+ use the <external-path> element to share directories in external storage, and
+ the <cache-path> element to share directories in your internal cache
+ directory. To learn more about the child elements that specify shared directories, see the
+ {@link android.support.v4.content.FileProvider} reference documentation.
+
+ Note: The XML file is the only way you can specify the directories you want to + share; you can't programmatically add a directory. +
+
+ You now have a complete specification of a {@link android.support.v4.content.FileProvider}
+ that generates content URIs for files in the files/ directory of your app's
+ internal storage or for files in subdirectories of files/. When your app generates
+ a content URI for a file, it contains the authority specified in the
+ <provider> element (com.example.myapp.fileprovider),
+ the path myimages/, and the name of the file.
+
+ For example, if you define a {@link android.support.v4.content.FileProvider} according to the
+ snippets in this lesson, and you request a content URI for the file
+ default_image.jpg, {@link android.support.v4.content.FileProvider} returns the
+ following URI:
+
+content://com.example.myapp.fileprovider/myimages/default_image.jpg+ diff --git a/docs/html/training/secure-file-sharing/share-file.jd b/docs/html/training/secure-file-sharing/share-file.jd new file mode 100644 index 0000000000000..6c52770a0fdaf --- /dev/null +++ b/docs/html/training/secure-file-sharing/share-file.jd @@ -0,0 +1,298 @@ +page.title=Sharing a File + +trainingnavtop=true +@jd:body + + +
+ 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 {@link android.app.Activity} in your app + that responds to requests for files. +
++ To receive requests for files from client apps and respond with a content URI, your app should + provide a file selection {@link android.app.Activity}. Client apps start this + {@link android.app.Activity} by calling {@link android.app.Activity#startActivityForResult + startActivityForResult()} with an {@link android.content.Intent} containing the action + {@link android.content.Intent#ACTION_PICK ACTION_PICK}. When the client app calls + {@link android.app.Activity#startActivityForResult 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. +
++ To set up the file selection {@link android.app.Activity}, start by specifying the + {@link android.app.Activity} in your manifest, along with an intent filter + that matches the action {@link android.content.Intent#ACTION_PICK ACTION_PICK} and the + categories {@link android.content.Intent#CATEGORY_DEFAULT CATEGORY_DEFAULT} and + {@link android.content.Intent#CATEGORY_OPENABLE 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 {@link android.app.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>+
+ Next, define an {@link android.app.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
+ {@link android.app.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
+ */
+ ...
+ }
+ ...
+}
++ 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 {@link android.app.Activity} displays the + list of available files in a {@link android.widget.ListView}, when the user clicks a file name + the system calls the method {@link android.widget.AdapterView.OnItemClickListener#onItemClick + onItemClick()}, in which you can get the selected file. +
+
+ In {@link android.widget.AdapterView.OnItemClickListener#onItemClick onItemClick()}, get a
+ {@link java.io.File} object for the file name of the selected file and pass it as an argument to
+ {@link android.support.v4.content.FileProvider#getUriForFile getUriForFile()}, along with the
+ authority that you specified in the
+ <provider> element for the {@link android.support.v4.content.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 {@link android.support.v4.content.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
+ {@link android.support.v4.content.FileProvider#getUriForFile getUriForFile()} for a
+ {@link java.io.File} in a path that you haven't specified, you receive an
+ {@link java.lang.IllegalArgumentException}.
+
+ 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 {@link android.content.Intent} and then setting permission flags on + the {@link android.content.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 {@link android.content.Intent#setFlags setFlags()} is the only + way to securely grant access to your files using temporary access permissions. Avoid calling + {@link android.content.Context#grantUriPermission Context.grantUriPermission()} method for a + file's content URI, since this method grants access that you can only revoke by + calling {@link android.content.Context#revokeUriPermission Context.revokeUriPermission()}. +
++ To share the file with the app that requested it, pass the {@link android.content.Intent} + containing the content URI and permissions to {@link android.app.Activity#setResult + setResult()}. When the {@link android.app.Activity} you have just defined is finished, the + system sends the {@link android.content.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
+ {@link android.app.Activity#finish finish()}. For example:
+
+ public void onDoneClick(View v) {
+ // Associate a method with the Done button
+ finish();
+ }
diff --git a/docs/html/training/sharing/index.jd b/docs/html/training/sharing/index.jd
index 2aa22b6a0490b..06d42fc81887e 100644
--- a/docs/html/training/sharing/index.jd
+++ b/docs/html/training/sharing/index.jd
@@ -1,4 +1,4 @@
-page.title=Sharing Content
+page.title=Sharing Simple Data
page.tags="intents","share"
trainingnavtop=true
@@ -20,26 +20,26 @@ Intent Filters
-
+
One of the great things about Android applications is their ability to communicate and integrate with each other. Why reinvent functionality that isn't core to your application when it -already exists in another application?
+already exists in another application? -This class covers some common ways you can send and receive content between +
This class covers some common ways you can send and receive simple data between applications using {@link android.content.Intent} APIs and the {@link android.view.ActionProvider} object.
Just as your application can send data to other applications, so too can it easily receive data -from applications. Think about how users interact with your application, and what data types you -want to receive from other applications. For example, a social networking application would likely -be interested in receiving text content, like an interesting web URL, from another app. The +
Just as your application can send data to other applications, so too can it easily receive data +from applications. Think about how users interact with your application, and what data types you +want to receive from other applications. For example, a social networking application would likely +be interested in receiving text content, like an interesting web URL, from another app. The Google+ Android -application -accepts both text and single or multiple images. With this app, a user can easily start a +application +accepts both text and single or multiple images. With this app, a user can easily start a new Google+ post with photos from the Android Gallery app.
Intent filters inform the system what intents an application component is willing to accept. -Similar to how you constructed an intent with action {@link android.content.Intent#ACTION_SEND} in -the Send Content to Other Apps Using Intents -lesson, you create intent filters in order to be able to receive intents with this action. You -define an intent filter in your manifest, using the +
Intent filters inform the system what intents an application component is willing to accept.
+Similar to how you constructed an intent with action {@link android.content.Intent#ACTION_SEND} in
+the Sending Simple Data to Other Apps
+lesson, you create intent filters in order to be able to receive intents with this action. You
+define an intent filter in your manifest, using the
<intent-filter>
-element. For example, if your application handles receiving text content, a single image of any
+href="{@docRoot}guide/components/intents-filters.html#ifs"><intent-filter>
+element. For example, if your application handles receiving text content, a single image of any
type, or multiple images of any type, your manifest would look like:
@@ -72,24 +72,24 @@ type, or multiple images of any type, your manifest would look like: </activity>-
Note: For more information on intent filters and intent resolution +
Note: For more information on intent filters and intent resolution please read Intents and Intent Filters
When another application tries to share any of these things by constructing an intent and passing
it to {@link android.content.Context#startActivity(android.content.Intent) startActivity()}, your
-application will be listed as an option in the intent chooser. If the user selects your application,
-the corresponding activity (.ui.MyActivity in the example above) will be started. It
+application will be listed as an option in the intent chooser. If the user selects your application,
+the corresponding activity (.ui.MyActivity in the example above) will be started. It
is then up to you to handle the content appropriately within your code and UI.
To handle the content delivered by an {@link android.content.Intent}, start by calling {@link -android.content.Intent#getIntent(String) getIntent()} -to get {@link android.content.Intent} object. Once you have the object, you can examine its -contents to determine what to do next. Keep in mind that if this activity can be started from other -parts of the system, such as the launcher, then you will need to take this into consideration when +android.content.Intent#getIntent(String) getIntent()} +to get {@link android.content.Intent} object. Once you have the object, you can examine its +contents to determine what to do next. Keep in mind that if this activity can be started from other +parts of the system, such as the launcher, then you will need to take this into consideration when examining the intent.
@@ -143,7 +143,7 @@ know what some other application may send you. For example, the wrong MIME type
image being sent might be extremely large. Also, remember to process binary data in a separate
thread rather than the main ("UI") thread.
-Updating the UI can be as simple as populating an {@link android.widget.EditText}, or it can
-be more complicated like applying an interesting photo filter to an image. It's really specific
+
Updating the UI can be as simple as populating an {@link android.widget.EditText}, or it can
+be more complicated like applying an interesting photo filter to an image. It's really specific
to your application what happens next.
diff --git a/docs/html/training/sharing/send.jd b/docs/html/training/sharing/send.jd
index ed9e12ede4a27..f5da68feb9342 100644
--- a/docs/html/training/sharing/send.jd
+++ b/docs/html/training/sharing/send.jd
@@ -1,9 +1,9 @@
-page.title=Sending Content to Other Apps
-parent.title=Sharing Content
+page.title=Sending Simple Data to Other Apps
+parent.title=Sharing Simple Data
parent.link=index.html
trainingnavtop=true
-next.title=Receiving Content from Other Apps
+next.title=Receiving Simple Data from Other Apps
next.link=receive.html
@jd:body
@@ -29,22 +29,22 @@ Intent Filters
-When you construct an intent, you must specify the action you want the intent to "trigger."
-Android defines several actions, including {@link android.content.Intent#ACTION_SEND} which, as
-you can probably guess, indicates that the intent is sending data from one activity to another,
-even across process boundaries. To send data to another activity, all you need to do is specify
-the data and its type, the system will identify compatible receiving activities and display them
-to the user (if there are multiple options) or immediately start the activity (if there is only
-one option). Similarly, you can advertise the data types that your activities support receiving
+
When you construct an intent, you must specify the action you want the intent to "trigger."
+Android defines several actions, including {@link android.content.Intent#ACTION_SEND} which, as
+you can probably guess, indicates that the intent is sending data from one activity to another,
+even across process boundaries. To send data to another activity, all you need to do is specify
+the data and its type, the system will identify compatible receiving activities and display them
+to the user (if there are multiple options) or immediately start the activity (if there is only
+one option). Similarly, you can advertise the data types that your activities support receiving
from other applications by specifying them in your manifest.
-Sending and receiving data between applications with intents is most commonly used for social
-sharing of content. Intents allow users to share information quickly and easily, using their
+
Sending and receiving data between applications with intents is most commonly used for social
+sharing of content. Intents allow users to share information quickly and easily, using their
favorite applications.
-Note: The best way to add a share action item to an
-{@link android.app.ActionBar} is to use {@link android.widget.ShareActionProvider}, which became
-available in API level 14. {@link android.widget.ShareActionProvider} is discussed in the lesson
+
Note: The best way to add a share action item to an
+{@link android.app.ActionBar} is to use {@link android.widget.ShareActionProvider}, which became
+available in API level 14. {@link android.widget.ShareActionProvider} is discussed in the lesson
about Adding an Easy Share Action.
@@ -58,10 +58,10 @@ on a handset.
-The most straightforward and common use of the {@link android.content.Intent#ACTION_SEND}
-action is sending text content from one activity to another. For example, the built-in Browser
-app can share the URL of the currently-displayed page as text with any application. This is useful
-for sharing an article or website with friends via email or social networking. Here is the code to
+
The most straightforward and common use of the {@link android.content.Intent#ACTION_SEND}
+action is sending text content from one activity to another. For example, the built-in Browser
+app can share the URL of the currently-displayed page as text with any application. This is useful
+for sharing an article or website with friends via email or social networking. Here is the code to
implement this type of sharing:
@@ -72,12 +72,12 @@ sendIntent.setType("text/plain");
startActivity(sendIntent);
-If there's an installed application with a filter that matches
-{@link android.content.Intent#ACTION_SEND} and MIME type text/plain, the Android system will run
-it; if more than one application matches, the system displays a disambiguation dialog (a "chooser")
-that allows the user to choose an app. If you call
+
If there's an installed application with a filter that matches
+{@link android.content.Intent#ACTION_SEND} and MIME type text/plain, the Android system will run
+it; if more than one application matches, the system displays a disambiguation dialog (a "chooser")
+that allows the user to choose an app. If you call
{@link android.content.Intent#createChooser(android.content.Intent, CharSequence)
-Intent.createChooser()}
+Intent.createChooser()}
for the intent, Android will always display the chooser. This has some
advantages:
@@ -100,17 +100,17 @@ startActivity(Intent.createChooser(sendIntent, getResources().getText(R.
The resulting dialog is shown in figure 1.
-Optionally, you can set some standard extras for the intent:
-{@link android.content.Intent#EXTRA_EMAIL}, {@link android.content.Intent#EXTRA_CC},
-{@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}. However,
-if the receiving application is not designed to use them, nothing will happen. You can use
-custom extras as well, but there's no effect unless the receiving application understands them.
+
Optionally, you can set some standard extras for the intent:
+{@link android.content.Intent#EXTRA_EMAIL}, {@link android.content.Intent#EXTRA_CC},
+{@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}. However,
+if the receiving application is not designed to use them, nothing will happen. You can use
+custom extras as well, but there's no effect unless the receiving application understands them.
Typically, you'd use custom extras defined by the receiving application itself.
-Note: Some e-mail applications, such as Gmail, expect a
-{@link java.lang.String String[]} for extras like {@link android.content.Intent#EXTRA_EMAIL} and
-{@link android.content.Intent#EXTRA_CC}, use
-{@link android.content.Intent#putExtra(String,String[]) putExtra(String, String[])} to add these
+
Note: Some e-mail applications, such as Gmail, expect a
+{@link java.lang.String String[]} for extras like {@link android.content.Intent#EXTRA_EMAIL} and
+{@link android.content.Intent#EXTRA_CC}, use
+{@link android.content.Intent#putExtra(String,String[]) putExtra(String, String[])} to add these
to your intent.
diff --git a/docs/html/training/sharing/shareaction.jd b/docs/html/training/sharing/shareaction.jd
index 873f61457b690..ee811dabdc30e 100644
--- a/docs/html/training/sharing/shareaction.jd
+++ b/docs/html/training/sharing/shareaction.jd
@@ -3,7 +3,7 @@ parent.title=Sharing Content
parent.link=index.html
trainingnavtop=true
-previous.title=Receiving Content from Other Apps
+previous.title=Receiving Simple Data from Other Apps
previous.link=receive.html
@jd:body
@@ -28,7 +28,7 @@ previous.link=receive.html
-Implementing an effective and user friendly share action in your {@link android.app.ActionBar}
+
Implementing an effective and user friendly share action in your {@link android.app.ActionBar}
is made even easier with the introduction of {@link android.view.ActionProvider} in Android 4.0
(API Level 14). An {@link android.view.ActionProvider}, once attached to a menu item in the action
bar, handles both the appearance and behavior of that item. In the case of {@link
@@ -47,36 +47,48 @@ starting with API Level 14 and higher.
Update Menu Declarations
-To get started with {@link android.widget.ShareActionProvider ShareActionProviders}, define the android:actionProviderClass attribute for the corresponding <item> in your menu resource file:
+
+ To get started with {@link android.widget.ShareActionProvider ShareActionProviders},
+ define the android:actionProviderClass attribute for the corresponding
+ <item> in your menu resource file:
<menu xmlns:android="http://schemas.android.com/apk/res/android">
- <item android:id="@+id/menu_item_share"
- android:showAsAction="ifRoom"
- android:title="Share"
- android:actionProviderClass="android.widget.ShareActionProvider" />
+ <item
+ android:id="@+id/menu_item_share"
+ android:showAsAction="ifRoom"
+ android:title="Share"
+ android:actionProviderClass=
+ "android.widget.ShareActionProvider" />
...
</menu>
-This delegates responsibility for the item's appearance and function to
-{@link android.widget.ShareActionProvider}. However, you will need to tell the provider what you
-would like to share.
+
+ This delegates responsibility for the item's appearance and function to
+ {@link android.widget.ShareActionProvider}. However, you will need to tell the provider what you
+ would like to share.
+
Set the Share Intent
-In order for {@link android.widget.ShareActionProvider} to function, you must provide it a share
-intent. This share intent should be the same as described in the Sending Content to Other Apps
-lesson, with action {@link android.content.Intent#ACTION_SEND} and additional data set via extras
-like {@link android.content.Intent#EXTRA_TEXT} and {@link android.content.Intent#EXTRA_STREAM}. To
-assign a share intent, first find the corresponding {@link android.view.MenuItem} while inflating
-your menu resource in your {@link android.app.Activity} or {@link android.app.Fragment}. Next, call
-{@link android.view.MenuItem#getActionProvider() MenuItem.getActionProvider()} to retreive an
-instance of {@link android.widget.ShareActionProvider}. Use {@link
-android.widget.ShareActionProvider#setShareIntent(android.content.Intent) setShareIntent()} to
-update the share intent associated with that action item. Here's an example:
+
+ In order for {@link android.widget.ShareActionProvider} to function, you must provide it a share
+ intent. This share intent should be the same as described in the
+ Sending Simple Data to Other Apps lesson,
+ with action {@link android.content.Intent#ACTION_SEND} and additional data set via extras
+ like {@link android.content.Intent#EXTRA_TEXT} and {@link android.content.Intent#EXTRA_STREAM}.
+ To assign a share intent, first find the corresponding {@link android.view.MenuItem} while
+ inflating your menu resource in your {@link android.app.Activity} or
+ {@link android.app.Fragment}. Next, call {@link android.view.MenuItem#getActionProvider
+ MenuItem.getActionProvider()} to retrieve an instance of
+ {@link android.widget.ShareActionProvider}. Use
+ {@link android.widget.ShareActionProvider#setShareIntent(android.content.Intent)
+ setShareIntent()} to update the share intent associated with that action item. Here's an
+ example:
+
private ShareActionProvider mShareActionProvider;
@@ -105,8 +117,8 @@ private void setShareIntent(Intent shareIntent) {
}
-You may only need to set the share intent once during the creation of your menus, or you may
-want to set it and then update it as the UI changes. For example, when you view photos full screen
+
You may only need to set the share intent once during the creation of your menus, or you may
+want to set it and then update it as the UI changes. For example, when you view photos full screen
in the Gallery app, the sharing intent changes as you flip between photos.
For further discussion about the {@link android.widget.ShareActionProvider} object, see the
-
-
-
-
-
+
+
+
+
+
+
+
+
@@ -423,22 +481,6 @@ include the action bar on devices running Android 2.1 or higher."
-
-
-
-