1page.title=Sending Simple Data to Other Apps
2parent.title=Sharing Simple Data
3parent.link=index.html
4
5trainingnavtop=true
6next.title=Receiving Simple Data from Other Apps
7next.link=receive.html
8
9@jd:body
10
11<div id="tb-wrapper">
12<div id="tb">
13
14<!-- table of contents -->
15<h2>This lesson teaches you to</h2>
16<ol>
17  <li><a href="#send-text-content">Send Text Content</a></li>
18  <li><a href="#send-binary-content">Send Binary Content</a></li>
19  <li><a href="#send-multiple-content">Send Multiple Pieces of Content</a></li>
20</ol>
21
22<!-- other docs (NOT javadocs) -->
23<h2>You should also read</h2>
24<ul>
25  <li><a href="{@docRoot}guide/components/intents-filters.html">Intents and
26Intent Filters</a></li>
27</ul>
28
29</div>
30</div>
31
32<p>When you construct an intent, you must specify the action you want the intent to "trigger."
33Android defines several actions, including {@link android.content.Intent#ACTION_SEND} which, as
34you can probably guess, indicates that the intent is sending data from one activity to another,
35even across process boundaries. To send data to another activity, all you need to do is specify
36the data and its type, the system will identify compatible receiving activities and display them
37to the user (if there are multiple options) or immediately start the activity (if there is only
38one option). Similarly, you can advertise the data types that your activities support receiving
39from other applications by specifying them in your manifest.</p>
40
41<p>Sending and receiving data between applications with intents is most commonly used for social
42sharing of content. Intents allow users to share information quickly and easily, using their
43favorite applications.</p>
44
45<p><strong>Note:</strong> The best way to add a share action item to an
46{@link android.app.ActionBar} is to use {@link android.widget.ShareActionProvider}, which became
47available in API level 14. {@link android.widget.ShareActionProvider} is discussed in the lesson
48about <a href="shareaction.html">Adding an Easy Share Action</a>.</p>
49
50
51<h2 id="send-text-content">Send Text Content</h2>
52
53<div class="figure" style="width:220px">
54<img src="{@docRoot}images/training/sharing/share-text-screenshot.png" alt="" id="figure1" />
55<p class="img-caption">
56  <strong>Figure 1.</strong> Screenshot of {@link android.content.Intent#ACTION_SEND} intent chooser
57on a handset.
58</p>
59</div>
60
61<p>The most straightforward and common use of the {@link android.content.Intent#ACTION_SEND}
62action is sending text content from one activity to another. For example, the built-in Browser
63app can share the URL of the currently-displayed page as text with any application. This is useful
64for sharing an article or website with friends via email or social networking. Here is the code to
65implement this type of sharing:</p>
66
67<pre>
68Intent sendIntent = new Intent();
69sendIntent.setAction(Intent.ACTION_SEND);
70sendIntent.putExtra(Intent.EXTRA_TEXT, &quot;This is my text to send.&quot;);
71sendIntent.setType(&quot;text/plain&quot;);
72startActivity(sendIntent);
73</pre>
74
75<p>If there's an installed application with a filter that matches
76{@link android.content.Intent#ACTION_SEND} and MIME type text/plain, the Android system will run
77it; if more than one application matches, the system displays a disambiguation dialog (a "chooser")
78that allows the user to choose an app.</p>
79
80<p>However, if you call
81{@link android.content.Intent#createChooser(android.content.Intent, CharSequence)
82Intent.createChooser()}, passing it your {@link android.content.Intent} object, it returns a version
83of your intent that will <strong>always display the chooser</strong>. This has some
84advantages:</p>
85
86<ul>
87  <li>Even if the user has previously selected a default action for this intent, the chooser will
88still be displayed.</li>
89  <li>If no applications match, Android displays a system message.</li>
90  <li>You can specify a title for the chooser dialog.</li>
91</ul>
92
93<p>Here's the updated code:</p>
94
95<pre>
96Intent sendIntent = new Intent();
97sendIntent.setAction(Intent.ACTION_SEND);
98sendIntent.putExtra(Intent.EXTRA_TEXT, &quot;This is my text to send.&quot;);
99sendIntent.setType(&quot;text/plain&quot;);
100startActivity(<strong>Intent.createChooser(sendIntent, getResources().getText(R.string.send_to))</strong>);
101</pre>
102
103<p>The resulting dialog is shown in figure 1.</p>
104
105<p>Optionally, you can set some standard extras for the intent:
106{@link android.content.Intent#EXTRA_EMAIL}, {@link android.content.Intent#EXTRA_CC},
107{@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}.
108If the receiving application is not designed to use them, it simply ignores them.</p>
109
110<p class="note"><strong>Note:</strong> Some e-mail applications, such as Gmail, expect a
111{@link java.lang.String String[]} for extras like {@link android.content.Intent#EXTRA_EMAIL} and
112{@link android.content.Intent#EXTRA_CC}, use
113{@link android.content.Intent#putExtra(String,String[]) putExtra(String, String[])} to add these
114to your intent.</p>
115
116
117<h2 id="send-binary-content">Send Binary Content</h2>
118
119<p>Binary data is shared using the {@link android.content.Intent#ACTION_SEND} action combined with
120setting the appropriate MIME type and placing the URI to the data in an extra named {@link
121android.content.Intent#EXTRA_STREAM}. This is commonly used to share an image but can be used to
122share any type of binary content:</p>
123
124<pre>
125Intent shareIntent = new Intent();
126shareIntent.setAction(Intent.ACTION_SEND);
127shareIntent.putExtra(Intent.EXTRA_STREAM, uriToImage);
128shareIntent.setType(&quot;image/jpeg&quot;);
129startActivity(Intent.createChooser(shareIntent, getResources().getText(R.string.send_to)));
130</pre>
131
132<p>Note the following:</p>
133<ul>
134  <li>You can use a MIME type of {@code "*/*"}, but this will only match activities that are able to
135handle generic data streams.</li>
136  <li>The receiving application needs permission to access the data the {@link android.net.Uri}
137points to. The recommended ways to do this are:
138  <ul>
139    <li>Store the data in your own {@link android.content.ContentProvider}, making sure that other
140apps have the correct permission to access your provider. The preferred mechanism for providing
141access is to use <a
142href="{@docRoot}guide/topics/security/permissions.html#uri">per-URI permissions</a> which are
143temporary and only grant access to the receiving application. An easy way to create a
144{@link android.content.ContentProvider} like this is to use the
145{@link android.support.v4.content.FileProvider} helper class.</li>
146    <li>Use the system {@link android.provider.MediaStore}. The {@link android.provider.MediaStore}
147is primarily aimed at video, audio and image MIME types, however beginning with Android 3.0 (API
148level 11) it can also store non-media types (see
149{@link android.provider.MediaStore.Files MediaStore.Files} for more info). Files can be inserted
150into the {@link android.provider.MediaStore} using {@link
151android.media.MediaScannerConnection#scanFile(android.content.Context, java.lang.String[],
152java.lang.String[], android.media.MediaScannerConnection.OnScanCompletedListener) scanFile()} after
153which a {@code content://} style {@link android.net.Uri} suitable for sharing is passed to the
154provided {@link android.media.MediaScannerConnection.OnScanCompletedListener#onScanCompleted(
155java.lang.String, android.net.Uri) onScanCompleted()} callback. Note that once added to the system
156{@link android.provider.MediaStore} the content is accessible to any app on the device.</li>
157  </ul>
158  </li>
159</ul>
160
161
162<h2 id="send-multiple-content">Send Multiple Pieces of Content</h2>
163
164<p>To share multiple pieces of content, use the {@link android.content.Intent#ACTION_SEND_MULTIPLE}
165action together with a list of URIs pointing to the content. The MIME type varies according to the
166mix of content you're sharing. For example, if you share 3 JPEG images, the type is still {@code
167"image/jpeg"}. For a mixture of image types, it should be {@code "image/*"} to match an activity
168that handles any type of image. You should only use {@code "*/*"} if you're sharing out a wide
169variety of types. As previously stated, it's up to the receiving application to parse and process
170your data. Here's an example:</p>
171
172<pre>
173ArrayList&lt;Uri&gt; imageUris = new ArrayList&lt;Uri&gt;();
174imageUris.add(imageUri1); // Add your image URIs here
175imageUris.add(imageUri2);
176
177Intent shareIntent = new Intent();
178shareIntent.setAction(Intent.ACTION_SEND_MULTIPLE);
179shareIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris);
180shareIntent.setType(&quot;image/*&quot;);
181startActivity(Intent.createChooser(shareIntent, &quot;Share images to..&quot;));
182</pre>
183
184<p>As before, make sure the provided {@link android.net.Uri URIs} point to data that a receiving
185application can access.</p>
186
187