1 page.title=Sending Simple Data to Other Apps 2 parent.title=Sharing Simple Data 3 parent.link=index.html 4 5 trainingnavtop=true 6 next.title=Receiving Simple Data from Other Apps 7 next.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 26 Intent 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." 33 Android defines several actions, including {@link android.content.Intent#ACTION_SEND} which, as 34 you can probably guess, indicates that the intent is sending data from one activity to another, 35 even across process boundaries. To send data to another activity, all you need to do is specify 36 the data and its type, the system will identify compatible receiving activities and display them 37 to the user (if there are multiple options) or immediately start the activity (if there is only 38 one option). Similarly, you can advertise the data types that your activities support receiving 39 from 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 42 sharing of content. Intents allow users to share information quickly and easily, using their 43 favorite 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 47 available in API level 14. {@link android.widget.ShareActionProvider} is discussed in the lesson 48 about <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 57 on a handset. 58 </p> 59 </div> 60 61 <p>The most straightforward and common use of the {@link android.content.Intent#ACTION_SEND} 62 action is sending text content from one activity to another. For example, the built-in Browser 63 app can share the URL of the currently-displayed page as text with any application. This is useful 64 for sharing an article or website with friends via email or social networking. Here is the code to 65 implement this type of sharing:</p> 66 67 <pre> 68 Intent sendIntent = new Intent(); 69 sendIntent.setAction(Intent.ACTION_SEND); 70 sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send."); 71 sendIntent.setType("text/plain"); 72 startActivity(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 77 it; if more than one application matches, the system displays a disambiguation dialog (a "chooser") 78 that allows the user to choose an app. If you call 79 {@link android.content.Intent#createChooser(android.content.Intent, CharSequence) 80 Intent.createChooser()} 81 for the intent, Android will <strong>always</strong> display the chooser. This has some 82 advantages:</p> 83 84 <ul> 85 <li>Even if the user has previously selected a default action for this intent, the chooser will 86 still 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> 94 Intent sendIntent = new Intent(); 95 sendIntent.setAction(Intent.ACTION_SEND); 96 sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send."); 97 sendIntent.setType("text/plain"); 98 startActivity(<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, 106 if the receiving application is not designed to use them, nothing will happen. You can use 107 custom extras as well, but there's no effect unless the receiving application understands them. 108 Typically, 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 114 to 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 120 setting the appropriate MIME type and placing the URI to the data in an extra named {@link 121 android.content.Intent#EXTRA_STREAM}. This is commonly used to share an image but can be used to 122 share any type of binary content:</p> 123 124 <pre> 125 Intent shareIntent = new Intent(); 126 shareIntent.setAction(Intent.ACTION_SEND); 127 shareIntent.putExtra(Intent.EXTRA_STREAM, uriToImage); 128 shareIntent.setType("image/jpeg"); 129 startActivity(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 135 handle generic data streams.</li> 136 <li>The receiving application needs permission to access the data the {@link android.net.Uri} 137 points 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 140 apps have the correct permission to access your provider. The preferred mechanism for providing 141 access is to use <a 142 href="{@docRoot}guide/topics/security/permissions.html#uri">per-URI permissions</a> which are 143 temporary 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} 147 is primarily aimed at video, audio and image MIME types, however beginning with Android 3.0 (API 148 level 11) it can also store non-media types (see 149 {@link android.provider.MediaStore.Files MediaStore.Files} for more info). Files can be inserted 150 into the {@link android.provider.MediaStore} using {@link 151 android.media.MediaScannerConnection#scanFile(android.content.Context, java.lang.String[], 152 java.lang.String[], android.media.MediaScannerConnection.OnScanCompletedListener) scanFile()} after 153 which a {@code content://} style {@link android.net.Uri} suitable for sharing is passed to the 154 provided {@link android.media.MediaScannerConnection.OnScanCompletedListener#onScanCompleted( 155 java.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} 165 action together with a list of URIs pointing to the content. The MIME type varies according to the 166 mix 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 168 that handles any type of image. You should only use {@code "*/*"} if you're sharing out a wide 169 variety of types. As previously stated, it's up to the receiving application to parse and process 170 your data. Here's an example:</p> 171 172 <pre> 173 ArrayList<Uri> imageUris = new ArrayList<Uri>(); 174 imageUris.add(imageUri1); // Add your image URIs here 175 imageUris.add(imageUri2); 176 177 Intent shareIntent = new Intent(); 178 shareIntent.setAction(Intent.ACTION_SEND_MULTIPLE); 179 shareIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris); 180 shareIntent.setType("image/*"); 181 startActivity(Intent.createChooser(shareIntent, "Share images to..")); 182 </pre> 183 184 <p>As before, make sure the provided {@link android.net.Uri URIs} point to data that a receiving 185 application can access.</p> 186 187
