Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2013 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package android.provider; |
| 18 | |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 19 | import static android.provider.DocumentsContract.METHOD_COPY_DOCUMENT; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 20 | import static android.provider.DocumentsContract.METHOD_CREATE_DOCUMENT; |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 21 | import static android.provider.DocumentsContract.METHOD_CREATE_WEB_LINK_INTENT; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 22 | import static android.provider.DocumentsContract.METHOD_DELETE_DOCUMENT; |
Ben Lin | e7822fb | 2016-06-24 15:21:08 -0700 | [diff] [blame] | 23 | import static android.provider.DocumentsContract.METHOD_EJECT_ROOT; |
Garfield Tan | 3f6b68a | 2016-11-01 14:13:38 -0700 | [diff] [blame] | 24 | import static android.provider.DocumentsContract.METHOD_FIND_DOCUMENT_PATH; |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 25 | import static android.provider.DocumentsContract.METHOD_GET_DOCUMENT_METADATA; |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 26 | import static android.provider.DocumentsContract.METHOD_IS_CHILD_DOCUMENT; |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 27 | import static android.provider.DocumentsContract.METHOD_MOVE_DOCUMENT; |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 28 | import static android.provider.DocumentsContract.METHOD_REMOVE_DOCUMENT; |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 29 | import static android.provider.DocumentsContract.METHOD_RENAME_DOCUMENT; |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 30 | import static android.provider.DocumentsContract.buildDocumentUri; |
| 31 | import static android.provider.DocumentsContract.buildDocumentUriMaybeUsingTree; |
| 32 | import static android.provider.DocumentsContract.buildTreeDocumentUri; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 33 | import static android.provider.DocumentsContract.getDocumentId; |
| 34 | import static android.provider.DocumentsContract.getRootId; |
| 35 | import static android.provider.DocumentsContract.getSearchDocumentsQuery; |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 36 | import static android.provider.DocumentsContract.getTreeDocumentId; |
| 37 | import static android.provider.DocumentsContract.isTreeUri; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 38 | |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 39 | import android.Manifest; |
Tor Norbye | c615c6f | 2015-03-02 10:11:44 -0800 | [diff] [blame] | 40 | import android.annotation.CallSuper; |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 41 | import android.annotation.Nullable; |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 42 | import android.app.AuthenticationRequiredException; |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 43 | import android.content.ClipDescription; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 44 | import android.content.ContentProvider; |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 45 | import android.content.ContentResolver; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 46 | import android.content.ContentValues; |
| 47 | import android.content.Context; |
| 48 | import android.content.Intent; |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 49 | import android.content.IntentSender; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 50 | import android.content.UriMatcher; |
Jeff Sharkey | e37ea61 | 2013-09-04 14:30:31 -0700 | [diff] [blame] | 51 | import android.content.pm.PackageManager; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 52 | import android.content.pm.ProviderInfo; |
| 53 | import android.content.res.AssetFileDescriptor; |
| 54 | import android.database.Cursor; |
| 55 | import android.graphics.Point; |
| 56 | import android.net.Uri; |
| 57 | import android.os.Bundle; |
| 58 | import android.os.CancellationSignal; |
| 59 | import android.os.ParcelFileDescriptor; |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 60 | import android.os.ParcelableException; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 61 | import android.provider.DocumentsContract.Document; |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 62 | import android.provider.DocumentsContract.Path; |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 63 | import android.provider.DocumentsContract.Root; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 64 | import android.util.Log; |
| 65 | |
| 66 | import libcore.io.IoUtils; |
| 67 | |
| 68 | import java.io.FileNotFoundException; |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 69 | import java.util.LinkedList; |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 70 | import java.util.Objects; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 71 | |
| 72 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 73 | * Base class for a document provider. A document provider offers read and write |
| 74 | * access to durable files, such as files stored on a local disk, or files in a |
| 75 | * cloud storage service. To create a document provider, extend this class, |
| 76 | * implement the abstract methods, and add it to your manifest like this: |
| 77 | * |
| 78 | * <pre class="prettyprint"><manifest> |
| 79 | * ... |
| 80 | * <application> |
| 81 | * ... |
| 82 | * <provider |
| 83 | * android:name="com.example.MyCloudProvider" |
| 84 | * android:authorities="com.example.mycloudprovider" |
| 85 | * android:exported="true" |
| 86 | * android:grantUriPermissions="true" |
Jeff Sharkey | 3b94540 | 2013-11-13 13:31:09 -0800 | [diff] [blame] | 87 | * android:permission="android.permission.MANAGE_DOCUMENTS" |
| 88 | * android:enabled="@bool/isAtLeastKitKat"> |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 89 | * <intent-filter> |
| 90 | * <action android:name="android.content.action.DOCUMENTS_PROVIDER" /> |
| 91 | * </intent-filter> |
| 92 | * </provider> |
| 93 | * ... |
| 94 | * </application> |
| 95 | *</manifest></pre> |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 96 | * <p> |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 97 | * When defining your provider, you must protect it with |
| 98 | * {@link android.Manifest.permission#MANAGE_DOCUMENTS}, which is a permission |
| 99 | * only the system can obtain. Applications cannot use a documents provider |
| 100 | * directly; they must go through {@link Intent#ACTION_OPEN_DOCUMENT} or |
| 101 | * {@link Intent#ACTION_CREATE_DOCUMENT} which requires a user to actively |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 102 | * navigate and select documents. When a user selects documents through that UI, |
| 103 | * the system issues narrow URI permission grants to the requesting application. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 104 | * </p> |
| 105 | * <h3>Documents</h3> |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 106 | * <p> |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 107 | * A document can be either an openable stream (with a specific MIME type), or a |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 108 | * directory containing additional documents (with the |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 109 | * {@link Document#MIME_TYPE_DIR} MIME type). Each directory represents the top |
| 110 | * of a subtree containing zero or more documents, which can recursively contain |
| 111 | * even more documents and directories. |
| 112 | * </p> |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 113 | * <p> |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 114 | * Each document can have different capabilities, as described by |
| 115 | * {@link Document#COLUMN_FLAGS}. For example, if a document can be represented |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 116 | * as a thumbnail, your provider can set |
| 117 | * {@link Document#FLAG_SUPPORTS_THUMBNAIL} and implement |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 118 | * {@link #openDocumentThumbnail(String, Point, CancellationSignal)} to return |
| 119 | * that thumbnail. |
| 120 | * </p> |
| 121 | * <p> |
| 122 | * Each document under a provider is uniquely referenced by its |
| 123 | * {@link Document#COLUMN_DOCUMENT_ID}, which must not change once returned. A |
| 124 | * single document can be included in multiple directories when responding to |
| 125 | * {@link #queryChildDocuments(String, String[], String)}. For example, a |
| 126 | * provider might surface a single photo in multiple locations: once in a |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 127 | * directory of geographic locations, and again in a directory of dates. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 128 | * </p> |
| 129 | * <h3>Roots</h3> |
| 130 | * <p> |
| 131 | * All documents are surfaced through one or more "roots." Each root represents |
| 132 | * the top of a document tree that a user can navigate. For example, a root |
| 133 | * could represent an account or a physical storage device. Similar to |
| 134 | * documents, each root can have capabilities expressed through |
| 135 | * {@link Root#COLUMN_FLAGS}. |
| 136 | * </p> |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 137 | * |
| 138 | * @see Intent#ACTION_OPEN_DOCUMENT |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 139 | * @see Intent#ACTION_OPEN_DOCUMENT_TREE |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 140 | * @see Intent#ACTION_CREATE_DOCUMENT |
| 141 | */ |
| 142 | public abstract class DocumentsProvider extends ContentProvider { |
| 143 | private static final String TAG = "DocumentsProvider"; |
| 144 | |
Jeff Sharkey | a61dc8e | 2013-09-05 17:14:14 -0700 | [diff] [blame] | 145 | private static final int MATCH_ROOTS = 1; |
| 146 | private static final int MATCH_ROOT = 2; |
| 147 | private static final int MATCH_RECENT = 3; |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 148 | private static final int MATCH_SEARCH = 4; |
| 149 | private static final int MATCH_DOCUMENT = 5; |
| 150 | private static final int MATCH_CHILDREN = 6; |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 151 | private static final int MATCH_DOCUMENT_TREE = 7; |
| 152 | private static final int MATCH_CHILDREN_TREE = 8; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 153 | |
| 154 | private String mAuthority; |
| 155 | |
| 156 | private UriMatcher mMatcher; |
| 157 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 158 | /** |
| 159 | * Implementation is provided by the parent class. |
| 160 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 161 | @Override |
| 162 | public void attachInfo(Context context, ProviderInfo info) { |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 163 | registerAuthority(info.authority); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 164 | |
| 165 | // Sanity check our setup |
| 166 | if (!info.exported) { |
| 167 | throw new SecurityException("Provider must be exported"); |
| 168 | } |
| 169 | if (!info.grantUriPermissions) { |
| 170 | throw new SecurityException("Provider must grantUriPermissions"); |
| 171 | } |
| 172 | if (!android.Manifest.permission.MANAGE_DOCUMENTS.equals(info.readPermission) |
| 173 | || !android.Manifest.permission.MANAGE_DOCUMENTS.equals(info.writePermission)) { |
| 174 | throw new SecurityException("Provider must be protected by MANAGE_DOCUMENTS"); |
| 175 | } |
| 176 | |
| 177 | super.attachInfo(context, info); |
| 178 | } |
| 179 | |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 180 | /** {@hide} */ |
| 181 | @Override |
| 182 | public void attachInfoForTesting(Context context, ProviderInfo info) { |
| 183 | registerAuthority(info.authority); |
| 184 | |
| 185 | super.attachInfoForTesting(context, info); |
| 186 | } |
| 187 | |
| 188 | private void registerAuthority(String authority) { |
| 189 | mAuthority = authority; |
| 190 | |
| 191 | mMatcher = new UriMatcher(UriMatcher.NO_MATCH); |
| 192 | mMatcher.addURI(mAuthority, "root", MATCH_ROOTS); |
| 193 | mMatcher.addURI(mAuthority, "root/*", MATCH_ROOT); |
| 194 | mMatcher.addURI(mAuthority, "root/*/recent", MATCH_RECENT); |
| 195 | mMatcher.addURI(mAuthority, "root/*/search", MATCH_SEARCH); |
| 196 | mMatcher.addURI(mAuthority, "document/*", MATCH_DOCUMENT); |
| 197 | mMatcher.addURI(mAuthority, "document/*/children", MATCH_CHILDREN); |
| 198 | mMatcher.addURI(mAuthority, "tree/*/document/*", MATCH_DOCUMENT_TREE); |
| 199 | mMatcher.addURI(mAuthority, "tree/*/document/*/children", MATCH_CHILDREN_TREE); |
| 200 | } |
| 201 | |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 202 | /** |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 203 | * Test if a document is descendant (child, grandchild, etc) from the given |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 204 | * parent. For example, providers must implement this to support |
| 205 | * {@link Intent#ACTION_OPEN_DOCUMENT_TREE}. You should avoid making network |
| 206 | * requests to keep this request fast. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 207 | * |
| 208 | * @param parentDocumentId parent to verify against. |
| 209 | * @param documentId child to verify. |
| 210 | * @return if given document is a descendant of the given parent. |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 211 | * @see DocumentsContract.Root#FLAG_SUPPORTS_IS_CHILD |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 212 | */ |
| 213 | public boolean isChildDocument(String parentDocumentId, String documentId) { |
| 214 | return false; |
| 215 | } |
| 216 | |
| 217 | /** {@hide} */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 218 | private void enforceTree(Uri documentUri) { |
| 219 | if (isTreeUri(documentUri)) { |
| 220 | final String parent = getTreeDocumentId(documentUri); |
| 221 | final String child = getDocumentId(documentUri); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 222 | if (Objects.equals(parent, child)) { |
| 223 | return; |
| 224 | } |
| 225 | if (!isChildDocument(parent, child)) { |
| 226 | throw new SecurityException( |
| 227 | "Document " + child + " is not a descendant of " + parent); |
| 228 | } |
| 229 | } |
| 230 | } |
| 231 | |
| 232 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 233 | * Create a new document and return its newly generated |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 234 | * {@link Document#COLUMN_DOCUMENT_ID}. You must allocate a new |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 235 | * {@link Document#COLUMN_DOCUMENT_ID} to represent the document, which must |
| 236 | * not change once returned. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 237 | * |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 238 | * @param parentDocumentId the parent directory to create the new document |
| 239 | * under. |
| 240 | * @param mimeType the concrete MIME type associated with the new document. |
| 241 | * If the MIME type is not supported, the provider must throw. |
| 242 | * @param displayName the display name of the new document. The provider may |
| 243 | * alter this name to meet any internal constraints, such as |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 244 | * avoiding conflicting names. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 245 | |
| 246 | * @throws AuthenticationRequiredException If authentication is required from the user (such as |
| 247 | * login credentials), but it is not guaranteed that the client will handle this |
| 248 | * properly. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 249 | */ |
| 250 | @SuppressWarnings("unused") |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 251 | public String createDocument(String parentDocumentId, String mimeType, String displayName) |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 252 | throws FileNotFoundException { |
| 253 | throw new UnsupportedOperationException("Create not supported"); |
| 254 | } |
| 255 | |
| 256 | /** |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 257 | * Rename an existing document. |
| 258 | * <p> |
| 259 | * If a different {@link Document#COLUMN_DOCUMENT_ID} must be used to |
| 260 | * represent the renamed document, generate and return it. Any outstanding |
| 261 | * URI permission grants will be updated to point at the new document. If |
| 262 | * the original {@link Document#COLUMN_DOCUMENT_ID} is still valid after the |
| 263 | * rename, return {@code null}. |
| 264 | * |
| 265 | * @param documentId the document to rename. |
| 266 | * @param displayName the updated display name of the document. The provider |
| 267 | * may alter this name to meet any internal constraints, such as |
| 268 | * avoiding conflicting names. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 269 | * @throws AuthenticationRequiredException If authentication is required from |
| 270 | * the user (such as login credentials), but it is not guaranteed |
| 271 | * that the client will handle this properly. |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 272 | */ |
| 273 | @SuppressWarnings("unused") |
| 274 | public String renameDocument(String documentId, String displayName) |
| 275 | throws FileNotFoundException { |
| 276 | throw new UnsupportedOperationException("Rename not supported"); |
| 277 | } |
| 278 | |
| 279 | /** |
| 280 | * Delete the requested document. |
| 281 | * <p> |
| 282 | * Upon returning, any URI permission grants for the given document will be |
| 283 | * revoked. If additional documents were deleted as a side effect of this |
| 284 | * call (such as documents inside a directory) the implementor is |
| 285 | * responsible for revoking those permissions using |
| 286 | * {@link #revokeDocumentPermission(String)}. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 287 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 288 | * @param documentId the document to delete. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 289 | * @throws AuthenticationRequiredException If authentication is required from |
| 290 | * the user (such as login credentials), but it is not guaranteed |
| 291 | * that the client will handle this properly. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 292 | */ |
| 293 | @SuppressWarnings("unused") |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 294 | public void deleteDocument(String documentId) throws FileNotFoundException { |
| 295 | throw new UnsupportedOperationException("Delete not supported"); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 296 | } |
| 297 | |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 298 | /** |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 299 | * Copy the requested document or a document tree. |
| 300 | * <p> |
| 301 | * Copies a document including all child documents to another location within |
| 302 | * the same document provider. Upon completion returns the document id of |
| 303 | * the copied document at the target destination. {@code null} must never |
| 304 | * be returned. |
| 305 | * |
| 306 | * @param sourceDocumentId the document to copy. |
| 307 | * @param targetParentDocumentId the target document to be copied into as a child. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 308 | * @throws AuthenticationRequiredException If authentication is required from |
| 309 | * the user (such as login credentials), but it is not guaranteed |
| 310 | * that the client will handle this properly. |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 311 | */ |
| 312 | @SuppressWarnings("unused") |
| 313 | public String copyDocument(String sourceDocumentId, String targetParentDocumentId) |
| 314 | throws FileNotFoundException { |
| 315 | throw new UnsupportedOperationException("Copy not supported"); |
| 316 | } |
| 317 | |
| 318 | /** |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 319 | * Move the requested document or a document tree. |
Tomasz Mikolajewski | eeb8b60 | 2016-01-28 13:00:12 +0900 | [diff] [blame] | 320 | * |
| 321 | * <p>Moves a document including all child documents to another location within |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 322 | * the same document provider. Upon completion returns the document id of |
| 323 | * the copied document at the target destination. {@code null} must never |
| 324 | * be returned. |
| 325 | * |
Tomasz Mikolajewski | eeb8b60 | 2016-01-28 13:00:12 +0900 | [diff] [blame] | 326 | * <p>It's the responsibility of the provider to revoke grants if the document |
| 327 | * is no longer accessible using <code>sourceDocumentId</code>. |
| 328 | * |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 329 | * @param sourceDocumentId the document to move. |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 330 | * @param sourceParentDocumentId the parent of the document to move. |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 331 | * @param targetParentDocumentId the target document to be a new parent of the |
| 332 | * source document. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 333 | * @throws AuthenticationRequiredException If authentication is required from |
| 334 | * the user (such as login credentials), but it is not guaranteed |
| 335 | * that the client will handle this properly. |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 336 | */ |
| 337 | @SuppressWarnings("unused") |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 338 | public String moveDocument(String sourceDocumentId, String sourceParentDocumentId, |
| 339 | String targetParentDocumentId) |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 340 | throws FileNotFoundException { |
| 341 | throw new UnsupportedOperationException("Move not supported"); |
| 342 | } |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 343 | |
| 344 | /** |
| 345 | * Removes the requested document or a document tree. |
| 346 | * |
| 347 | * <p>In contrast to {@link #deleteDocument} it requires specifying the parent. |
| 348 | * This method is especially useful if the document can be in multiple parents. |
| 349 | * |
| 350 | * <p>It's the responsibility of the provider to revoke grants if the document is |
| 351 | * removed from the last parent, and effectively the document is deleted. |
| 352 | * |
| 353 | * @param documentId the document to remove. |
| 354 | * @param parentDocumentId the parent of the document to move. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 355 | * @throws AuthenticationRequiredException If authentication is required from |
| 356 | * the user (such as login credentials), but it is not guaranteed |
| 357 | * that the client will handle this properly. |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 358 | */ |
| 359 | @SuppressWarnings("unused") |
Tomasz Mikolajewski | 3071401 | 2016-02-15 17:07:37 +0900 | [diff] [blame] | 360 | public void removeDocument(String documentId, String parentDocumentId) |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 361 | throws FileNotFoundException { |
| 362 | throw new UnsupportedOperationException("Remove not supported"); |
| 363 | } |
| 364 | |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 365 | /** |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 366 | * Finds the canonical path for the requested document. The path must start |
| 367 | * from the parent document if parentDocumentId is not null or the root document |
| 368 | * if parentDocumentId is null. If there are more than one path to this document, |
| 369 | * return the most typical one. Include both the parent document or root document |
| 370 | * and the requested document in the returned path. |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 371 | * |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 372 | * <p>This API assumes that document ID has enough info to infer the root. |
| 373 | * Different roots should use different document ID to refer to the same |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 374 | * document. |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 375 | * |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 376 | * |
Garfield Tan | 3f6b68a | 2016-11-01 14:13:38 -0700 | [diff] [blame] | 377 | * @param parentDocumentId the document from which the path starts if not null, |
| 378 | * or null to indicate a path from the root is requested. |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 379 | * @param childDocumentId the document which path is requested. |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 380 | * @return the path of the requested document. If parentDocumentId is null |
| 381 | * returned root ID must not be null. If parentDocumentId is not null |
| 382 | * returned root ID must be null. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 383 | * @throws AuthenticationRequiredException If authentication is required from |
| 384 | * the user (such as login credentials), but it is not guaranteed |
| 385 | * that the client will handle this properly. |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 386 | */ |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 387 | public Path findDocumentPath(@Nullable String parentDocumentId, String childDocumentId) |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 388 | throws FileNotFoundException { |
Garfield Tan | 3f6b68a | 2016-11-01 14:13:38 -0700 | [diff] [blame] | 389 | throw new UnsupportedOperationException("findDocumentPath not supported."); |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 390 | } |
| 391 | |
| 392 | /** |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 393 | * Creates an intent sender for a web link, if the document is web linkable. |
| 394 | * <p> |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 395 | * {@link AuthenticationRequiredException} can be thrown if user does not have |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 396 | * sufficient permission for the linked document. Before any new permissions |
| 397 | * are granted for the linked document, a visible UI must be shown, so the |
| 398 | * user can explicitly confirm whether the permission grants are expected. |
| 399 | * The user must be able to cancel the operation. |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 400 | * <p> |
| 401 | * Options passed as an argument may include a list of recipients, such |
| 402 | * as email addresses. The provider should reflect these options if possible, |
| 403 | * but it's acceptable to ignore them. In either case, confirmation UI must |
| 404 | * be shown before any new permission grants are granted. |
| 405 | * <p> |
| 406 | * It is all right to generate a web link without granting new permissions, |
| 407 | * if opening the link would result in a page for requesting permission |
| 408 | * access. If it's impossible then the operation must fail by throwing an exception. |
| 409 | * |
| 410 | * @param documentId the document to create a web link intent for. |
| 411 | * @param options additional information, such as list of recipients. Optional. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 412 | * @throws AuthenticationRequiredException If authentication is required from |
| 413 | * the user (such as login credentials), but it is not guaranteed |
| 414 | * that the client will handle this properly. |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 415 | * |
| 416 | * @see DocumentsContract.Document#FLAG_WEB_LINKABLE |
| 417 | * @see android.app.PendingIntent#getIntentSender |
| 418 | */ |
| 419 | public IntentSender createWebLinkIntent(String documentId, @Nullable Bundle options) |
| 420 | throws FileNotFoundException { |
| 421 | throw new UnsupportedOperationException("createWebLink is not supported."); |
| 422 | } |
| 423 | |
| 424 | /** |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 425 | * Return all roots currently provided. To display to users, you must define |
| 426 | * at least one root. You should avoid making network requests to keep this |
| 427 | * request fast. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 428 | * <p> |
| 429 | * Each root is defined by the metadata columns described in {@link Root}, |
| 430 | * including {@link Root#COLUMN_DOCUMENT_ID} which points to a directory |
| 431 | * representing a tree of documents to display under that root. |
| 432 | * <p> |
| 433 | * If this set of roots changes, you must call {@link ContentResolver#notifyChange(Uri, |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 434 | * android.database.ContentObserver, boolean)} with |
| 435 | * {@link DocumentsContract#buildRootsUri(String)} to notify the system. |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 436 | * <p> |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 437 | * |
| 438 | * @param projection list of {@link Root} columns to put into the cursor. If |
| 439 | * {@code null} all supported columns should be included. |
| 440 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 441 | public abstract Cursor queryRoots(String[] projection) throws FileNotFoundException; |
| 442 | |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 443 | /** |
| 444 | * Return recently modified documents under the requested root. This will |
| 445 | * only be called for roots that advertise |
| 446 | * {@link Root#FLAG_SUPPORTS_RECENTS}. The returned documents should be |
| 447 | * sorted by {@link Document#COLUMN_LAST_MODIFIED} in descending order, and |
| 448 | * limited to only return the 64 most recently modified documents. |
Jeff Sharkey | 37ed78e | 2013-11-05 12:38:21 -0800 | [diff] [blame] | 449 | * <p> |
| 450 | * Recent documents do not support change notifications. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 451 | * |
| 452 | * @param projection list of {@link Document} columns to put into the |
| 453 | * cursor. If {@code null} all supported columns should be |
| 454 | * included. |
| 455 | * @see DocumentsContract#EXTRA_LOADING |
| 456 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 457 | @SuppressWarnings("unused") |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 458 | public Cursor queryRecentDocuments(String rootId, String[] projection) |
| 459 | throws FileNotFoundException { |
| 460 | throw new UnsupportedOperationException("Recent not supported"); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 461 | } |
| 462 | |
| 463 | /** |
Risan | 6a4a8f6 | 2018-10-30 17:57:56 -0600 | [diff] [blame] | 464 | * Return recently modified documents under the requested root. This will |
| 465 | * only be called for roots that advertise |
| 466 | * {@link Root#FLAG_SUPPORTS_RECENTS}. The returned documents should be |
| 467 | * sorted by {@link Document#COLUMN_LAST_MODIFIED} in descending order of |
| 468 | * the most recently modified documents. |
| 469 | * <p> |
| 470 | * If this method is overriden by the concrete DocumentsProvider and |
| 471 | * QUERY_ARGS_LIMIT is specified with a nonnegative int under queryArgs, the |
| 472 | * result will be limited by that number and QUERY_ARG_LIMIT will be |
| 473 | * specified under EXTRA_HONORED_ARGS. Otherwise, a default 64 limit will |
| 474 | * be used and no QUERY_ARG* will be specified under EXTRA_HONORED_ARGS. |
| 475 | * <p> |
| 476 | * Recent documents do not support change notifications. |
| 477 | * |
| 478 | * @param projection list of {@link Document} columns to put into the |
| 479 | * cursor. If {@code null} all supported columns should be |
| 480 | * included. |
| 481 | * @param queryArgs the extra query arguments. |
| 482 | * @param signal used by the caller to signal if the request should be |
| 483 | * cancelled. May be null. |
| 484 | * @see DocumentsContract#EXTRA_LOADING |
| 485 | */ |
| 486 | @SuppressWarnings("unused") |
| 487 | public Cursor queryRecentDocuments( |
| 488 | String rootId, String[] projection, @Nullable Bundle queryArgs, |
| 489 | @Nullable CancellationSignal signal) |
| 490 | throws FileNotFoundException { |
| 491 | Cursor c = queryRecentDocuments(rootId, projection); |
| 492 | Bundle extras = new Bundle(); |
| 493 | c.setExtras(extras); |
| 494 | extras.putStringArray(ContentResolver.EXTRA_HONORED_ARGS, new String[0]); |
| 495 | return c; |
| 496 | } |
| 497 | |
| 498 | /** |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 499 | * Return metadata for the single requested document. You should avoid |
| 500 | * making network requests to keep this request fast. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 501 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 502 | * @param documentId the document to return. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 503 | * @param projection list of {@link Document} columns to put into the |
| 504 | * cursor. If {@code null} all supported columns should be |
| 505 | * included. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 506 | * @throws AuthenticationRequiredException If authentication is required from |
| 507 | * the user (such as login credentials), but it is not guaranteed |
| 508 | * that the client will handle this properly. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 509 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 510 | public abstract Cursor queryDocument(String documentId, String[] projection) |
| 511 | throws FileNotFoundException; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 512 | |
| 513 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 514 | * Return the children documents contained in the requested directory. This |
| 515 | * must only return immediate descendants, as additional queries will be |
| 516 | * issued to recursively explore the tree. |
| 517 | * <p> |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 518 | * Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher |
| 519 | * should override {@link #queryChildDocuments(String, String[], Bundle)}. |
| 520 | * <p> |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 521 | * If your provider is cloud-based, and you have some data cached or pinned |
| 522 | * locally, you may return the local data immediately, setting |
| 523 | * {@link DocumentsContract#EXTRA_LOADING} on the Cursor to indicate that |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 524 | * you are still fetching additional data. Then, when the network data is |
| 525 | * available, you can send a change notification to trigger a requery and |
Jeff Sharkey | 3b94540 | 2013-11-13 13:31:09 -0800 | [diff] [blame] | 526 | * return the complete contents. To return a Cursor with extras, you need to |
| 527 | * extend and override {@link Cursor#getExtras()}. |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 528 | * <p> |
| 529 | * To support change notifications, you must |
| 530 | * {@link Cursor#setNotificationUri(ContentResolver, Uri)} with a relevant |
| 531 | * Uri, such as |
| 532 | * {@link DocumentsContract#buildChildDocumentsUri(String, String)}. Then |
| 533 | * you can call {@link ContentResolver#notifyChange(Uri, |
| 534 | * android.database.ContentObserver, boolean)} with that Uri to send change |
| 535 | * notifications. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 536 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 537 | * @param parentDocumentId the directory to return children for. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 538 | * @param projection list of {@link Document} columns to put into the |
| 539 | * cursor. If {@code null} all supported columns should be |
| 540 | * included. |
| 541 | * @param sortOrder how to order the rows, formatted as an SQL |
| 542 | * {@code ORDER BY} clause (excluding the ORDER BY itself). |
| 543 | * Passing {@code null} will use the default sort order, which |
| 544 | * may be unordered. This ordering is a hint that can be used to |
| 545 | * prioritize how data is fetched from the network, but UI may |
| 546 | * always enforce a specific ordering. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 547 | * @throws AuthenticationRequiredException If authentication is required from |
| 548 | * the user (such as login credentials), but it is not guaranteed |
| 549 | * that the client will handle this properly. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 550 | * @see DocumentsContract#EXTRA_LOADING |
| 551 | * @see DocumentsContract#EXTRA_INFO |
| 552 | * @see DocumentsContract#EXTRA_ERROR |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 553 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 554 | public abstract Cursor queryChildDocuments( |
| 555 | String parentDocumentId, String[] projection, String sortOrder) |
| 556 | throws FileNotFoundException; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 557 | |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 558 | /** |
| 559 | * Override this method to return the children documents contained |
| 560 | * in the requested directory. This must return immediate descendants only. |
| 561 | * |
| 562 | * <p>If your provider is cloud-based, and you have data cached |
| 563 | * locally, you may return the local data immediately, setting |
| 564 | * {@link DocumentsContract#EXTRA_LOADING} on Cursor extras to indicate that |
| 565 | * you are still fetching additional data. Then, when the network data is |
| 566 | * available, you can send a change notification to trigger a requery and |
| 567 | * return the complete contents. To return a Cursor with extras, you need to |
| 568 | * extend and override {@link Cursor#getExtras()}. |
| 569 | * |
| 570 | * <p>To support change notifications, you must |
| 571 | * {@link Cursor#setNotificationUri(ContentResolver, Uri)} with a relevant |
| 572 | * Uri, such as |
| 573 | * {@link DocumentsContract#buildChildDocumentsUri(String, String)}. Then |
| 574 | * you can call {@link ContentResolver#notifyChange(Uri, |
| 575 | * android.database.ContentObserver, boolean)} with that Uri to send change |
| 576 | * notifications. |
| 577 | * |
| 578 | * @param parentDocumentId the directory to return children for. |
| 579 | * @param projection list of {@link Document} columns to put into the |
| 580 | * cursor. If {@code null} all supported columns should be |
| 581 | * included. |
| 582 | * @param queryArgs Bundle containing sorting information or other |
| 583 | * argument useful to the provider. If no sorting |
| 584 | * information is available, default sorting |
| 585 | * will be used, which may be unordered. See |
| 586 | * {@link ContentResolver#QUERY_ARG_SORT_COLUMNS} for |
| 587 | * details. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 588 | * @throws AuthenticationRequiredException If authentication is required from |
| 589 | * the user (such as login credentials), but it is not guaranteed |
| 590 | * that the client will handle this properly. |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 591 | * |
| 592 | * @see DocumentsContract#EXTRA_LOADING |
| 593 | * @see DocumentsContract#EXTRA_INFO |
| 594 | * @see DocumentsContract#EXTRA_ERROR |
| 595 | */ |
| 596 | public Cursor queryChildDocuments( |
| 597 | String parentDocumentId, @Nullable String[] projection, @Nullable Bundle queryArgs) |
| 598 | throws FileNotFoundException { |
| 599 | |
| 600 | return queryChildDocuments( |
| 601 | parentDocumentId, projection, getSortClause(queryArgs)); |
| 602 | } |
| 603 | |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 604 | /** {@hide} */ |
| 605 | @SuppressWarnings("unused") |
| 606 | public Cursor queryChildDocumentsForManage( |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 607 | String parentDocumentId, @Nullable String[] projection, @Nullable String sortOrder) |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 608 | throws FileNotFoundException { |
| 609 | throw new UnsupportedOperationException("Manage not supported"); |
| 610 | } |
| 611 | |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 612 | /** |
Mark Doliner | d0646dc | 2014-08-27 16:04:02 -0700 | [diff] [blame] | 613 | * Return documents that match the given query under the requested |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 614 | * root. The returned documents should be sorted by relevance in descending |
| 615 | * order. How documents are matched against the query string is an |
| 616 | * implementation detail left to each provider, but it's suggested that at |
| 617 | * least {@link Document#COLUMN_DISPLAY_NAME} be matched in a |
| 618 | * case-insensitive fashion. |
| 619 | * <p> |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 620 | * If your provider is cloud-based, and you have some data cached or pinned |
| 621 | * locally, you may return the local data immediately, setting |
| 622 | * {@link DocumentsContract#EXTRA_LOADING} on the Cursor to indicate that |
| 623 | * you are still fetching additional data. Then, when the network data is |
| 624 | * available, you can send a change notification to trigger a requery and |
| 625 | * return the complete contents. |
| 626 | * <p> |
| 627 | * To support change notifications, you must |
| 628 | * {@link Cursor#setNotificationUri(ContentResolver, Uri)} with a relevant |
| 629 | * Uri, such as {@link DocumentsContract#buildSearchDocumentsUri(String, |
| 630 | * String, String)}. Then you can call {@link ContentResolver#notifyChange(Uri, |
| 631 | * android.database.ContentObserver, boolean)} with that Uri to send change |
| 632 | * notifications. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 633 | * |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 634 | * @param rootId the root to search under. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 635 | * @param query string to match documents against. |
| 636 | * @param projection list of {@link Document} columns to put into the |
| 637 | * cursor. If {@code null} all supported columns should be |
| 638 | * included. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 639 | * @throws AuthenticationRequiredException If authentication is required from |
| 640 | * the user (such as login credentials), but it is not guaranteed |
| 641 | * that the client will handle this properly. |
| 642 | * |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 643 | * @see DocumentsContract#EXTRA_LOADING |
| 644 | * @see DocumentsContract#EXTRA_INFO |
| 645 | * @see DocumentsContract#EXTRA_ERROR |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 646 | */ |
| 647 | @SuppressWarnings("unused") |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 648 | public Cursor querySearchDocuments(String rootId, String query, String[] projection) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 649 | throws FileNotFoundException { |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 650 | throw new UnsupportedOperationException("Search not supported"); |
| 651 | } |
| 652 | |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 653 | /** |
| 654 | * Ejects the root. Throws {@link IllegalStateException} if ejection failed. |
| 655 | * |
| 656 | * @param rootId the root to be ejected. |
| 657 | * @see Root#FLAG_SUPPORTS_EJECT |
| 658 | */ |
Ben Lin | e7822fb | 2016-06-24 15:21:08 -0700 | [diff] [blame] | 659 | @SuppressWarnings("unused") |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 660 | public void ejectRoot(String rootId) { |
Ben Lin | e7822fb | 2016-06-24 15:21:08 -0700 | [diff] [blame] | 661 | throw new UnsupportedOperationException("Eject not supported"); |
| 662 | } |
| 663 | |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 664 | /** {@hide} */ |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 665 | public @Nullable Bundle getDocumentMetadata(String documentId) |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 666 | throws FileNotFoundException { |
| 667 | throw new UnsupportedOperationException("Metadata not supported"); |
| 668 | } |
| 669 | |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 670 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 671 | * Return concrete MIME type of the requested document. Must match the value |
| 672 | * of {@link Document#COLUMN_MIME_TYPE} for this document. The default |
| 673 | * implementation queries {@link #queryDocument(String, String[])}, so |
| 674 | * providers may choose to override this as an optimization. |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 675 | * <p> |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 676 | * @throws AuthenticationRequiredException If authentication is required from |
| 677 | * the user (such as login credentials), but it is not guaranteed |
| 678 | * that the client will handle this properly. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 679 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 680 | public String getDocumentType(String documentId) throws FileNotFoundException { |
| 681 | final Cursor cursor = queryDocument(documentId, null); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 682 | try { |
| 683 | if (cursor.moveToFirst()) { |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 684 | return cursor.getString(cursor.getColumnIndexOrThrow(Document.COLUMN_MIME_TYPE)); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 685 | } else { |
| 686 | return null; |
| 687 | } |
| 688 | } finally { |
| 689 | IoUtils.closeQuietly(cursor); |
| 690 | } |
| 691 | } |
| 692 | |
| 693 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 694 | * Open and return the requested document. |
| 695 | * <p> |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 696 | * Your provider should return a reliable {@link ParcelFileDescriptor} to |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 697 | * detect when the remote caller has finished reading or writing the |
Garfield Tan | af03e5a | 2017-05-15 14:19:11 -0700 | [diff] [blame] | 698 | * document. |
| 699 | * <p> |
| 700 | * Mode "r" should always be supported. Provider should throw |
| 701 | * {@link UnsupportedOperationException} if the passing mode is not supported. |
| 702 | * You may return a pipe or socket pair if the mode is exclusively "r" or |
| 703 | * "w", but complex modes like "rw" imply a normal file on disk that |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 704 | * supports seeking. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 705 | * <p> |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 706 | * If you block while downloading content, you should periodically check |
| 707 | * {@link CancellationSignal#isCanceled()} to abort abandoned open requests. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 708 | * |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 709 | * @param documentId the document to return. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 710 | * @param mode the mode to open with, such as 'r', 'w', or 'rw'. |
| 711 | * @param signal used by the caller to signal if the request should be |
Jeff Sharkey | 3b94540 | 2013-11-13 13:31:09 -0800 | [diff] [blame] | 712 | * cancelled. May be null. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 713 | * @throws AuthenticationRequiredException If authentication is required from |
| 714 | * the user (such as login credentials), but it is not guaranteed |
| 715 | * that the client will handle this properly. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 716 | * @see ParcelFileDescriptor#open(java.io.File, int, android.os.Handler, |
| 717 | * OnCloseListener) |
| 718 | * @see ParcelFileDescriptor#createReliablePipe() |
| 719 | * @see ParcelFileDescriptor#createReliableSocketPair() |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 720 | * @see ParcelFileDescriptor#parseMode(String) |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 721 | */ |
| 722 | public abstract ParcelFileDescriptor openDocument( |
Steve McKay | 36f1d7e | 2017-07-20 11:41:58 -0700 | [diff] [blame] | 723 | String documentId, |
| 724 | String mode, |
| 725 | @Nullable CancellationSignal signal) throws FileNotFoundException; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 726 | |
| 727 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 728 | * Open and return a thumbnail of the requested document. |
| 729 | * <p> |
| 730 | * A provider should return a thumbnail closely matching the hinted size, |
| 731 | * attempting to serve from a local cache if possible. A provider should |
| 732 | * never return images more than double the hinted size. |
| 733 | * <p> |
Jeff Sharkey | 9352c38 | 2013-10-23 12:14:34 -0700 | [diff] [blame] | 734 | * If you perform expensive operations to download or generate a thumbnail, |
| 735 | * you should periodically check {@link CancellationSignal#isCanceled()} to |
| 736 | * abort abandoned thumbnail requests. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 737 | * |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 738 | * @param documentId the document to return. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 739 | * @param sizeHint hint of the optimal thumbnail dimensions. |
| 740 | * @param signal used by the caller to signal if the request should be |
Jeff Sharkey | 3b94540 | 2013-11-13 13:31:09 -0800 | [diff] [blame] | 741 | * cancelled. May be null. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 742 | * @throws AuthenticationRequiredException If authentication is required from |
| 743 | * the user (such as login credentials), but it is not guaranteed |
| 744 | * that the client will handle this properly. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 745 | * @see Document#FLAG_SUPPORTS_THUMBNAIL |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 746 | */ |
| 747 | @SuppressWarnings("unused") |
| 748 | public AssetFileDescriptor openDocumentThumbnail( |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 749 | String documentId, Point sizeHint, CancellationSignal signal) |
| 750 | throws FileNotFoundException { |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 751 | throw new UnsupportedOperationException("Thumbnails not supported"); |
| 752 | } |
| 753 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 754 | /** |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 755 | * Open and return the document in a format matching the specified MIME |
| 756 | * type filter. |
| 757 | * <p> |
| 758 | * A provider may perform a conversion if the documents's MIME type is not |
| 759 | * matching the specified MIME type filter. |
Tomasz Mikolajewski | 099f951 | 2016-12-09 10:19:46 +0900 | [diff] [blame] | 760 | * <p> |
| 761 | * Virtual documents must have at least one streamable format. |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 762 | * |
| 763 | * @param documentId the document to return. |
| 764 | * @param mimeTypeFilter the MIME type filter for the requested format. May |
| 765 | * be *\/*, which matches any MIME type. |
| 766 | * @param opts extra options from the client. Specific to the content |
| 767 | * provider. |
| 768 | * @param signal used by the caller to signal if the request should be |
| 769 | * cancelled. May be null. |
Ben Lin | df6d37e | 2017-03-20 18:51:20 -0700 | [diff] [blame] | 770 | * @throws AuthenticationRequiredException If authentication is required from |
| 771 | * the user (such as login credentials), but it is not guaranteed |
| 772 | * that the client will handle this properly. |
Tomasz Mikolajewski | d99964f | 2016-02-15 11:16:32 +0900 | [diff] [blame] | 773 | * @see #getDocumentStreamTypes(String, String) |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 774 | */ |
| 775 | @SuppressWarnings("unused") |
| 776 | public AssetFileDescriptor openTypedDocument( |
| 777 | String documentId, String mimeTypeFilter, Bundle opts, CancellationSignal signal) |
| 778 | throws FileNotFoundException { |
Tomasz Mikolajewski | 7539565 | 2016-01-07 07:19:22 +0000 | [diff] [blame] | 779 | throw new FileNotFoundException("The requested MIME type is not supported."); |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 780 | } |
| 781 | |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 782 | @Override |
| 783 | public final Cursor query(Uri uri, String[] projection, String selection, |
| 784 | String[] selectionArgs, String sortOrder) { |
| 785 | // As of Android-O, ContentProvider#query (w/ bundle arg) is the primary |
| 786 | // transport method. We override that, and don't ever delegate to this method. |
| 787 | throw new UnsupportedOperationException("Pre-Android-O query format not supported."); |
| 788 | } |
| 789 | |
Steve McKay | 0bb2529 | 2017-01-24 11:45:18 -0800 | [diff] [blame] | 790 | /** |
| 791 | * WARNING: Sub-classes should not override this method. This method is non-final |
| 792 | * solely for the purposes of backwards compatibility. |
| 793 | * |
| 794 | * @see #queryChildDocuments(String, String[], Bundle), |
| 795 | * {@link #queryDocument(String, String[])}, |
| 796 | * {@link #queryRecentDocuments(String, String[])}, |
| 797 | * {@link #queryRoots(String[])}, and |
| 798 | * {@link #querySearchDocuments(String, String, String[])}. |
| 799 | */ |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 800 | @Override |
Steve McKay | 0bb2529 | 2017-01-24 11:45:18 -0800 | [diff] [blame] | 801 | public Cursor query(Uri uri, String[] projection, String selection, |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 802 | String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal) { |
| 803 | // As of Android-O, ContentProvider#query (w/ bundle arg) is the primary |
| 804 | // transport method. We override that, and don't ever delegate to this metohd. |
| 805 | throw new UnsupportedOperationException("Pre-Android-O query format not supported."); |
| 806 | } |
| 807 | |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 808 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 809 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 810 | * |
| 811 | * @see #queryRoots(String[]) |
Risan | 6a4a8f6 | 2018-10-30 17:57:56 -0600 | [diff] [blame] | 812 | * @see #queryRecentDocuments(String, String[], Bundle, CancellationSignal) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 813 | * @see #queryDocument(String, String[]) |
| 814 | * @see #queryChildDocuments(String, String[], String) |
| 815 | * @see #querySearchDocuments(String, String, String[]) |
| 816 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 817 | @Override |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 818 | public final Cursor query( |
| 819 | Uri uri, String[] projection, Bundle queryArgs, CancellationSignal cancellationSignal) { |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 820 | try { |
| 821 | switch (mMatcher.match(uri)) { |
Jeff Sharkey | a61dc8e | 2013-09-05 17:14:14 -0700 | [diff] [blame] | 822 | case MATCH_ROOTS: |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 823 | return queryRoots(projection); |
| 824 | case MATCH_RECENT: |
Risan | 6a4a8f6 | 2018-10-30 17:57:56 -0600 | [diff] [blame] | 825 | return queryRecentDocuments( |
| 826 | getRootId(uri), projection, queryArgs, cancellationSignal); |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 827 | case MATCH_SEARCH: |
| 828 | return querySearchDocuments( |
| 829 | getRootId(uri), getSearchDocumentsQuery(uri), projection); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 830 | case MATCH_DOCUMENT: |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 831 | case MATCH_DOCUMENT_TREE: |
| 832 | enforceTree(uri); |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 833 | return queryDocument(getDocumentId(uri), projection); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 834 | case MATCH_CHILDREN: |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 835 | case MATCH_CHILDREN_TREE: |
| 836 | enforceTree(uri); |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 837 | if (DocumentsContract.isManageMode(uri)) { |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 838 | // TODO: Update "ForManage" variant to support query args. |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 839 | return queryChildDocumentsForManage( |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 840 | getDocumentId(uri), |
| 841 | projection, |
| 842 | getSortClause(queryArgs)); |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 843 | } else { |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 844 | return queryChildDocuments(getDocumentId(uri), projection, queryArgs); |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 845 | } |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 846 | default: |
| 847 | throw new UnsupportedOperationException("Unsupported Uri " + uri); |
| 848 | } |
| 849 | } catch (FileNotFoundException e) { |
| 850 | Log.w(TAG, "Failed during query", e); |
| 851 | return null; |
| 852 | } |
| 853 | } |
| 854 | |
Steve McKay | 29c3f68 | 2016-12-16 14:52:59 -0800 | [diff] [blame] | 855 | private static @Nullable String getSortClause(@Nullable Bundle queryArgs) { |
| 856 | queryArgs = queryArgs != null ? queryArgs : Bundle.EMPTY; |
| 857 | String sortClause = queryArgs.getString(ContentResolver.QUERY_ARG_SQL_SORT_ORDER); |
| 858 | |
| 859 | if (sortClause == null && queryArgs.containsKey(ContentResolver.QUERY_ARG_SORT_COLUMNS)) { |
| 860 | sortClause = ContentResolver.createSqlSortClause(queryArgs); |
| 861 | } |
| 862 | |
| 863 | return sortClause; |
| 864 | } |
| 865 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 866 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 867 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 868 | * |
| 869 | * @see #getDocumentType(String) |
| 870 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 871 | @Override |
| 872 | public final String getType(Uri uri) { |
| 873 | try { |
| 874 | switch (mMatcher.match(uri)) { |
Jeff Sharkey | a61dc8e | 2013-09-05 17:14:14 -0700 | [diff] [blame] | 875 | case MATCH_ROOT: |
| 876 | return DocumentsContract.Root.MIME_TYPE_ITEM; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 877 | case MATCH_DOCUMENT: |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 878 | case MATCH_DOCUMENT_TREE: |
| 879 | enforceTree(uri); |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 880 | return getDocumentType(getDocumentId(uri)); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 881 | default: |
| 882 | return null; |
| 883 | } |
| 884 | } catch (FileNotFoundException e) { |
| 885 | Log.w(TAG, "Failed during getType", e); |
| 886 | return null; |
| 887 | } |
| 888 | } |
| 889 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 890 | /** |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 891 | * Implementation is provided by the parent class. Can be overridden to |
| 892 | * provide additional functionality, but subclasses <em>must</em> always |
| 893 | * call the superclass. If the superclass returns {@code null}, the subclass |
| 894 | * may implement custom behavior. |
| 895 | * <p> |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 896 | * This is typically used to resolve a subtree URI into a concrete document |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 897 | * reference, issuing a narrower single-document URI permission grant along |
| 898 | * the way. |
| 899 | * |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 900 | * @see DocumentsContract#buildDocumentUriUsingTree(Uri, String) |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 901 | */ |
Tor Norbye | c615c6f | 2015-03-02 10:11:44 -0800 | [diff] [blame] | 902 | @CallSuper |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 903 | @Override |
| 904 | public Uri canonicalize(Uri uri) { |
| 905 | final Context context = getContext(); |
| 906 | switch (mMatcher.match(uri)) { |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 907 | case MATCH_DOCUMENT_TREE: |
| 908 | enforceTree(uri); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 909 | |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 910 | final Uri narrowUri = buildDocumentUri(uri.getAuthority(), getDocumentId(uri)); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 911 | |
| 912 | // Caller may only have prefix grant, so extend them a grant to |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 913 | // the narrow URI. |
| 914 | final int modeFlags = getCallingOrSelfUriPermissionModeFlags(context, uri); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 915 | context.grantUriPermission(getCallingPackage(), narrowUri, modeFlags); |
| 916 | return narrowUri; |
| 917 | } |
| 918 | return null; |
| 919 | } |
| 920 | |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 921 | private static int getCallingOrSelfUriPermissionModeFlags(Context context, Uri uri) { |
| 922 | // TODO: move this to a direct AMS call |
| 923 | int modeFlags = 0; |
| 924 | if (context.checkCallingOrSelfUriPermission(uri, Intent.FLAG_GRANT_READ_URI_PERMISSION) |
| 925 | == PackageManager.PERMISSION_GRANTED) { |
| 926 | modeFlags |= Intent.FLAG_GRANT_READ_URI_PERMISSION; |
| 927 | } |
| 928 | if (context.checkCallingOrSelfUriPermission(uri, Intent.FLAG_GRANT_WRITE_URI_PERMISSION) |
| 929 | == PackageManager.PERMISSION_GRANTED) { |
| 930 | modeFlags |= Intent.FLAG_GRANT_WRITE_URI_PERMISSION; |
| 931 | } |
| 932 | if (context.checkCallingOrSelfUriPermission(uri, Intent.FLAG_GRANT_READ_URI_PERMISSION |
| 933 | | Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION) |
| 934 | == PackageManager.PERMISSION_GRANTED) { |
| 935 | modeFlags |= Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION; |
| 936 | } |
| 937 | return modeFlags; |
| 938 | } |
| 939 | |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 940 | /** |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 941 | * Implementation is provided by the parent class. Throws by default, and |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 942 | * cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 943 | * |
| 944 | * @see #createDocument(String, String, String) |
| 945 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 946 | @Override |
| 947 | public final Uri insert(Uri uri, ContentValues values) { |
| 948 | throw new UnsupportedOperationException("Insert not supported"); |
| 949 | } |
| 950 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 951 | /** |
| 952 | * Implementation is provided by the parent class. Throws by default, and |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 953 | * cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 954 | * |
| 955 | * @see #deleteDocument(String) |
| 956 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 957 | @Override |
| 958 | public final int delete(Uri uri, String selection, String[] selectionArgs) { |
| 959 | throw new UnsupportedOperationException("Delete not supported"); |
| 960 | } |
| 961 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 962 | /** |
| 963 | * Implementation is provided by the parent class. Throws by default, and |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 964 | * cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 965 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 966 | @Override |
| 967 | public final int update( |
| 968 | Uri uri, ContentValues values, String selection, String[] selectionArgs) { |
| 969 | throw new UnsupportedOperationException("Update not supported"); |
| 970 | } |
| 971 | |
Jeff Sharkey | 911d7f4 | 2013-09-05 18:11:45 -0700 | [diff] [blame] | 972 | /** |
| 973 | * Implementation is provided by the parent class. Can be overridden to |
| 974 | * provide additional functionality, but subclasses <em>must</em> always |
| 975 | * call the superclass. If the superclass returns {@code null}, the subclass |
| 976 | * may implement custom behavior. |
Jeff Sharkey | 911d7f4 | 2013-09-05 18:11:45 -0700 | [diff] [blame] | 977 | */ |
Tor Norbye | c615c6f | 2015-03-02 10:11:44 -0800 | [diff] [blame] | 978 | @CallSuper |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 979 | @Override |
Jeff Sharkey | 911d7f4 | 2013-09-05 18:11:45 -0700 | [diff] [blame] | 980 | public Bundle call(String method, String arg, Bundle extras) { |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 981 | if (!method.startsWith("android:")) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 982 | // Ignore non-platform methods |
Jeff Sharkey | 911d7f4 | 2013-09-05 18:11:45 -0700 | [diff] [blame] | 983 | return super.call(method, arg, extras); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 984 | } |
| 985 | |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 986 | try { |
| 987 | return callUnchecked(method, arg, extras); |
| 988 | } catch (FileNotFoundException e) { |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 989 | throw new ParcelableException(e); |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 990 | } |
| 991 | } |
| 992 | |
| 993 | private Bundle callUnchecked(String method, String arg, Bundle extras) |
| 994 | throws FileNotFoundException { |
| 995 | |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 996 | final Context context = getContext(); |
Ben Lin | d7d1487 | 2016-06-28 17:12:52 -0700 | [diff] [blame] | 997 | final Bundle out = new Bundle(); |
| 998 | |
| 999 | if (METHOD_EJECT_ROOT.equals(method)) { |
| 1000 | // Given that certain system apps can hold MOUNT_UNMOUNT permission, but only apps |
| 1001 | // signed with platform signature can hold MANAGE_DOCUMENTS, we are going to check for |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 1002 | // MANAGE_DOCUMENTS or associated URI permission here instead |
Ben Lin | d7d1487 | 2016-06-28 17:12:52 -0700 | [diff] [blame] | 1003 | final Uri rootUri = extras.getParcelable(DocumentsContract.EXTRA_URI); |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 1004 | enforceWritePermissionInner(rootUri, getCallingPackage(), null); |
Ben Lin | d7d1487 | 2016-06-28 17:12:52 -0700 | [diff] [blame] | 1005 | |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 1006 | final String rootId = DocumentsContract.getRootId(rootUri); |
| 1007 | ejectRoot(rootId); |
Ben Lin | d7d1487 | 2016-06-28 17:12:52 -0700 | [diff] [blame] | 1008 | |
| 1009 | return out; |
| 1010 | } |
| 1011 | |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1012 | final Uri documentUri = extras.getParcelable(DocumentsContract.EXTRA_URI); |
| 1013 | final String authority = documentUri.getAuthority(); |
| 1014 | final String documentId = DocumentsContract.getDocumentId(documentUri); |
Jeff Sharkey | e37ea61 | 2013-09-04 14:30:31 -0700 | [diff] [blame] | 1015 | |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1016 | if (!mAuthority.equals(authority)) { |
| 1017 | throw new SecurityException( |
| 1018 | "Requested authority " + authority + " doesn't match provider " + mAuthority); |
| 1019 | } |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1020 | |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1021 | // If the URI is a tree URI performs some validation. |
| 1022 | enforceTree(documentUri); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1023 | |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1024 | if (METHOD_IS_CHILD_DOCUMENT.equals(method)) { |
| 1025 | enforceReadPermissionInner(documentUri, getCallingPackage(), null); |
| 1026 | |
| 1027 | final Uri childUri = extras.getParcelable(DocumentsContract.EXTRA_TARGET_URI); |
| 1028 | final String childAuthority = childUri.getAuthority(); |
| 1029 | final String childId = DocumentsContract.getDocumentId(childUri); |
| 1030 | |
| 1031 | out.putBoolean( |
| 1032 | DocumentsContract.EXTRA_RESULT, |
| 1033 | mAuthority.equals(childAuthority) |
| 1034 | && isChildDocument(documentId, childId)); |
| 1035 | |
| 1036 | } else if (METHOD_CREATE_DOCUMENT.equals(method)) { |
| 1037 | enforceWritePermissionInner(documentUri, getCallingPackage(), null); |
| 1038 | |
| 1039 | final String mimeType = extras.getString(Document.COLUMN_MIME_TYPE); |
| 1040 | final String displayName = extras.getString(Document.COLUMN_DISPLAY_NAME); |
| 1041 | final String newDocumentId = createDocument(documentId, mimeType, displayName); |
| 1042 | |
| 1043 | // No need to issue new grants here, since caller either has |
| 1044 | // manage permission or a prefix grant. We might generate a |
| 1045 | // tree style URI if that's how they called us. |
| 1046 | final Uri newDocumentUri = buildDocumentUriMaybeUsingTree(documentUri, |
| 1047 | newDocumentId); |
| 1048 | out.putParcelable(DocumentsContract.EXTRA_URI, newDocumentUri); |
| 1049 | |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1050 | } else if (METHOD_CREATE_WEB_LINK_INTENT.equals(method)) { |
| 1051 | enforceWritePermissionInner(documentUri, getCallingPackage(), null); |
| 1052 | |
| 1053 | final Bundle options = extras.getBundle(DocumentsContract.EXTRA_OPTIONS); |
| 1054 | final IntentSender intentSender = createWebLinkIntent(documentId, options); |
| 1055 | |
| 1056 | out.putParcelable(DocumentsContract.EXTRA_RESULT, intentSender); |
| 1057 | |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1058 | } else if (METHOD_RENAME_DOCUMENT.equals(method)) { |
| 1059 | enforceWritePermissionInner(documentUri, getCallingPackage(), null); |
| 1060 | |
| 1061 | final String displayName = extras.getString(Document.COLUMN_DISPLAY_NAME); |
| 1062 | final String newDocumentId = renameDocument(documentId, displayName); |
| 1063 | |
| 1064 | if (newDocumentId != null) { |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1065 | final Uri newDocumentUri = buildDocumentUriMaybeUsingTree(documentUri, |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1066 | newDocumentId); |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1067 | |
| 1068 | // If caller came in with a narrow grant, issue them a |
| 1069 | // narrow grant for the newly renamed document. |
| 1070 | if (!isTreeUri(newDocumentUri)) { |
| 1071 | final int modeFlags = getCallingOrSelfUriPermissionModeFlags(context, |
| 1072 | documentUri); |
| 1073 | context.grantUriPermission(getCallingPackage(), newDocumentUri, modeFlags); |
| 1074 | } |
| 1075 | |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1076 | out.putParcelable(DocumentsContract.EXTRA_URI, newDocumentUri); |
Jeff Sharkey | e37ea61 | 2013-09-04 14:30:31 -0700 | [diff] [blame] | 1077 | |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 1078 | // Original document no longer exists, clean up any grants. |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1079 | revokeDocumentPermission(documentId); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1080 | } |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1081 | |
| 1082 | } else if (METHOD_DELETE_DOCUMENT.equals(method)) { |
| 1083 | enforceWritePermissionInner(documentUri, getCallingPackage(), null); |
| 1084 | deleteDocument(documentId); |
| 1085 | |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 1086 | // Document no longer exists, clean up any grants. |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1087 | revokeDocumentPermission(documentId); |
| 1088 | |
| 1089 | } else if (METHOD_COPY_DOCUMENT.equals(method)) { |
| 1090 | final Uri targetUri = extras.getParcelable(DocumentsContract.EXTRA_TARGET_URI); |
| 1091 | final String targetId = DocumentsContract.getDocumentId(targetUri); |
| 1092 | |
| 1093 | enforceReadPermissionInner(documentUri, getCallingPackage(), null); |
| 1094 | enforceWritePermissionInner(targetUri, getCallingPackage(), null); |
| 1095 | |
| 1096 | final String newDocumentId = copyDocument(documentId, targetId); |
| 1097 | |
| 1098 | if (newDocumentId != null) { |
| 1099 | final Uri newDocumentUri = buildDocumentUriMaybeUsingTree(documentUri, |
| 1100 | newDocumentId); |
| 1101 | |
| 1102 | if (!isTreeUri(newDocumentUri)) { |
| 1103 | final int modeFlags = getCallingOrSelfUriPermissionModeFlags(context, |
| 1104 | documentUri); |
| 1105 | context.grantUriPermission(getCallingPackage(), newDocumentUri, modeFlags); |
| 1106 | } |
| 1107 | |
| 1108 | out.putParcelable(DocumentsContract.EXTRA_URI, newDocumentUri); |
| 1109 | } |
| 1110 | |
| 1111 | } else if (METHOD_MOVE_DOCUMENT.equals(method)) { |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 1112 | final Uri parentSourceUri = extras.getParcelable(DocumentsContract.EXTRA_PARENT_URI); |
| 1113 | final String parentSourceId = DocumentsContract.getDocumentId(parentSourceUri); |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1114 | final Uri targetUri = extras.getParcelable(DocumentsContract.EXTRA_TARGET_URI); |
| 1115 | final String targetId = DocumentsContract.getDocumentId(targetUri); |
| 1116 | |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 1117 | enforceWritePermissionInner(documentUri, getCallingPackage(), null); |
| 1118 | enforceReadPermissionInner(parentSourceUri, getCallingPackage(), null); |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1119 | enforceWritePermissionInner(targetUri, getCallingPackage(), null); |
| 1120 | |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 1121 | final String newDocumentId = moveDocument(documentId, parentSourceId, targetId); |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1122 | |
| 1123 | if (newDocumentId != null) { |
| 1124 | final Uri newDocumentUri = buildDocumentUriMaybeUsingTree(documentUri, |
| 1125 | newDocumentId); |
| 1126 | |
| 1127 | if (!isTreeUri(newDocumentUri)) { |
| 1128 | final int modeFlags = getCallingOrSelfUriPermissionModeFlags(context, |
| 1129 | documentUri); |
| 1130 | context.grantUriPermission(getCallingPackage(), newDocumentUri, modeFlags); |
| 1131 | } |
| 1132 | |
| 1133 | out.putParcelable(DocumentsContract.EXTRA_URI, newDocumentUri); |
| 1134 | } |
| 1135 | |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 1136 | } else if (METHOD_REMOVE_DOCUMENT.equals(method)) { |
| 1137 | final Uri parentSourceUri = extras.getParcelable(DocumentsContract.EXTRA_PARENT_URI); |
| 1138 | final String parentSourceId = DocumentsContract.getDocumentId(parentSourceUri); |
| 1139 | |
| 1140 | enforceReadPermissionInner(parentSourceUri, getCallingPackage(), null); |
| 1141 | enforceWritePermissionInner(documentUri, getCallingPackage(), null); |
| 1142 | removeDocument(documentId, parentSourceId); |
| 1143 | |
| 1144 | // It's responsibility of the provider to revoke any grants, as the document may be |
| 1145 | // still attached to another parents. |
Garfield Tan | 3f6b68a | 2016-11-01 14:13:38 -0700 | [diff] [blame] | 1146 | } else if (METHOD_FIND_DOCUMENT_PATH.equals(method)) { |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1147 | final boolean isTreeUri = isTreeUri(documentUri); |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1148 | |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1149 | if (isTreeUri) { |
| 1150 | enforceReadPermissionInner(documentUri, getCallingPackage(), null); |
| 1151 | } else { |
| 1152 | getContext().enforceCallingPermission(Manifest.permission.MANAGE_DOCUMENTS, null); |
| 1153 | } |
| 1154 | |
| 1155 | final String parentDocumentId = isTreeUri |
| 1156 | ? DocumentsContract.getTreeDocumentId(documentUri) |
| 1157 | : null; |
| 1158 | |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 1159 | Path path = findDocumentPath(parentDocumentId, documentId); |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1160 | |
| 1161 | // Ensure provider doesn't leak information to unprivileged callers. |
Garfield Tan | 5f21480 | 2016-10-26 14:52:46 -0700 | [diff] [blame] | 1162 | if (isTreeUri) { |
| 1163 | if (!Objects.equals(path.getPath().get(0), parentDocumentId)) { |
| 1164 | Log.wtf(TAG, "Provider doesn't return path from the tree root. Expected: " |
| 1165 | + parentDocumentId + " found: " + path.getPath().get(0)); |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 1166 | |
| 1167 | LinkedList<String> docs = new LinkedList<>(path.getPath()); |
| 1168 | while (docs.size() > 1 && !Objects.equals(docs.getFirst(), parentDocumentId)) { |
| 1169 | docs.removeFirst(); |
| 1170 | } |
| 1171 | path = new Path(null, docs); |
Garfield Tan | 5f21480 | 2016-10-26 14:52:46 -0700 | [diff] [blame] | 1172 | } |
| 1173 | |
| 1174 | if (path.getRootId() != null) { |
| 1175 | Log.wtf(TAG, "Provider returns root id :" |
| 1176 | + path.getRootId() + " unexpectedly. Erase root id."); |
| 1177 | path = new Path(null, path.getPath()); |
| 1178 | } |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1179 | } |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1180 | |
| 1181 | out.putParcelable(DocumentsContract.EXTRA_RESULT, path); |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1182 | } else if (METHOD_GET_DOCUMENT_METADATA.equals(method)) { |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 1183 | return getDocumentMetadata(documentId); |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1184 | } else { |
| 1185 | throw new UnsupportedOperationException("Method not supported " + method); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1186 | } |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 1187 | |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1188 | return out; |
| 1189 | } |
| 1190 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1191 | /** |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1192 | * Revoke any active permission grants for the given |
| 1193 | * {@link Document#COLUMN_DOCUMENT_ID}, usually called when a document |
| 1194 | * becomes invalid. Follows the same semantics as |
| 1195 | * {@link Context#revokeUriPermission(Uri, int)}. |
| 1196 | */ |
| 1197 | public final void revokeDocumentPermission(String documentId) { |
| 1198 | final Context context = getContext(); |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1199 | context.revokeUriPermission(buildDocumentUri(mAuthority, documentId), ~0); |
| 1200 | context.revokeUriPermission(buildTreeDocumentUri(mAuthority, documentId), ~0); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1201 | } |
| 1202 | |
| 1203 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 1204 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1205 | * |
| 1206 | * @see #openDocument(String, String, CancellationSignal) |
| 1207 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1208 | @Override |
| 1209 | public final ParcelFileDescriptor openFile(Uri uri, String mode) throws FileNotFoundException { |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1210 | enforceTree(uri); |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1211 | return openDocument(getDocumentId(uri), mode, null); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1212 | } |
| 1213 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1214 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 1215 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1216 | * |
| 1217 | * @see #openDocument(String, String, CancellationSignal) |
| 1218 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1219 | @Override |
| 1220 | public final ParcelFileDescriptor openFile(Uri uri, String mode, CancellationSignal signal) |
| 1221 | throws FileNotFoundException { |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1222 | enforceTree(uri); |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1223 | return openDocument(getDocumentId(uri), mode, signal); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1224 | } |
| 1225 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1226 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 1227 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1228 | * |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1229 | * @see #openDocument(String, String, CancellationSignal) |
| 1230 | */ |
| 1231 | @Override |
| 1232 | @SuppressWarnings("resource") |
| 1233 | public final AssetFileDescriptor openAssetFile(Uri uri, String mode) |
| 1234 | throws FileNotFoundException { |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1235 | enforceTree(uri); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1236 | final ParcelFileDescriptor fd = openDocument(getDocumentId(uri), mode, null); |
| 1237 | return fd != null ? new AssetFileDescriptor(fd, 0, -1) : null; |
| 1238 | } |
| 1239 | |
| 1240 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 1241 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1242 | * |
| 1243 | * @see #openDocument(String, String, CancellationSignal) |
| 1244 | */ |
| 1245 | @Override |
| 1246 | @SuppressWarnings("resource") |
| 1247 | public final AssetFileDescriptor openAssetFile(Uri uri, String mode, CancellationSignal signal) |
| 1248 | throws FileNotFoundException { |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1249 | enforceTree(uri); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1250 | final ParcelFileDescriptor fd = openDocument(getDocumentId(uri), mode, signal); |
| 1251 | return fd != null ? new AssetFileDescriptor(fd, 0, -1) : null; |
| 1252 | } |
| 1253 | |
| 1254 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 1255 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1256 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1257 | * @see #openDocumentThumbnail(String, Point, CancellationSignal) |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1258 | * @see #openTypedDocument(String, String, Bundle, CancellationSignal) |
Tomasz Mikolajewski | d99964f | 2016-02-15 11:16:32 +0900 | [diff] [blame] | 1259 | * @see #getDocumentStreamTypes(String, String) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1260 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1261 | @Override |
| 1262 | public final AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts) |
| 1263 | throws FileNotFoundException { |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1264 | return openTypedAssetFileImpl(uri, mimeTypeFilter, opts, null); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1265 | } |
| 1266 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1267 | /** |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 1268 | * Implementation is provided by the parent class. Cannot be overridden. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1269 | * |
| 1270 | * @see #openDocumentThumbnail(String, Point, CancellationSignal) |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1271 | * @see #openTypedDocument(String, String, Bundle, CancellationSignal) |
Tomasz Mikolajewski | d99964f | 2016-02-15 11:16:32 +0900 | [diff] [blame] | 1272 | * @see #getDocumentStreamTypes(String, String) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1273 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1274 | @Override |
| 1275 | public final AssetFileDescriptor openTypedAssetFile( |
| 1276 | Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal) |
| 1277 | throws FileNotFoundException { |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1278 | return openTypedAssetFileImpl(uri, mimeTypeFilter, opts, signal); |
| 1279 | } |
| 1280 | |
| 1281 | /** |
Tomasz Mikolajewski | d99964f | 2016-02-15 11:16:32 +0900 | [diff] [blame] | 1282 | * Return a list of streamable MIME types matching the filter, which can be passed to |
| 1283 | * {@link #openTypedDocument(String, String, Bundle, CancellationSignal)}. |
| 1284 | * |
| 1285 | * <p>The default implementation returns a MIME type provided by |
| 1286 | * {@link #queryDocument(String, String[])} as long as it matches the filter and the document |
| 1287 | * does not have the {@link Document#FLAG_VIRTUAL_DOCUMENT} flag set. |
| 1288 | * |
Tomasz Mikolajewski | 099f951 | 2016-12-09 10:19:46 +0900 | [diff] [blame] | 1289 | * <p>Virtual documents must have at least one streamable format. |
| 1290 | * |
Tomasz Mikolajewski | d99964f | 2016-02-15 11:16:32 +0900 | [diff] [blame] | 1291 | * @see #getStreamTypes(Uri, String) |
| 1292 | * @see #openTypedDocument(String, String, Bundle, CancellationSignal) |
| 1293 | */ |
| 1294 | public String[] getDocumentStreamTypes(String documentId, String mimeTypeFilter) { |
| 1295 | Cursor cursor = null; |
| 1296 | try { |
| 1297 | cursor = queryDocument(documentId, null); |
| 1298 | if (cursor.moveToFirst()) { |
| 1299 | final String mimeType = |
| 1300 | cursor.getString(cursor.getColumnIndexOrThrow(Document.COLUMN_MIME_TYPE)); |
| 1301 | final long flags = |
| 1302 | cursor.getLong(cursor.getColumnIndexOrThrow(Document.COLUMN_FLAGS)); |
| 1303 | if ((flags & Document.FLAG_VIRTUAL_DOCUMENT) == 0 && mimeType != null && |
| 1304 | mimeTypeMatches(mimeTypeFilter, mimeType)) { |
| 1305 | return new String[] { mimeType }; |
| 1306 | } |
| 1307 | } |
| 1308 | } catch (FileNotFoundException e) { |
| 1309 | return null; |
| 1310 | } finally { |
| 1311 | IoUtils.closeQuietly(cursor); |
| 1312 | } |
| 1313 | |
| 1314 | // No streamable MIME types. |
| 1315 | return null; |
| 1316 | } |
| 1317 | |
| 1318 | /** |
| 1319 | * Called by a client to determine the types of data streams that this content provider |
| 1320 | * support for the given URI. |
| 1321 | * |
| 1322 | * <p>Overriding this method is deprecated. Override {@link #openTypedDocument} instead. |
| 1323 | * |
| 1324 | * @see #getDocumentStreamTypes(String, String) |
| 1325 | */ |
| 1326 | @Override |
| 1327 | public String[] getStreamTypes(Uri uri, String mimeTypeFilter) { |
| 1328 | enforceTree(uri); |
| 1329 | return getDocumentStreamTypes(getDocumentId(uri), mimeTypeFilter); |
| 1330 | } |
| 1331 | |
| 1332 | /** |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1333 | * @hide |
| 1334 | */ |
| 1335 | private final AssetFileDescriptor openTypedAssetFileImpl( |
| 1336 | Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal) |
| 1337 | throws FileNotFoundException { |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1338 | enforceTree(uri); |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1339 | final String documentId = getDocumentId(uri); |
Jeff Sharkey | 5b836f2 | 2014-08-27 14:46:32 -0700 | [diff] [blame] | 1340 | if (opts != null && opts.containsKey(ContentResolver.EXTRA_SIZE)) { |
| 1341 | final Point sizeHint = opts.getParcelable(ContentResolver.EXTRA_SIZE); |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1342 | return openDocumentThumbnail(documentId, sizeHint, signal); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1343 | } |
Tomasz Mikolajewski | b344b89 | 2015-10-28 17:50:40 +0900 | [diff] [blame] | 1344 | if ("*/*".equals(mimeTypeFilter)) { |
| 1345 | // If they can take anything, the untyped open call is good enough. |
| 1346 | return openAssetFile(uri, "r"); |
| 1347 | } |
| 1348 | final String baseType = getType(uri); |
| 1349 | if (baseType != null && ClipDescription.compareMimeTypes(baseType, mimeTypeFilter)) { |
| 1350 | // Use old untyped open call if this provider has a type for this |
| 1351 | // URI and it matches the request. |
| 1352 | return openAssetFile(uri, "r"); |
| 1353 | } |
| 1354 | // For any other yet unhandled case, let the provider subclass handle it. |
| 1355 | return openTypedDocument(documentId, mimeTypeFilter, opts, signal); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1356 | } |
Tomasz Mikolajewski | d99964f | 2016-02-15 11:16:32 +0900 | [diff] [blame] | 1357 | |
| 1358 | /** |
| 1359 | * @hide |
| 1360 | */ |
| 1361 | public static boolean mimeTypeMatches(String filter, String test) { |
| 1362 | if (test == null) { |
| 1363 | return false; |
| 1364 | } else if (filter == null || "*/*".equals(filter)) { |
| 1365 | return true; |
| 1366 | } else if (filter.equals(test)) { |
| 1367 | return true; |
| 1368 | } else if (filter.endsWith("/*")) { |
| 1369 | return filter.regionMatches(0, test, 0, filter.indexOf('/')); |
| 1370 | } else { |
| 1371 | return false; |
| 1372 | } |
| 1373 | } |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1374 | } |