1page.title=Sending Content to Other Apps 2parent.title=Sharing Content 3parent.link=index.html 4 5trainingnavtop=true 6next.title=Receiving Content 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 speicify 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, "This is my text to send."); 71sendIntent.setType("text/plain"); 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. If you call 79{@link android.content.Intent#createChooser(android.content.Intent, CharSequence) 80Intent.createChooser()} 81for the intent, Android will <strong>always</strong> display the chooser. This has some 82advantages:</p> 83 84<ul> 85 <li>Even if the user has previously selected a default action for this intent, the chooser will 86still be displayed.</li> 87 <li>If no applications match, Android displays a system message.</li> 88 <li>You can specify a title for the chooser dialog.</li> 89</ul> 90 91<p>Here's the updated code:</p> 92 93<pre> 94Intent sendIntent = new Intent(); 95sendIntent.setAction(Intent.ACTION_SEND); 96sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send."); 97sendIntent.setType("text/plain"); 98startActivity(<strong>Intent.createChooser(sendIntent, getResources().getText(R.string.send_to)</strong>); 99</pre> 100 101<p>The resulting dialog is shown in figure 1.</p> 102 103<p>Optionally, you can set some standard extras for the intent: 104{@link android.content.Intent#EXTRA_EMAIL}, {@link android.content.Intent#EXTRA_CC}, 105{@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}. However, 106if the receiving application is not designed to use them, nothing will happen. You can use 107custom extras as well, but there's no effect unless the receiving application understands them. 108Typically, you'd use custom extras defined by the receiving application itself.</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("image/jpeg"); 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. There are a number of ways to handle this: 138 <ul> 139 <li>Write the data to a file on external/shared storage (such as the SD card), which all apps 140can read. Use {@link android.net.Uri#fromFile(java.io.File) Uri.fromFile()} to create the 141{@link android.net.Uri} that can be passed to the share intent. However, keep in mind that not 142all applications process a {@code file://} style {@link android.net.Uri}.</li> 143 <li>Write the data to a file in your own application directory using {@link 144android.content.Context#openFileOutput(java.lang.String, int) openFileOutput()} with mode {@link 145android.content.Context#MODE_WORLD_READABLE} after which {@link 146android.content.Context#getFileStreamPath(java.lang.String) getFileStreamPath()} can be used to 147return a {@link java.io.File}. As with the previous option, {@link 148android.net.Uri#fromFile(java.io.File) Uri.fromFile()} will create a {@code file://} style {@link 149android.net.Uri} for your share intent.</li> 150 <li>Media files like images, videos and audio can be scanned and added to the system {@link 151android.provider.MediaStore} using {@link 152android.media.MediaScannerConnection#scanFile(android.content.Context, java.lang.String[], 153java.lang.String[], android.media.MediaScannerConnection.OnScanCompletedListener) scanFile()}. The 154{@link 155android.media.MediaScannerConnection.OnScanCompletedListener#onScanCompleted(java.lang.String, 156android.net.Uri) onScanCompleted()} callback returns a {@code content://} style {@link 157android.net.Uri} suitable for including in your share intent.</li> 158 <li>Images can be inserted into the system {@link android.provider.MediaStore} using {@link 159android.provider.MediaStore.Images.Media#insertImage(android.content.ContentResolver, 160android.graphics.Bitmap, java.lang.String, java.lang.String) insertImage()} which will return a 161{@code content://} style {@link android.net.Uri} suitable for including in a share intent.</li> 162 <li>Store the data in your own {@link android.content.ContentProvider}, make sure that other 163apps have the correct permission to access your provider (or use <a 164href="{@docRoot}guide/topics/security/security.html#uri">per-URI permissions</a>).</li> 165 </ul> 166 </li> 167</ul> 168 169 170<h2 id="send-multiple-content">Send Multiple Pieces of Content</h2> 171 172<p>To share multiple pieces of content, use the {@link android.content.Intent#ACTION_SEND_MULTIPLE} 173action together with a list of URIs pointing to the content. The MIME type varies according to the 174mix of content you're sharing. For example, if you share 3 JPEG images, the type is still {@code 175"image/jpeg"}. For a mixture of image types, it should be {@code "image/*"} to match an activity 176that handles any type of image. You should only use {@code "*/*"} if you're sharing out a wide 177variety of types. As previously stated, it's up to the receiving application to parse and process 178your data. Here's an example:</p> 179 180<pre> 181ArrayList<Uri> imageUris = new ArrayList<Uri>(); 182imageUris.add(imageUri1); // Add your image URIs here 183imageUris.add(imageUri2); 184 185Intent shareIntent = new Intent(); 186shareIntent.setAction(Intent.ACTION_SEND_MULTIPLE); 187shareIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris); 188shareIntent.setType("image/*"); 189startActivity(Intent.createChooser(shareIntent, "Share images to..")); 190</pre> 191 192<p>As before, make sure the provided {@link android.net.Uri URIs} point to data that a receiving 193application can access.</p> 194 195
