Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -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 | |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 19 | import static com.android.internal.util.Preconditions.checkCollectionElementsNotNull; |
| 20 | import static com.android.internal.util.Preconditions.checkCollectionNotEmpty; |
| 21 | |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 22 | import android.annotation.NonNull; |
Steve McKay | 323ee3e | 2015-09-25 16:02:56 -0700 | [diff] [blame] | 23 | import android.annotation.Nullable; |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 24 | import android.annotation.SystemApi; |
Mathew Inwood | 6750f2e | 2018-08-10 09:29:25 +0100 | [diff] [blame] | 25 | import android.annotation.UnsupportedAppUsage; |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 26 | import android.content.ContentInterface; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 27 | import android.content.ContentResolver; |
Jeff Sharkey | ee2f7df | 2013-09-26 11:32:30 -0700 | [diff] [blame] | 28 | import android.content.Context; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 29 | import android.content.Intent; |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 30 | import android.content.IntentSender; |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 31 | import android.content.MimeTypeFilter; |
Jeff Sharkey | d2e1e81 | 2013-10-09 13:31:13 -0700 | [diff] [blame] | 32 | import android.content.pm.ResolveInfo; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 33 | import android.content.res.AssetFileDescriptor; |
Jeff Sharkey | 20d96d8 | 2013-07-30 17:08:39 -0700 | [diff] [blame] | 34 | import android.database.Cursor; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 35 | import android.graphics.Bitmap; |
Jeff Sharkey | 4e5efa3 | 2018-10-04 19:21:53 -0600 | [diff] [blame] | 36 | import android.graphics.ImageDecoder; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 37 | import android.graphics.Point; |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 38 | import android.media.ExifInterface; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 39 | import android.net.Uri; |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 40 | import android.os.Build; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 41 | import android.os.Bundle; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 42 | import android.os.CancellationSignal; |
Jeff Sharkey | 3381931 | 2013-10-29 11:56:37 -0700 | [diff] [blame] | 43 | import android.os.OperationCanceledException; |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 44 | import android.os.Parcel; |
Jeff Sharkey | bd3b902 | 2013-08-20 15:20:04 -0700 | [diff] [blame] | 45 | import android.os.ParcelFileDescriptor; |
Jeff Sharkey | 67f9d50 | 2017-08-05 13:49:13 -0600 | [diff] [blame] | 46 | import android.os.ParcelFileDescriptor.OnCloseListener; |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 47 | import android.os.Parcelable; |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 48 | import android.os.ParcelableException; |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 49 | import android.os.RemoteException; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 50 | import android.util.Log; |
| 51 | |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 52 | import com.android.internal.util.Preconditions; |
| 53 | |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 54 | import dalvik.system.VMRuntime; |
| 55 | |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 56 | import java.io.File; |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 57 | import java.io.FileNotFoundException; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 58 | import java.io.IOException; |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 59 | import java.util.ArrayList; |
Jeff Sharkey | dc2963a | 2013-08-02 15:55:26 -0700 | [diff] [blame] | 60 | import java.util.List; |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 61 | import java.util.Objects; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 62 | |
| 63 | /** |
Jeff Sharkey | bd3b902 | 2013-08-20 15:20:04 -0700 | [diff] [blame] | 64 | * Defines the contract between a documents provider and the platform. |
| 65 | * <p> |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 66 | * To create a document provider, extend {@link DocumentsProvider}, which |
| 67 | * provides a foundational implementation of this contract. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 68 | * <p> |
| 69 | * All client apps must hold a valid URI permission grant to access documents, |
| 70 | * typically issued when a user makes a selection through |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 71 | * {@link Intent#ACTION_OPEN_DOCUMENT}, {@link Intent#ACTION_CREATE_DOCUMENT}, |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 72 | * or {@link Intent#ACTION_OPEN_DOCUMENT_TREE}. |
Jeff Sharkey | bd3b902 | 2013-08-20 15:20:04 -0700 | [diff] [blame] | 73 | * |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 74 | * @see DocumentsProvider |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 75 | */ |
| 76 | public final class DocumentsContract { |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 77 | private static final String TAG = "DocumentsContract"; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 78 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 79 | // content://com.example/root/ |
| 80 | // content://com.example/root/sdcard/ |
| 81 | // content://com.example/root/sdcard/recent/ |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 82 | // content://com.example/root/sdcard/search/?query=pony |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 83 | // content://com.example/document/12/ |
| 84 | // content://com.example/document/12/children/ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 85 | // content://com.example/tree/12/document/24/ |
| 86 | // content://com.example/tree/12/document/24/children/ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 87 | |
| 88 | private DocumentsContract() { |
| 89 | } |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 90 | |
Jeff Sharkey | 85f5f81 | 2013-10-07 10:16:12 -0700 | [diff] [blame] | 91 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 92 | * Intent action used to identify {@link DocumentsProvider} instances. This |
| 93 | * is used in the {@code <intent-filter>} of a {@code <provider>}. |
Jeff Sharkey | 85f5f81 | 2013-10-07 10:16:12 -0700 | [diff] [blame] | 94 | */ |
| 95 | public static final String PROVIDER_INTERFACE = "android.content.action.DOCUMENTS_PROVIDER"; |
| 96 | |
Jeff Sharkey | 5b83f85 | 2013-08-14 18:29:19 -0700 | [diff] [blame] | 97 | /** {@hide} */ |
Jeff Sharkey | 5aae0c9 | 2018-07-09 16:38:20 -0600 | [diff] [blame] | 98 | @Deprecated |
| 99 | public static final String EXTRA_PACKAGE_NAME = Intent.EXTRA_PACKAGE_NAME; |
Jeff Sharkey | 15be836 | 2013-10-09 13:52:17 -0700 | [diff] [blame] | 100 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 101 | /** |
| 102 | * The value is decide whether to show advance mode or not. |
| 103 | * If the value is true, the local/device storage root must be |
| 104 | * visible in DocumentsUI. |
| 105 | * |
| 106 | * {@hide} |
| 107 | */ |
| 108 | @SystemApi |
| 109 | public static final String EXTRA_SHOW_ADVANCED = "android.provider.extra.SHOW_ADVANCED"; |
Aga Wronska | 1719b35 | 2016-03-21 11:28:03 -0700 | [diff] [blame] | 110 | |
| 111 | /** {@hide} */ |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 112 | public static final String EXTRA_TARGET_URI = "android.content.extra.TARGET_URI"; |
| 113 | |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 114 | /** |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 115 | * Key for {@link DocumentsProvider} to query display name is matched. |
| 116 | * The match of display name is partial matching and case-insensitive. |
| 117 | * Ex: The value is "o", the display name of the results will contain |
| 118 | * both "foo" and "Open". |
| 119 | * |
| 120 | * @see DocumentsProvider#querySearchDocuments(String, String[], |
| 121 | * Bundle) |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 122 | */ |
| 123 | public static final String QUERY_ARG_DISPLAY_NAME = "android:query-arg-display-name"; |
| 124 | |
| 125 | /** |
| 126 | * Key for {@link DocumentsProvider} to query mime types is matched. |
| 127 | * The value is a string array, it can support different mime types. |
| 128 | * Each items will be treated as "OR" condition. Ex: {"image/*" , |
| 129 | * "video/*"}. The mime types of the results will contain both image |
| 130 | * type and video type. |
| 131 | * |
| 132 | * @see DocumentsProvider#querySearchDocuments(String, String[], |
| 133 | * Bundle) |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 134 | */ |
| 135 | public static final String QUERY_ARG_MIME_TYPES = "android:query-arg-mime-types"; |
| 136 | |
| 137 | /** |
| 138 | * Key for {@link DocumentsProvider} to query the file size in bytes is |
| 139 | * larger than the value. |
| 140 | * |
| 141 | * @see DocumentsProvider#querySearchDocuments(String, String[], |
| 142 | * Bundle) |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 143 | */ |
| 144 | public static final String QUERY_ARG_FILE_SIZE_OVER = "android:query-arg-file-size-over"; |
| 145 | |
| 146 | /** |
| 147 | * Key for {@link DocumentsProvider} to query the last modified time |
| 148 | * is newer than the value. The unit is in milliseconds since |
| 149 | * January 1, 1970 00:00:00.0 UTC. |
| 150 | * |
| 151 | * @see DocumentsProvider#querySearchDocuments(String, String[], |
| 152 | * Bundle) |
| 153 | * @see Document#COLUMN_LAST_MODIFIED |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 154 | */ |
| 155 | public static final String QUERY_ARG_LAST_MODIFIED_AFTER = |
| 156 | "android:query-arg-last-modified-after"; |
| 157 | |
| 158 | /** |
Ivan Chiang | 1edfcb2 | 2018-11-14 13:20:22 +0800 | [diff] [blame] | 159 | * Key for {@link DocumentsProvider} to decide whether the files that |
| 160 | * have been added to MediaStore should be excluded. If the value is |
| 161 | * true, exclude them. Otherwise, include them. |
| 162 | * |
| 163 | * @see DocumentsProvider#querySearchDocuments(String, String[], |
| 164 | * Bundle) |
Ivan Chiang | 1edfcb2 | 2018-11-14 13:20:22 +0800 | [diff] [blame] | 165 | */ |
| 166 | public static final String QUERY_ARG_EXCLUDE_MEDIA = "android:query-arg-exclude-media"; |
| 167 | |
| 168 | /** |
Garfield Tan | b44ae61 | 2016-11-07 16:46:37 -0800 | [diff] [blame] | 169 | * Sets the desired initial location visible to user when file chooser is shown. |
| 170 | * |
| 171 | * <p>Applicable to {@link Intent} with actions: |
| 172 | * <ul> |
| 173 | * <li>{@link Intent#ACTION_OPEN_DOCUMENT}</li> |
| 174 | * <li>{@link Intent#ACTION_CREATE_DOCUMENT}</li> |
| 175 | * <li>{@link Intent#ACTION_OPEN_DOCUMENT_TREE}</li> |
| 176 | * </ul> |
| 177 | * |
| 178 | * <p>Location should specify a document URI or a tree URI with document ID. If |
| 179 | * this URI identifies a non-directory, document navigator will attempt to use the parent |
| 180 | * of the document as the initial location. |
Garfield Tan | 40d7b35 | 2017-03-02 15:30:30 -0800 | [diff] [blame] | 181 | * |
| 182 | * <p>The initial location is system specific if this extra is missing or document navigator |
| 183 | * failed to locate the desired initial location. |
Garfield Tan | b44ae61 | 2016-11-07 16:46:37 -0800 | [diff] [blame] | 184 | */ |
| 185 | public static final String EXTRA_INITIAL_URI = "android.provider.extra.INITIAL_URI"; |
| 186 | |
| 187 | /** |
Ben Kwa | 7779740 | 2015-05-29 15:40:31 -0700 | [diff] [blame] | 188 | * Set this in a DocumentsUI intent to cause a package's own roots to be |
| 189 | * excluded from the roots list. |
| 190 | */ |
| 191 | public static final String EXTRA_EXCLUDE_SELF = "android.provider.extra.EXCLUDE_SELF"; |
| 192 | |
| 193 | /** |
Jeff Sharkey | 4e5efa3 | 2018-10-04 19:21:53 -0600 | [diff] [blame] | 194 | * An extra number of degrees that an image should be rotated during the |
| 195 | * decode process to be presented correctly. |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 196 | * |
Jeff Sharkey | 4e5efa3 | 2018-10-04 19:21:53 -0600 | [diff] [blame] | 197 | * @see AssetFileDescriptor#getExtras() |
| 198 | * @see android.provider.MediaStore.Images.ImageColumns#ORIENTATION |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 199 | */ |
Tomasz Mikolajewski | 5f53f65 | 2016-03-31 09:34:51 +0900 | [diff] [blame] | 200 | public static final String EXTRA_ORIENTATION = "android.provider.extra.ORIENTATION"; |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 201 | |
Tomasz Mikolajewski | 0e591f9 | 2015-06-12 16:22:17 -0700 | [diff] [blame] | 202 | /** |
| 203 | * Overrides the default prompt text in DocumentsUI when set in an intent. |
| 204 | */ |
| 205 | public static final String EXTRA_PROMPT = "android.provider.extra.PROMPT"; |
| 206 | |
Ben Lin | bd036d8 | 2016-12-15 15:41:08 -0800 | [diff] [blame] | 207 | /** |
| 208 | * Action of intent issued by DocumentsUI when user wishes to open/configure/manage a particular |
| 209 | * document in the provider application. |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 210 | * |
Ben Lin | bd036d8 | 2016-12-15 15:41:08 -0800 | [diff] [blame] | 211 | * <p>When issued, the intent will include the URI of the document as the intent data. |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 212 | * |
Ben Lin | bd036d8 | 2016-12-15 15:41:08 -0800 | [diff] [blame] | 213 | * <p>A provider wishing to provide support for this action should do two things. |
| 214 | * <li>Add an {@code <intent-filter>} matching this action. |
| 215 | * <li>When supplying information in {@link DocumentsProvider#queryChildDocuments}, include |
| 216 | * {@link Document#FLAG_SUPPORTS_SETTINGS} in the flags for each document that supports |
| 217 | * settings. |
Ben Lin | bd036d8 | 2016-12-15 15:41:08 -0800 | [diff] [blame] | 218 | */ |
| 219 | public static final String |
| 220 | ACTION_DOCUMENT_SETTINGS = "android.provider.action.DOCUMENT_SETTINGS"; |
| 221 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 222 | /** |
| 223 | * The action to manage document in Downloads root in DocumentsUI. |
| 224 | * {@hide} |
| 225 | */ |
| 226 | @SystemApi |
Jeff Sharkey | a61dc8e | 2013-09-05 17:14:14 -0700 | [diff] [blame] | 227 | public static final String ACTION_MANAGE_DOCUMENT = "android.provider.action.MANAGE_DOCUMENT"; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 228 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 229 | /** |
| 230 | * The action to launch the settings of this root. |
| 231 | * {@hide} |
| 232 | */ |
| 233 | @SystemApi |
Jeff Sharkey | 1407d4c | 2015-04-12 21:52:24 -0700 | [diff] [blame] | 234 | public static final String |
| 235 | ACTION_DOCUMENT_ROOT_SETTINGS = "android.provider.action.DOCUMENT_ROOT_SETTINGS"; |
Jeff Sharkey | 59d577a | 2015-04-11 21:27:21 -0700 | [diff] [blame] | 236 | |
Jeff Sharkey | cc2ae6b4 | 2015-09-29 13:04:46 -0700 | [diff] [blame] | 237 | /** {@hide} */ |
Garfield Tan | 92b96ba | 2016-11-01 14:33:48 -0700 | [diff] [blame] | 238 | public static final String EXTERNAL_STORAGE_PROVIDER_AUTHORITY = |
| 239 | "com.android.externalstorage.documents"; |
| 240 | |
| 241 | /** {@hide} */ |
Amin Shaikh | 305e87e | 2018-11-19 12:33:27 -0500 | [diff] [blame] | 242 | public static final String EXTERNAL_STORAGE_PRIMARY_EMULATED_ROOT_ID = "primary"; |
| 243 | |
| 244 | /** {@hide} */ |
Jeff Sharkey | cc2ae6b4 | 2015-09-29 13:04:46 -0700 | [diff] [blame] | 245 | public static final String PACKAGE_DOCUMENTS_UI = "com.android.documentsui"; |
| 246 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 247 | /** |
| 248 | * Get string array identifies the type or types of metadata returned |
| 249 | * using DocumentsContract#getDocumentMetadata. |
| 250 | * |
Jeff Sharkey | b95bd44 | 2018-12-11 10:35:02 -0700 | [diff] [blame] | 251 | * @see #getDocumentMetadata(ContentInterface, Uri) |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 252 | */ |
| 253 | public static final String METADATA_TYPES = "android:documentMetadataTypes"; |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 254 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 255 | /** |
| 256 | * Get Exif information using DocumentsContract#getDocumentMetadata. |
| 257 | * |
Jeff Sharkey | b95bd44 | 2018-12-11 10:35:02 -0700 | [diff] [blame] | 258 | * @see #getDocumentMetadata(ContentInterface, Uri) |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 259 | */ |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 260 | public static final String METADATA_EXIF = "android:documentExif"; |
| 261 | |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 262 | /** |
Jeff Sharkey | b95bd44 | 2018-12-11 10:35:02 -0700 | [diff] [blame] | 263 | * Get total count of all documents currently stored under the given |
| 264 | * directory tree. Only valid for {@link Document#MIME_TYPE_DIR} documents. |
| 265 | * |
| 266 | * @see #getDocumentMetadata(ContentInterface, Uri) |
| 267 | */ |
| 268 | public static final String METADATA_TREE_COUNT = "android:metadataTreeCount"; |
| 269 | |
| 270 | /** |
| 271 | * Get total size of all documents currently stored under the given |
| 272 | * directory tree. Only valid for {@link Document#MIME_TYPE_DIR} documents. |
| 273 | * |
| 274 | * @see #getDocumentMetadata(ContentInterface, Uri) |
| 275 | */ |
| 276 | public static final String METADATA_TREE_SIZE = "android:metadataTreeSize"; |
| 277 | |
| 278 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 279 | * Constants related to a document, including {@link Cursor} column names |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 280 | * and flags. |
| 281 | * <p> |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 282 | * A document can be either an openable stream (with a specific MIME type), |
| 283 | * or a directory containing additional documents (with the |
| 284 | * {@link #MIME_TYPE_DIR} MIME type). A directory represents the top of a |
| 285 | * subtree containing zero or more documents, which can recursively contain |
| 286 | * even more documents and directories. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 287 | * <p> |
| 288 | * All columns are <em>read-only</em> to client applications. |
Jeff Sharkey | bd3b902 | 2013-08-20 15:20:04 -0700 | [diff] [blame] | 289 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 290 | public final static class Document { |
| 291 | private Document() { |
Jeff Sharkey | a5599ef | 2013-08-15 16:17:41 -0700 | [diff] [blame] | 292 | } |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 293 | |
Jeff Sharkey | a5599ef | 2013-08-15 16:17:41 -0700 | [diff] [blame] | 294 | /** |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 295 | * Unique ID of a document. This ID is both provided by and interpreted |
| 296 | * by a {@link DocumentsProvider}, and should be treated as an opaque |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 297 | * value by client applications. This column is required. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 298 | * <p> |
| 299 | * Each document must have a unique ID within a provider, but that |
| 300 | * single document may be included as a child of multiple directories. |
| 301 | * <p> |
| 302 | * A provider must always return durable IDs, since they will be used to |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 303 | * issue long-term URI permission grants when an application interacts |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 304 | * with {@link Intent#ACTION_OPEN_DOCUMENT} and |
| 305 | * {@link Intent#ACTION_CREATE_DOCUMENT}. |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 306 | * <p> |
| 307 | * Type: STRING |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 308 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 309 | public static final String COLUMN_DOCUMENT_ID = "document_id"; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 310 | |
| 311 | /** |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 312 | * Concrete MIME type of a document. For example, "image/png" or |
| 313 | * "application/pdf" for openable files. A document can also be a |
| 314 | * directory containing additional documents, which is represented with |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 315 | * the {@link #MIME_TYPE_DIR} MIME type. This column is required. |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 316 | * <p> |
| 317 | * Type: STRING |
| 318 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 319 | * @see #MIME_TYPE_DIR |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 320 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 321 | public static final String COLUMN_MIME_TYPE = "mime_type"; |
| 322 | |
| 323 | /** |
| 324 | * Display name of a document, used as the primary title displayed to a |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 325 | * user. This column is required. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 326 | * <p> |
| 327 | * Type: STRING |
| 328 | */ |
| 329 | public static final String COLUMN_DISPLAY_NAME = OpenableColumns.DISPLAY_NAME; |
| 330 | |
| 331 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 332 | * Summary of a document, which may be shown to a user. This column is |
| 333 | * optional, and may be {@code null}. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 334 | * <p> |
| 335 | * Type: STRING |
| 336 | */ |
| 337 | public static final String COLUMN_SUMMARY = "summary"; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 338 | |
| 339 | /** |
| 340 | * Timestamp when a document was last modified, in milliseconds since |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 341 | * January 1, 1970 00:00:00.0 UTC. This column is required, and may be |
| 342 | * {@code null} if unknown. A {@link DocumentsProvider} can update this |
| 343 | * field using events from {@link OnCloseListener} or other reliable |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 344 | * {@link ParcelFileDescriptor} transports. |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 345 | * <p> |
| 346 | * Type: INTEGER (long) |
| 347 | * |
| 348 | * @see System#currentTimeMillis() |
| 349 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 350 | public static final String COLUMN_LAST_MODIFIED = "last_modified"; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 351 | |
| 352 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 353 | * Specific icon resource ID for a document. This column is optional, |
| 354 | * and may be {@code null} to use a platform-provided default icon based |
| 355 | * on {@link #COLUMN_MIME_TYPE}. |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 356 | * <p> |
| 357 | * Type: INTEGER (int) |
| 358 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 359 | public static final String COLUMN_ICON = "icon"; |
Jeff Sharkey | 6651669 | 2013-08-06 11:26:10 -0700 | [diff] [blame] | 360 | |
| 361 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 362 | * Flags that apply to a document. This column is required. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 363 | * <p> |
| 364 | * Type: INTEGER (int) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 365 | * |
| 366 | * @see #FLAG_SUPPORTS_WRITE |
| 367 | * @see #FLAG_SUPPORTS_DELETE |
| 368 | * @see #FLAG_SUPPORTS_THUMBNAIL |
| 369 | * @see #FLAG_DIR_PREFERS_GRID |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 370 | * @see #FLAG_DIR_PREFERS_LAST_MODIFIED |
Tomasz Mikolajewski | a8057a9 | 2015-11-16 11:41:28 +0900 | [diff] [blame] | 371 | * @see #FLAG_VIRTUAL_DOCUMENT |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 372 | * @see #FLAG_SUPPORTS_COPY |
| 373 | * @see #FLAG_SUPPORTS_MOVE |
| 374 | * @see #FLAG_SUPPORTS_REMOVE |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 375 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 376 | public static final String COLUMN_FLAGS = "flags"; |
| 377 | |
| 378 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 379 | * Size of a document, in bytes, or {@code null} if unknown. This column |
| 380 | * is required. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 381 | * <p> |
| 382 | * Type: INTEGER (long) |
| 383 | */ |
| 384 | public static final String COLUMN_SIZE = OpenableColumns.SIZE; |
| 385 | |
| 386 | /** |
| 387 | * MIME type of a document which is a directory that may contain |
| 388 | * additional documents. |
| 389 | * |
| 390 | * @see #COLUMN_MIME_TYPE |
| 391 | */ |
| 392 | public static final String MIME_TYPE_DIR = "vnd.android.document/directory"; |
| 393 | |
| 394 | /** |
| 395 | * Flag indicating that a document can be represented as a thumbnail. |
| 396 | * |
| 397 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 398 | * @see DocumentsContract#getDocumentThumbnail(ContentInterface, Uri, |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 399 | * Point, CancellationSignal) |
| 400 | * @see DocumentsProvider#openDocumentThumbnail(String, Point, |
| 401 | * android.os.CancellationSignal) |
| 402 | */ |
| 403 | public static final int FLAG_SUPPORTS_THUMBNAIL = 1; |
| 404 | |
| 405 | /** |
| 406 | * Flag indicating that a document supports writing. |
| 407 | * <p> |
| 408 | * When a document is opened with {@link Intent#ACTION_OPEN_DOCUMENT}, |
| 409 | * the calling application is granted both |
| 410 | * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION} and |
| 411 | * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION}. However, the actual |
| 412 | * writability of a document may change over time, for example due to |
| 413 | * remote access changes. This flag indicates that a document client can |
| 414 | * expect {@link ContentResolver#openOutputStream(Uri)} to succeed. |
Steve McKay | 83df8c0 | 2015-09-16 15:07:31 -0700 | [diff] [blame] | 415 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 416 | * @see #COLUMN_FLAGS |
| 417 | */ |
| 418 | public static final int FLAG_SUPPORTS_WRITE = 1 << 1; |
| 419 | |
| 420 | /** |
| 421 | * Flag indicating that a document is deletable. |
| 422 | * |
| 423 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 424 | * @see DocumentsContract#deleteDocument(ContentInterface, Uri) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 425 | * @see DocumentsProvider#deleteDocument(String) |
| 426 | */ |
| 427 | public static final int FLAG_SUPPORTS_DELETE = 1 << 2; |
| 428 | |
| 429 | /** |
| 430 | * Flag indicating that a document is a directory that supports creation |
| 431 | * of new files within it. Only valid when {@link #COLUMN_MIME_TYPE} is |
| 432 | * {@link #MIME_TYPE_DIR}. |
| 433 | * |
| 434 | * @see #COLUMN_FLAGS |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 435 | * @see DocumentsProvider#createDocument(String, String, String) |
| 436 | */ |
| 437 | public static final int FLAG_DIR_SUPPORTS_CREATE = 1 << 3; |
| 438 | |
| 439 | /** |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 440 | * Flag indicating that a directory prefers its contents be shown in a |
| 441 | * larger format grid. Usually suitable when a directory contains mostly |
| 442 | * pictures. Only valid when {@link #COLUMN_MIME_TYPE} is |
| 443 | * {@link #MIME_TYPE_DIR}. |
| 444 | * |
| 445 | * @see #COLUMN_FLAGS |
| 446 | */ |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 447 | public static final int FLAG_DIR_PREFERS_GRID = 1 << 4; |
Jeff Sharkey | d182bb6 | 2013-09-07 14:45:03 -0700 | [diff] [blame] | 448 | |
| 449 | /** |
| 450 | * Flag indicating that a directory prefers its contents be sorted by |
| 451 | * {@link #COLUMN_LAST_MODIFIED}. Only valid when |
| 452 | * {@link #COLUMN_MIME_TYPE} is {@link #MIME_TYPE_DIR}. |
| 453 | * |
| 454 | * @see #COLUMN_FLAGS |
| 455 | */ |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 456 | public static final int FLAG_DIR_PREFERS_LAST_MODIFIED = 1 << 5; |
Jeff Sharkey | f6db154 | 2013-09-13 13:42:19 -0700 | [diff] [blame] | 457 | |
| 458 | /** |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 459 | * Flag indicating that a document can be renamed. |
| 460 | * |
| 461 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 462 | * @see DocumentsContract#renameDocument(ContentInterface, Uri, String) |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 463 | * @see DocumentsProvider#renameDocument(String, String) |
| 464 | */ |
| 465 | public static final int FLAG_SUPPORTS_RENAME = 1 << 6; |
| 466 | |
| 467 | /** |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 468 | * Flag indicating that a document can be copied to another location |
| 469 | * within the same document provider. |
| 470 | * |
| 471 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 472 | * @see DocumentsContract#copyDocument(ContentInterface, Uri, Uri) |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 473 | * @see DocumentsProvider#copyDocument(String, String) |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 474 | */ |
| 475 | public static final int FLAG_SUPPORTS_COPY = 1 << 7; |
| 476 | |
| 477 | /** |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 478 | * Flag indicating that a document can be moved to another location |
| 479 | * within the same document provider. |
| 480 | * |
| 481 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 482 | * @see DocumentsContract#moveDocument(ContentInterface, Uri, Uri, Uri) |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 483 | * @see DocumentsProvider#moveDocument(String, String, String) |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 484 | */ |
| 485 | public static final int FLAG_SUPPORTS_MOVE = 1 << 8; |
| 486 | |
| 487 | /** |
Tomasz Mikolajewski | a8057a9 | 2015-11-16 11:41:28 +0900 | [diff] [blame] | 488 | * Flag indicating that a document is virtual, and doesn't have byte |
| 489 | * representation in the MIME type specified as {@link #COLUMN_MIME_TYPE}. |
| 490 | * |
Tomasz Mikolajewski | 099f951 | 2016-12-09 10:19:46 +0900 | [diff] [blame] | 491 | * <p><em>Virtual documents must have at least one alternative streamable |
| 492 | * format via {@link DocumentsProvider#openTypedDocument}</em> |
| 493 | * |
Tomasz Mikolajewski | a8057a9 | 2015-11-16 11:41:28 +0900 | [diff] [blame] | 494 | * @see #COLUMN_FLAGS |
| 495 | * @see #COLUMN_MIME_TYPE |
| 496 | * @see DocumentsProvider#openTypedDocument(String, String, Bundle, |
| 497 | * android.os.CancellationSignal) |
Tomasz Mikolajewski | d99964f | 2016-02-15 11:16:32 +0900 | [diff] [blame] | 498 | * @see DocumentsProvider#getDocumentStreamTypes(String, String) |
Tomasz Mikolajewski | a8057a9 | 2015-11-16 11:41:28 +0900 | [diff] [blame] | 499 | */ |
Tomasz Mikolajewski | 7539565 | 2016-01-07 07:19:22 +0000 | [diff] [blame] | 500 | public static final int FLAG_VIRTUAL_DOCUMENT = 1 << 9; |
Tomasz Mikolajewski | a8057a9 | 2015-11-16 11:41:28 +0900 | [diff] [blame] | 501 | |
| 502 | /** |
Tomasz Mikolajewski | 9b055e1 | 2016-02-01 13:01:34 +0900 | [diff] [blame] | 503 | * Flag indicating that a document can be removed from a parent. |
| 504 | * |
| 505 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 506 | * @see DocumentsContract#removeDocument(ContentInterface, Uri, Uri) |
Tomasz Mikolajewski | 9b055e1 | 2016-02-01 13:01:34 +0900 | [diff] [blame] | 507 | * @see DocumentsProvider#removeDocument(String, String) |
| 508 | */ |
| 509 | public static final int FLAG_SUPPORTS_REMOVE = 1 << 10; |
| 510 | |
| 511 | /** |
Ben Lin | bd036d8 | 2016-12-15 15:41:08 -0800 | [diff] [blame] | 512 | * Flag indicating that a document has settings that can be configured by user. |
| 513 | * |
| 514 | * @see #COLUMN_FLAGS |
| 515 | * @see #ACTION_DOCUMENT_SETTINGS |
| 516 | */ |
| 517 | public static final int FLAG_SUPPORTS_SETTINGS = 1 << 11; |
| 518 | |
| 519 | /** |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 520 | * Flag indicating that a Web link can be obtained for the document. |
| 521 | * |
| 522 | * @see #COLUMN_FLAGS |
Aurimas Liutikas | e701dc1 | 2018-06-01 16:04:37 -0700 | [diff] [blame] | 523 | * @see DocumentsProvider#createWebLinkIntent(String, Bundle) |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 524 | */ |
| 525 | public static final int FLAG_WEB_LINKABLE = 1 << 12; |
| 526 | |
| 527 | /** |
Steve McKay | 168e464 | 2016-03-14 13:02:56 -0700 | [diff] [blame] | 528 | * Flag indicating that a document is not complete, likely its |
| 529 | * contents are being downloaded. Partial files cannot be opened, |
| 530 | * copied, moved in the UI. But they can be deleted and retried |
| 531 | * if they represent a failed download. |
| 532 | * |
| 533 | * @see #COLUMN_FLAGS |
Steve McKay | 168e464 | 2016-03-14 13:02:56 -0700 | [diff] [blame] | 534 | */ |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 535 | public static final int FLAG_PARTIAL = 1 << 13; |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 536 | |
| 537 | /** |
| 538 | * Flag indicating that a document has available metadata that can be read |
| 539 | * using DocumentsContract#getDocumentMetadata |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 540 | * |
| 541 | * @see #COLUMN_FLAGS |
Jeff Sharkey | b95bd44 | 2018-12-11 10:35:02 -0700 | [diff] [blame] | 542 | * @see DocumentsContract#getDocumentMetadata(ContentInterface, Uri) |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 543 | */ |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 544 | public static final int FLAG_SUPPORTS_METADATA = 1 << 14; |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 545 | } |
| 546 | |
Jeff Sharkey | bd3b902 | 2013-08-20 15:20:04 -0700 | [diff] [blame] | 547 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 548 | * Constants related to a root of documents, including {@link Cursor} column |
| 549 | * names and flags. A root is the start of a tree of documents, such as a |
| 550 | * physical storage device, or an account. Each root starts at the directory |
| 551 | * referenced by {@link Root#COLUMN_DOCUMENT_ID}, which can recursively |
| 552 | * contain both documents and directories. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 553 | * <p> |
| 554 | * All columns are <em>read-only</em> to client applications. |
Jeff Sharkey | bd3b902 | 2013-08-20 15:20:04 -0700 | [diff] [blame] | 555 | */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 556 | public final static class Root { |
| 557 | private Root() { |
| 558 | } |
| 559 | |
Jeff Sharkey | a5599ef | 2013-08-15 16:17:41 -0700 | [diff] [blame] | 560 | /** |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 561 | * Unique ID of a root. This ID is both provided by and interpreted by a |
| 562 | * {@link DocumentsProvider}, and should be treated as an opaque value |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 563 | * by client applications. This column is required. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 564 | * <p> |
| 565 | * Type: STRING |
| 566 | */ |
| 567 | public static final String COLUMN_ROOT_ID = "root_id"; |
| 568 | |
| 569 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 570 | * Flags that apply to a root. This column is required. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 571 | * <p> |
| 572 | * Type: INTEGER (int) |
| 573 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 574 | * @see #FLAG_LOCAL_ONLY |
| 575 | * @see #FLAG_SUPPORTS_CREATE |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 576 | * @see #FLAG_SUPPORTS_RECENTS |
| 577 | * @see #FLAG_SUPPORTS_SEARCH |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 578 | */ |
| 579 | public static final String COLUMN_FLAGS = "flags"; |
| 580 | |
| 581 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 582 | * Icon resource ID for a root. This column is required. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 583 | * <p> |
| 584 | * Type: INTEGER (int) |
| 585 | */ |
| 586 | public static final String COLUMN_ICON = "icon"; |
| 587 | |
| 588 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 589 | * Title for a root, which will be shown to a user. This column is |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 590 | * required. For a single storage service surfacing multiple accounts as |
| 591 | * different roots, this title should be the name of the service. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 592 | * <p> |
| 593 | * Type: STRING |
| 594 | */ |
| 595 | public static final String COLUMN_TITLE = "title"; |
| 596 | |
| 597 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 598 | * Summary for this root, which may be shown to a user. This column is |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 599 | * optional, and may be {@code null}. For a single storage service |
| 600 | * surfacing multiple accounts as different roots, this summary should |
| 601 | * be the name of the account. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 602 | * <p> |
| 603 | * Type: STRING |
| 604 | */ |
| 605 | public static final String COLUMN_SUMMARY = "summary"; |
| 606 | |
| 607 | /** |
| 608 | * Document which is a directory that represents the top directory of |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 609 | * this root. This column is required. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 610 | * <p> |
| 611 | * Type: STRING |
| 612 | * |
| 613 | * @see Document#COLUMN_DOCUMENT_ID |
| 614 | */ |
| 615 | public static final String COLUMN_DOCUMENT_ID = "document_id"; |
| 616 | |
| 617 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 618 | * Number of bytes available in this root. This column is optional, and |
| 619 | * may be {@code null} if unknown or unbounded. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 620 | * <p> |
| 621 | * Type: INTEGER (long) |
| 622 | */ |
| 623 | public static final String COLUMN_AVAILABLE_BYTES = "available_bytes"; |
| 624 | |
| 625 | /** |
Tomasz Mikolajewski | 3f78e17 | 2015-06-25 16:17:26 +0900 | [diff] [blame] | 626 | * Capacity of a root in bytes. This column is optional, and may be |
| 627 | * {@code null} if unknown or unbounded. |
Tomasz Mikolajewski | 3f78e17 | 2015-06-25 16:17:26 +0900 | [diff] [blame] | 628 | * <p> |
| 629 | * Type: INTEGER (long) |
| 630 | */ |
| 631 | public static final String COLUMN_CAPACITY_BYTES = "capacity_bytes"; |
| 632 | |
| 633 | /** |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 634 | * MIME types supported by this root. This column is optional, and if |
| 635 | * {@code null} the root is assumed to support all MIME types. Multiple |
| 636 | * MIME types can be separated by a newline. For example, a root |
| 637 | * supporting audio might return "audio/*\napplication/x-flac". |
Jeff Sharkey | 923396b | 2013-09-05 13:55:35 -0700 | [diff] [blame] | 638 | * <p> |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 639 | * Type: STRING |
Jeff Sharkey | 923396b | 2013-09-05 13:55:35 -0700 | [diff] [blame] | 640 | */ |
| 641 | public static final String COLUMN_MIME_TYPES = "mime_types"; |
| 642 | |
Garfield Tan | a7e852e | 2017-02-21 12:34:08 -0800 | [diff] [blame] | 643 | /** |
Ivan Chiang | c26d3c2 | 2019-01-10 19:29:01 +0800 | [diff] [blame] | 644 | * Query arguments supported by this root. This column is optional |
| 645 | * and related to {@link #COLUMN_FLAGS} and {@link #FLAG_SUPPORTS_SEARCH}. |
| 646 | * If the flags include {@link #FLAG_SUPPORTS_SEARCH}, and the column is |
| 647 | * {@code null}, the root is assumed to support {@link #QUERY_ARG_DISPLAY_NAME} |
| 648 | * search of {@link Document#COLUMN_DISPLAY_NAME}. Multiple query arguments |
| 649 | * can be separated by a newline. For example, a root supporting |
| 650 | * {@link #QUERY_ARG_MIME_TYPES} and {@link #QUERY_ARG_DISPLAY_NAME} might |
| 651 | * return "android:query-arg-mime-types\nandroid:query-arg-display-name". |
| 652 | * <p> |
| 653 | * Type: STRING |
| 654 | * @see #COLUMN_FLAGS |
| 655 | * @see #FLAG_SUPPORTS_SEARCH |
| 656 | * @see #QUERY_ARG_DISPLAY_NAME |
| 657 | * @see #QUERY_ARG_FILE_SIZE_OVER |
| 658 | * @see #QUERY_ARG_LAST_MODIFIED_AFTER |
| 659 | * @see #QUERY_ARG_MIME_TYPES |
| 660 | * @see DocumentsProvider#querySearchDocuments(String, String[], |
| 661 | * Bundle) |
| 662 | */ |
| 663 | public static final String COLUMN_QUERY_ARGS = "query_args"; |
| 664 | |
| 665 | /** |
Garfield Tan | a7e852e | 2017-02-21 12:34:08 -0800 | [diff] [blame] | 666 | * MIME type for a root. |
| 667 | */ |
Jeff Sharkey | a61dc8e | 2013-09-05 17:14:14 -0700 | [diff] [blame] | 668 | public static final String MIME_TYPE_ITEM = "vnd.android.document/root"; |
| 669 | |
Jeff Sharkey | 923396b | 2013-09-05 13:55:35 -0700 | [diff] [blame] | 670 | /** |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 671 | * Flag indicating that at least one directory under this root supports |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 672 | * creating content. Roots with this flag will be shown when an |
| 673 | * application interacts with {@link Intent#ACTION_CREATE_DOCUMENT}. |
Jeff Sharkey | 20d96d8 | 2013-07-30 17:08:39 -0700 | [diff] [blame] | 674 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 675 | * @see #COLUMN_FLAGS |
Jeff Sharkey | 20d96d8 | 2013-07-30 17:08:39 -0700 | [diff] [blame] | 676 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 677 | public static final int FLAG_SUPPORTS_CREATE = 1; |
Jeff Sharkey | 20d96d8 | 2013-07-30 17:08:39 -0700 | [diff] [blame] | 678 | |
| 679 | /** |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 680 | * Flag indicating that this root offers content that is strictly local |
| 681 | * on the device. That is, no network requests are made for the content. |
| 682 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 683 | * @see #COLUMN_FLAGS |
| 684 | * @see Intent#EXTRA_LOCAL_ONLY |
Jeff Sharkey | 20d96d8 | 2013-07-30 17:08:39 -0700 | [diff] [blame] | 685 | */ |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 686 | public static final int FLAG_LOCAL_ONLY = 1 << 1; |
| 687 | |
Jeff Sharkey | 20d96d8 | 2013-07-30 17:08:39 -0700 | [diff] [blame] | 688 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 689 | * Flag indicating that this root can be queried to provide recently |
| 690 | * modified documents. |
Jeff Sharkey | 251097b | 2013-09-02 15:07:28 -0700 | [diff] [blame] | 691 | * |
| 692 | * @see #COLUMN_FLAGS |
| 693 | * @see DocumentsContract#buildRecentDocumentsUri(String, String) |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 694 | * @see DocumentsProvider#queryRecentDocuments(String, String[]) |
Jeff Sharkey | 251097b | 2013-09-02 15:07:28 -0700 | [diff] [blame] | 695 | */ |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 696 | public static final int FLAG_SUPPORTS_RECENTS = 1 << 2; |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 697 | |
| 698 | /** |
| 699 | * Flag indicating that this root supports search. |
| 700 | * |
| 701 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 702 | * @see DocumentsContract#buildSearchDocumentsUri(String, String, |
| 703 | * String) |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 704 | * @see DocumentsProvider#querySearchDocuments(String, String, |
| 705 | * String[]) |
Ivan Chiang | c26d3c2 | 2019-01-10 19:29:01 +0800 | [diff] [blame] | 706 | * @see DocumentsProvider#querySearchDocuments(String, String[], |
| 707 | * Bundle) |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 708 | */ |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 709 | public static final int FLAG_SUPPORTS_SEARCH = 1 << 3; |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 710 | |
| 711 | /** |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 712 | * Flag indicating that this root supports testing parent child |
| 713 | * relationships. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 714 | * |
| 715 | * @see #COLUMN_FLAGS |
| 716 | * @see DocumentsProvider#isChildDocument(String, String) |
| 717 | */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 718 | public static final int FLAG_SUPPORTS_IS_CHILD = 1 << 4; |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 719 | |
| 720 | /** |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 721 | * Flag indicating that this root can be ejected. |
| 722 | * |
| 723 | * @see #COLUMN_FLAGS |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 724 | * @see DocumentsContract#ejectRoot(ContentInterface, Uri) |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 725 | * @see DocumentsProvider#ejectRoot(String) |
| 726 | */ |
| 727 | public static final int FLAG_SUPPORTS_EJECT = 1 << 5; |
| 728 | |
| 729 | /** |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 730 | * Flag indicating that this root is currently empty. This may be used |
| 731 | * to hide the root when opening documents, but the root will still be |
| 732 | * shown when creating documents and {@link #FLAG_SUPPORTS_CREATE} is |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 733 | * also set. If the value of this flag changes, such as when a root |
| 734 | * becomes non-empty, you must send a content changed notification for |
| 735 | * {@link DocumentsContract#buildRootsUri(String)}. |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 736 | * |
| 737 | * @see #COLUMN_FLAGS |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 738 | * @see ContentResolver#notifyChange(Uri, |
| 739 | * android.database.ContentObserver, boolean) |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 740 | */ |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 741 | public static final int FLAG_EMPTY = 1 << 6; |
Jeff Sharkey | 6efba22 | 2013-09-27 16:44:11 -0700 | [diff] [blame] | 742 | |
| 743 | /** |
Aga Wronska | 1719b35 | 2016-03-21 11:28:03 -0700 | [diff] [blame] | 744 | * Flag indicating that this root should only be visible to advanced |
| 745 | * users. |
| 746 | * |
| 747 | * @see #COLUMN_FLAGS |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 748 | * {@hide} |
Aga Wronska | 1719b35 | 2016-03-21 11:28:03 -0700 | [diff] [blame] | 749 | */ |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 750 | @SystemApi |
| 751 | public static final int FLAG_ADVANCED = 1 << 16; |
Aga Wronska | 1719b35 | 2016-03-21 11:28:03 -0700 | [diff] [blame] | 752 | |
| 753 | /** |
Jeff Sharkey | 1407d4c | 2015-04-12 21:52:24 -0700 | [diff] [blame] | 754 | * Flag indicating that this root has settings. |
| 755 | * |
| 756 | * @see #COLUMN_FLAGS |
| 757 | * @see DocumentsContract#ACTION_DOCUMENT_ROOT_SETTINGS |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 758 | * {@hide} |
Jeff Sharkey | 1407d4c | 2015-04-12 21:52:24 -0700 | [diff] [blame] | 759 | */ |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 760 | @SystemApi |
| 761 | public static final int FLAG_HAS_SETTINGS = 1 << 17; |
Steve McKay | ba23e54 | 2016-03-02 15:15:00 -0800 | [diff] [blame] | 762 | |
| 763 | /** |
| 764 | * Flag indicating that this root is on removable SD card storage. |
| 765 | * |
| 766 | * @see #COLUMN_FLAGS |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 767 | * {@hide} |
Steve McKay | ba23e54 | 2016-03-02 15:15:00 -0800 | [diff] [blame] | 768 | */ |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 769 | @SystemApi |
| 770 | public static final int FLAG_REMOVABLE_SD = 1 << 18; |
Steve McKay | ba23e54 | 2016-03-02 15:15:00 -0800 | [diff] [blame] | 771 | |
| 772 | /** |
| 773 | * Flag indicating that this root is on removable USB storage. |
| 774 | * |
| 775 | * @see #COLUMN_FLAGS |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 776 | * {@hide} |
Steve McKay | ba23e54 | 2016-03-02 15:15:00 -0800 | [diff] [blame] | 777 | */ |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 778 | @SystemApi |
| 779 | public static final int FLAG_REMOVABLE_USB = 1 << 19; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 780 | } |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 781 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 782 | /** |
| 783 | * Optional boolean flag included in a directory {@link Cursor#getExtras()} |
| 784 | * indicating that a document provider is still loading data. For example, a |
| 785 | * provider has returned some results, but is still waiting on an |
| 786 | * outstanding network request. The provider must send a content changed |
| 787 | * notification when loading is finished. |
| 788 | * |
| 789 | * @see ContentResolver#notifyChange(Uri, android.database.ContentObserver, |
| 790 | * boolean) |
| 791 | */ |
| 792 | public static final String EXTRA_LOADING = "loading"; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 793 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 794 | /** |
| 795 | * Optional string included in a directory {@link Cursor#getExtras()} |
| 796 | * providing an informational message that should be shown to a user. For |
| 797 | * example, a provider may wish to indicate that not all documents are |
| 798 | * available. |
| 799 | */ |
| 800 | public static final String EXTRA_INFO = "info"; |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 801 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 802 | /** |
| 803 | * Optional string included in a directory {@link Cursor#getExtras()} |
| 804 | * providing an error message that should be shown to a user. For example, a |
| 805 | * provider may wish to indicate that a network error occurred. The user may |
| 806 | * choose to retry, resulting in a new query. |
| 807 | */ |
| 808 | public static final String EXTRA_ERROR = "error"; |
| 809 | |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 810 | /** |
| 811 | * Optional result (I'm thinking boolean) answer to a question. |
| 812 | * {@hide} |
| 813 | */ |
| 814 | public static final String EXTRA_RESULT = "result"; |
| 815 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 816 | /** {@hide} */ |
Mathew Inwood | 6750f2e | 2018-08-10 09:29:25 +0100 | [diff] [blame] | 817 | @UnsupportedAppUsage |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 818 | public static final String METHOD_CREATE_DOCUMENT = "android:createDocument"; |
| 819 | /** {@hide} */ |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 820 | public static final String METHOD_RENAME_DOCUMENT = "android:renameDocument"; |
| 821 | /** {@hide} */ |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 822 | public static final String METHOD_DELETE_DOCUMENT = "android:deleteDocument"; |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 823 | /** {@hide} */ |
| 824 | public static final String METHOD_COPY_DOCUMENT = "android:copyDocument"; |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 825 | /** {@hide} */ |
| 826 | public static final String METHOD_MOVE_DOCUMENT = "android:moveDocument"; |
Steve McKay | d3afdee | 2015-11-19 17:27:12 -0800 | [diff] [blame] | 827 | /** {@hide} */ |
| 828 | public static final String METHOD_IS_CHILD_DOCUMENT = "android:isChildDocument"; |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 829 | /** {@hide} */ |
| 830 | public static final String METHOD_REMOVE_DOCUMENT = "android:removeDocument"; |
Ben Lin | e7822fb | 2016-06-24 15:21:08 -0700 | [diff] [blame] | 831 | /** {@hide} */ |
| 832 | public static final String METHOD_EJECT_ROOT = "android:ejectRoot"; |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 833 | /** {@hide} */ |
Garfield Tan | 3f6b68a | 2016-11-01 14:13:38 -0700 | [diff] [blame] | 834 | public static final String METHOD_FIND_DOCUMENT_PATH = "android:findDocumentPath"; |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 835 | /** {@hide} */ |
| 836 | public static final String METHOD_CREATE_WEB_LINK_INTENT = "android:createWebLinkIntent"; |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 837 | /** {@hide} */ |
| 838 | public static final String METHOD_GET_DOCUMENT_METADATA = "android:getDocumentMetadata"; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 839 | |
| 840 | /** {@hide} */ |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 841 | public static final String EXTRA_PARENT_URI = "parentUri"; |
| 842 | /** {@hide} */ |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 843 | public static final String EXTRA_URI = "uri"; |
Jeff Sharkey | 643e99e | 2018-10-22 18:01:27 -0600 | [diff] [blame] | 844 | /** {@hide} */ |
| 845 | public static final String EXTRA_URI_PERMISSIONS = "uriPermissions"; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 846 | |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 847 | /** {@hide} */ |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 848 | public static final String EXTRA_OPTIONS = "options"; |
| 849 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 850 | private static final String PATH_ROOT = "root"; |
| 851 | private static final String PATH_RECENT = "recent"; |
Mathew Inwood | 6750f2e | 2018-08-10 09:29:25 +0100 | [diff] [blame] | 852 | @UnsupportedAppUsage |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 853 | private static final String PATH_DOCUMENT = "document"; |
| 854 | private static final String PATH_CHILDREN = "children"; |
| 855 | private static final String PATH_SEARCH = "search"; |
Mathew Inwood | 6750f2e | 2018-08-10 09:29:25 +0100 | [diff] [blame] | 856 | @UnsupportedAppUsage |
Amin Shaikh | 528ba88 | 2019-02-07 10:03:44 -0500 | [diff] [blame] | 857 | private static final String PATH_TREE = "tree"; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 858 | |
| 859 | private static final String PARAM_QUERY = "query"; |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 860 | private static final String PARAM_MANAGE = "manage"; |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 861 | |
| 862 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 863 | * Build URI representing the roots of a document provider. When queried, a |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 864 | * provider will return one or more rows with columns defined by |
| 865 | * {@link Root}. |
| 866 | * |
| 867 | * @see DocumentsProvider#queryRoots(String[]) |
| 868 | */ |
| 869 | public static Uri buildRootsUri(String authority) { |
| 870 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) |
| 871 | .authority(authority).appendPath(PATH_ROOT).build(); |
| 872 | } |
| 873 | |
| 874 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 875 | * Build URI representing the given {@link Root#COLUMN_ROOT_ID} in a |
Jeff Sharkey | a61dc8e | 2013-09-05 17:14:14 -0700 | [diff] [blame] | 876 | * document provider. |
| 877 | * |
| 878 | * @see #getRootId(Uri) |
| 879 | */ |
| 880 | public static Uri buildRootUri(String authority, String rootId) { |
| 881 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) |
| 882 | .authority(authority).appendPath(PATH_ROOT).appendPath(rootId).build(); |
| 883 | } |
| 884 | |
| 885 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 886 | * Build URI representing the recently modified documents of a specific root |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 887 | * in a document provider. When queried, a provider will return zero or more |
| 888 | * rows with columns defined by {@link Document}. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 889 | * |
| 890 | * @see DocumentsProvider#queryRecentDocuments(String, String[]) |
| 891 | * @see #getRootId(Uri) |
| 892 | */ |
| 893 | public static Uri buildRecentDocumentsUri(String authority, String rootId) { |
| 894 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) |
| 895 | .authority(authority).appendPath(PATH_ROOT).appendPath(rootId) |
| 896 | .appendPath(PATH_RECENT).build(); |
| 897 | } |
| 898 | |
| 899 | /** |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 900 | * Build URI representing access to descendant documents of the given |
| 901 | * {@link Document#COLUMN_DOCUMENT_ID}. |
| 902 | * |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 903 | * @see #getTreeDocumentId(Uri) |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 904 | */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 905 | public static Uri buildTreeDocumentUri(String authority, String documentId) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 906 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority) |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 907 | .appendPath(PATH_TREE).appendPath(documentId).build(); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 908 | } |
| 909 | |
| 910 | /** |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 911 | * Build URI representing the target {@link Document#COLUMN_DOCUMENT_ID} in |
| 912 | * a document provider. When queried, a provider will return a single row |
| 913 | * with columns defined by {@link Document}. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 914 | * |
| 915 | * @see DocumentsProvider#queryDocument(String, String[]) |
| 916 | * @see #getDocumentId(Uri) |
| 917 | */ |
| 918 | public static Uri buildDocumentUri(String authority, String documentId) { |
| 919 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) |
| 920 | .authority(authority).appendPath(PATH_DOCUMENT).appendPath(documentId).build(); |
| 921 | } |
| 922 | |
| 923 | /** |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 924 | * Build URI representing the target {@link Document#COLUMN_DOCUMENT_ID} in |
| 925 | * a document provider. When queried, a provider will return a single row |
| 926 | * with columns defined by {@link Document}. |
| 927 | * <p> |
| 928 | * However, instead of directly accessing the target document, the returned |
| 929 | * URI will leverage access granted through a subtree URI, typically |
| 930 | * returned by {@link Intent#ACTION_OPEN_DOCUMENT_TREE}. The target document |
| 931 | * must be a descendant (child, grandchild, etc) of the subtree. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 932 | * <p> |
| 933 | * This is typically used to access documents under a user-selected |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 934 | * directory tree, since it doesn't require the user to separately confirm |
| 935 | * each new document access. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 936 | * |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 937 | * @param treeUri the subtree to leverage to gain access to the target |
| 938 | * document. The target directory must be a descendant of this |
| 939 | * subtree. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 940 | * @param documentId the target document, which the caller may not have |
| 941 | * direct access to. |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 942 | * @see Intent#ACTION_OPEN_DOCUMENT_TREE |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 943 | * @see DocumentsProvider#isChildDocument(String, String) |
| 944 | * @see #buildDocumentUri(String, String) |
| 945 | */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 946 | public static Uri buildDocumentUriUsingTree(Uri treeUri, String documentId) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 947 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 948 | .authority(treeUri.getAuthority()).appendPath(PATH_TREE) |
| 949 | .appendPath(getTreeDocumentId(treeUri)).appendPath(PATH_DOCUMENT) |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 950 | .appendPath(documentId).build(); |
| 951 | } |
| 952 | |
| 953 | /** {@hide} */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 954 | public static Uri buildDocumentUriMaybeUsingTree(Uri baseUri, String documentId) { |
| 955 | if (isTreeUri(baseUri)) { |
| 956 | return buildDocumentUriUsingTree(baseUri, documentId); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 957 | } else { |
| 958 | return buildDocumentUri(baseUri.getAuthority(), documentId); |
| 959 | } |
| 960 | } |
| 961 | |
| 962 | /** |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 963 | * Build URI representing the children of the target directory in a document |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 964 | * provider. When queried, a provider will return zero or more rows with |
| 965 | * columns defined by {@link Document}. |
| 966 | * |
| 967 | * @param parentDocumentId the document to return children for, which must |
| 968 | * be a directory with MIME type of |
| 969 | * {@link Document#MIME_TYPE_DIR}. |
| 970 | * @see DocumentsProvider#queryChildDocuments(String, String[], String) |
| 971 | * @see #getDocumentId(Uri) |
| 972 | */ |
| 973 | public static Uri buildChildDocumentsUri(String authority, String parentDocumentId) { |
| 974 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority) |
| 975 | .appendPath(PATH_DOCUMENT).appendPath(parentDocumentId).appendPath(PATH_CHILDREN) |
| 976 | .build(); |
| 977 | } |
| 978 | |
| 979 | /** |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 980 | * Build URI representing the children of the target directory in a document |
| 981 | * provider. When queried, a provider will return zero or more rows with |
| 982 | * columns defined by {@link Document}. |
| 983 | * <p> |
| 984 | * However, instead of directly accessing the target directory, the returned |
| 985 | * URI will leverage access granted through a subtree URI, typically |
| 986 | * returned by {@link Intent#ACTION_OPEN_DOCUMENT_TREE}. The target |
| 987 | * directory must be a descendant (child, grandchild, etc) of the subtree. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 988 | * <p> |
| 989 | * This is typically used to access documents under a user-selected |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 990 | * directory tree, since it doesn't require the user to separately confirm |
| 991 | * each new document access. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 992 | * |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 993 | * @param treeUri the subtree to leverage to gain access to the target |
| 994 | * document. The target directory must be a descendant of this |
| 995 | * subtree. |
| 996 | * @param parentDocumentId the document to return children for, which the |
| 997 | * caller may not have direct access to, and which must be a |
| 998 | * directory with MIME type of {@link Document#MIME_TYPE_DIR}. |
| 999 | * @see Intent#ACTION_OPEN_DOCUMENT_TREE |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1000 | * @see DocumentsProvider#isChildDocument(String, String) |
| 1001 | * @see #buildChildDocumentsUri(String, String) |
| 1002 | */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1003 | public static Uri buildChildDocumentsUriUsingTree(Uri treeUri, String parentDocumentId) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1004 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1005 | .authority(treeUri.getAuthority()).appendPath(PATH_TREE) |
| 1006 | .appendPath(getTreeDocumentId(treeUri)).appendPath(PATH_DOCUMENT) |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1007 | .appendPath(parentDocumentId).appendPath(PATH_CHILDREN).build(); |
| 1008 | } |
| 1009 | |
| 1010 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 1011 | * Build URI representing a search for matching documents under a specific |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 1012 | * root in a document provider. When queried, a provider will return zero or |
| 1013 | * more rows with columns defined by {@link Document}. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1014 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1015 | * @see DocumentsProvider#querySearchDocuments(String, String, String[]) |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 1016 | * @see #getRootId(Uri) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1017 | * @see #getSearchDocumentsQuery(Uri) |
| 1018 | */ |
| 1019 | public static Uri buildSearchDocumentsUri( |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 1020 | String authority, String rootId, String query) { |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1021 | return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority) |
Jeff Sharkey | 3e1189b | 2013-09-12 21:59:06 -0700 | [diff] [blame] | 1022 | .appendPath(PATH_ROOT).appendPath(rootId).appendPath(PATH_SEARCH) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1023 | .appendQueryParameter(PARAM_QUERY, query).build(); |
| 1024 | } |
| 1025 | |
| 1026 | /** |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 1027 | * Check if the values match the query arguments. |
| 1028 | * |
| 1029 | * @param queryArgs the query arguments |
| 1030 | * @param displayName the display time to check against |
| 1031 | * @param mimeType the mime type to check against |
| 1032 | * @param lastModified the last modified time to check against |
| 1033 | * @param size the size to check against |
| 1034 | * @hide |
| 1035 | */ |
| 1036 | public static boolean matchSearchQueryArguments(Bundle queryArgs, String displayName, |
| 1037 | String mimeType, long lastModified, long size) { |
| 1038 | if (queryArgs == null) { |
| 1039 | return true; |
| 1040 | } |
| 1041 | |
| 1042 | final String argDisplayName = queryArgs.getString(QUERY_ARG_DISPLAY_NAME, ""); |
| 1043 | if (!argDisplayName.isEmpty()) { |
| 1044 | // TODO (118795812) : Enhance the search string handled in DocumentsProvider |
| 1045 | if (!displayName.toLowerCase().contains(argDisplayName.toLowerCase())) { |
| 1046 | return false; |
| 1047 | } |
| 1048 | } |
| 1049 | |
| 1050 | final long argFileSize = queryArgs.getLong(QUERY_ARG_FILE_SIZE_OVER, -1 /* defaultValue */); |
| 1051 | if (argFileSize != -1 && size < argFileSize) { |
| 1052 | return false; |
| 1053 | } |
| 1054 | |
| 1055 | final long argLastModified = queryArgs.getLong(QUERY_ARG_LAST_MODIFIED_AFTER, |
| 1056 | -1 /* defaultValue */); |
| 1057 | if (argLastModified != -1 && lastModified < argLastModified) { |
| 1058 | return false; |
| 1059 | } |
| 1060 | |
| 1061 | final String[] argMimeTypes = queryArgs.getStringArray(QUERY_ARG_MIME_TYPES); |
| 1062 | if (argMimeTypes != null && argMimeTypes.length > 0) { |
| 1063 | mimeType = Intent.normalizeMimeType(mimeType); |
| 1064 | for (String type : argMimeTypes) { |
| 1065 | if (MimeTypeFilter.matches(mimeType, Intent.normalizeMimeType(type))) { |
| 1066 | return true; |
| 1067 | } |
| 1068 | } |
| 1069 | return false; |
| 1070 | } |
| 1071 | return true; |
| 1072 | } |
| 1073 | |
| 1074 | /** |
| 1075 | * Get the handled query arguments from the query bundle. The handled arguments are |
Ivan Chiang | 1edfcb2 | 2018-11-14 13:20:22 +0800 | [diff] [blame] | 1076 | * {@link DocumentsContract#QUERY_ARG_EXCLUDE_MEDIA}, |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 1077 | * {@link DocumentsContract#QUERY_ARG_DISPLAY_NAME}, |
| 1078 | * {@link DocumentsContract#QUERY_ARG_MIME_TYPES}, |
| 1079 | * {@link DocumentsContract#QUERY_ARG_FILE_SIZE_OVER} and |
| 1080 | * {@link DocumentsContract#QUERY_ARG_LAST_MODIFIED_AFTER}. |
| 1081 | * |
| 1082 | * @param queryArgs the query arguments to be parsed. |
| 1083 | * @return the handled query arguments |
| 1084 | * @hide |
| 1085 | */ |
| 1086 | public static String[] getHandledQueryArguments(Bundle queryArgs) { |
| 1087 | if (queryArgs == null) { |
| 1088 | return new String[0]; |
| 1089 | } |
| 1090 | |
| 1091 | final ArrayList<String> args = new ArrayList<>(); |
Ivan Chiang | 1edfcb2 | 2018-11-14 13:20:22 +0800 | [diff] [blame] | 1092 | |
| 1093 | if (queryArgs.keySet().contains(QUERY_ARG_EXCLUDE_MEDIA)) { |
| 1094 | args.add(QUERY_ARG_EXCLUDE_MEDIA); |
| 1095 | } |
| 1096 | |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 1097 | if (queryArgs.keySet().contains(QUERY_ARG_DISPLAY_NAME)) { |
| 1098 | args.add(QUERY_ARG_DISPLAY_NAME); |
| 1099 | } |
| 1100 | |
| 1101 | if (queryArgs.keySet().contains(QUERY_ARG_FILE_SIZE_OVER)) { |
| 1102 | args.add(QUERY_ARG_FILE_SIZE_OVER); |
| 1103 | } |
| 1104 | |
| 1105 | if (queryArgs.keySet().contains(QUERY_ARG_LAST_MODIFIED_AFTER)) { |
| 1106 | args.add(QUERY_ARG_LAST_MODIFIED_AFTER); |
| 1107 | } |
| 1108 | |
| 1109 | if (queryArgs.keySet().contains(QUERY_ARG_MIME_TYPES)) { |
| 1110 | args.add(QUERY_ARG_MIME_TYPES); |
| 1111 | } |
| 1112 | return args.toArray(new String[0]); |
| 1113 | } |
| 1114 | |
| 1115 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 1116 | * Test if the given URI represents a {@link Document} backed by a |
Jeff Sharkey | ee2f7df | 2013-09-26 11:32:30 -0700 | [diff] [blame] | 1117 | * {@link DocumentsProvider}. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1118 | * |
| 1119 | * @see #buildDocumentUri(String, String) |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1120 | * @see #buildDocumentUriUsingTree(Uri, String) |
Jeff Sharkey | ee2f7df | 2013-09-26 11:32:30 -0700 | [diff] [blame] | 1121 | */ |
Steve McKay | 323ee3e | 2015-09-25 16:02:56 -0700 | [diff] [blame] | 1122 | public static boolean isDocumentUri(Context context, @Nullable Uri uri) { |
| 1123 | if (isContentUri(uri) && isDocumentsProvider(context, uri.getAuthority())) { |
| 1124 | final List<String> paths = uri.getPathSegments(); |
| 1125 | if (paths.size() == 2) { |
| 1126 | return PATH_DOCUMENT.equals(paths.get(0)); |
| 1127 | } else if (paths.size() == 4) { |
| 1128 | return PATH_TREE.equals(paths.get(0)) && PATH_DOCUMENT.equals(paths.get(2)); |
| 1129 | } |
Jeff Sharkey | ee2f7df | 2013-09-26 11:32:30 -0700 | [diff] [blame] | 1130 | } |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1131 | return false; |
| 1132 | } |
Jeff Sharkey | ee2f7df | 2013-09-26 11:32:30 -0700 | [diff] [blame] | 1133 | |
Ivan Chiang | 9f5a059 | 2018-09-26 16:00:02 +0800 | [diff] [blame] | 1134 | /** |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 1135 | * Test if the given URI represents all roots of the authority |
| 1136 | * backed by {@link DocumentsProvider}. |
Ivan Chiang | 9f5a059 | 2018-09-26 16:00:02 +0800 | [diff] [blame] | 1137 | * |
| 1138 | * @see #buildRootsUri(String) |
Ivan Chiang | 9f5a059 | 2018-09-26 16:00:02 +0800 | [diff] [blame] | 1139 | */ |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 1140 | public static boolean isRootsUri(@NonNull Context context, @Nullable Uri uri) { |
| 1141 | Preconditions.checkNotNull(context, "context can not be null"); |
Ivan Chiang | 9f5a059 | 2018-09-26 16:00:02 +0800 | [diff] [blame] | 1142 | return isRootUri(context, uri, 1 /* pathSize */); |
| 1143 | } |
| 1144 | |
| 1145 | /** |
| 1146 | * Test if the given URI represents specific root backed by {@link DocumentsProvider}. |
| 1147 | * |
| 1148 | * @see #buildRootUri(String, String) |
Ivan Chiang | 9f5a059 | 2018-09-26 16:00:02 +0800 | [diff] [blame] | 1149 | */ |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 1150 | public static boolean isRootUri(@NonNull Context context, @Nullable Uri uri) { |
| 1151 | Preconditions.checkNotNull(context, "context can not be null"); |
Ivan Chiang | 9f5a059 | 2018-09-26 16:00:02 +0800 | [diff] [blame] | 1152 | return isRootUri(context, uri, 2 /* pathSize */); |
Steve McKay | 323ee3e | 2015-09-25 16:02:56 -0700 | [diff] [blame] | 1153 | } |
| 1154 | |
| 1155 | /** {@hide} */ |
| 1156 | public static boolean isContentUri(@Nullable Uri uri) { |
| 1157 | return uri != null && ContentResolver.SCHEME_CONTENT.equals(uri.getScheme()); |
| 1158 | } |
| 1159 | |
Tomasz Mikolajewski | 7db9c81 | 2016-01-28 09:50:01 +0900 | [diff] [blame] | 1160 | /** |
| 1161 | * Test if the given URI represents a {@link Document} tree. |
| 1162 | * |
| 1163 | * @see #buildTreeDocumentUri(String, String) |
Tomasz Mikolajewski | 90a7533 | 2016-07-13 10:14:59 +0900 | [diff] [blame] | 1164 | * @see #getTreeDocumentId(Uri) |
Tomasz Mikolajewski | 7db9c81 | 2016-01-28 09:50:01 +0900 | [diff] [blame] | 1165 | */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1166 | public static boolean isTreeUri(Uri uri) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1167 | final List<String> paths = uri.getPathSegments(); |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1168 | return (paths.size() >= 2 && PATH_TREE.equals(paths.get(0))); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1169 | } |
| 1170 | |
Ivan Chiang | 9f5a059 | 2018-09-26 16:00:02 +0800 | [diff] [blame] | 1171 | private static boolean isRootUri(Context context, @Nullable Uri uri, int pathSize) { |
| 1172 | if (isContentUri(uri) && isDocumentsProvider(context, uri.getAuthority())) { |
| 1173 | final List<String> paths = uri.getPathSegments(); |
| 1174 | return (paths.size() == pathSize && PATH_ROOT.equals(paths.get(0))); |
| 1175 | } |
| 1176 | return false; |
| 1177 | } |
| 1178 | |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1179 | private static boolean isDocumentsProvider(Context context, String authority) { |
Jeff Sharkey | d2e1e81 | 2013-10-09 13:31:13 -0700 | [diff] [blame] | 1180 | final Intent intent = new Intent(PROVIDER_INTERFACE); |
| 1181 | final List<ResolveInfo> infos = context.getPackageManager() |
| 1182 | .queryIntentContentProviders(intent, 0); |
| 1183 | for (ResolveInfo info : infos) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1184 | if (authority.equals(info.providerInfo.authority)) { |
Jeff Sharkey | d2e1e81 | 2013-10-09 13:31:13 -0700 | [diff] [blame] | 1185 | return true; |
| 1186 | } |
Jeff Sharkey | ee2f7df | 2013-09-26 11:32:30 -0700 | [diff] [blame] | 1187 | } |
| 1188 | return false; |
| 1189 | } |
| 1190 | |
| 1191 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 1192 | * Extract the {@link Root#COLUMN_ROOT_ID} from the given URI. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1193 | */ |
| 1194 | public static String getRootId(Uri rootUri) { |
| 1195 | final List<String> paths = rootUri.getPathSegments(); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1196 | if (paths.size() >= 2 && PATH_ROOT.equals(paths.get(0))) { |
| 1197 | return paths.get(1); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1198 | } |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1199 | throw new IllegalArgumentException("Invalid URI: " + rootUri); |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1200 | } |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1201 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1202 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 1203 | * Extract the {@link Document#COLUMN_DOCUMENT_ID} from the given URI. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1204 | * |
| 1205 | * @see #isDocumentUri(Context, Uri) |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1206 | */ |
| 1207 | public static String getDocumentId(Uri documentUri) { |
| 1208 | final List<String> paths = documentUri.getPathSegments(); |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1209 | if (paths.size() >= 2 && PATH_DOCUMENT.equals(paths.get(0))) { |
| 1210 | return paths.get(1); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1211 | } |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1212 | if (paths.size() >= 4 && PATH_TREE.equals(paths.get(0)) |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1213 | && PATH_DOCUMENT.equals(paths.get(2))) { |
| 1214 | return paths.get(3); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1215 | } |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1216 | throw new IllegalArgumentException("Invalid URI: " + documentUri); |
| 1217 | } |
| 1218 | |
| 1219 | /** |
| 1220 | * Extract the via {@link Document#COLUMN_DOCUMENT_ID} from the given URI. |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1221 | */ |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1222 | public static String getTreeDocumentId(Uri documentUri) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1223 | final List<String> paths = documentUri.getPathSegments(); |
Jeff Sharkey | b9fbb72 | 2014-06-04 16:42:47 -0700 | [diff] [blame] | 1224 | if (paths.size() >= 2 && PATH_TREE.equals(paths.get(0))) { |
Jeff Sharkey | 21de56a | 2014-04-05 19:05:24 -0700 | [diff] [blame] | 1225 | return paths.get(1); |
| 1226 | } |
| 1227 | throw new IllegalArgumentException("Invalid URI: " + documentUri); |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1228 | } |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1229 | |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1230 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 1231 | * Extract the search query from a URI built by |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1232 | * {@link #buildSearchDocumentsUri(String, String, String)}. |
| 1233 | */ |
| 1234 | public static String getSearchDocumentsQuery(Uri searchDocumentsUri) { |
| 1235 | return searchDocumentsUri.getQueryParameter(PARAM_QUERY); |
Jeff Sharkey | 20d96d8 | 2013-07-30 17:08:39 -0700 | [diff] [blame] | 1236 | } |
| 1237 | |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 1238 | /** |
| 1239 | * Extract the search query from a Bundle |
| 1240 | * {@link #QUERY_ARG_DISPLAY_NAME}. |
| 1241 | * {@hide} |
| 1242 | */ |
| 1243 | public static String getSearchDocumentsQuery(@NonNull Bundle bundle) { |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 1244 | Preconditions.checkNotNull(bundle, "bundle can not be null"); |
Ivan Chiang | a972d04 | 2018-10-15 15:23:02 +0800 | [diff] [blame] | 1245 | return bundle.getString(QUERY_ARG_DISPLAY_NAME, "" /* defaultValue */); |
| 1246 | } |
| 1247 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1248 | /** |
| 1249 | * Build URI that append the query parameter {@link PARAM_MANAGE} to |
| 1250 | * enable the manage mode. |
| 1251 | * @see DocumentsProvider#queryChildDocumentsForManage(String parentDocId, String[], String) |
| 1252 | * {@hide} |
| 1253 | */ |
| 1254 | @SystemApi |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 1255 | public static Uri setManageMode(Uri uri) { |
| 1256 | return uri.buildUpon().appendQueryParameter(PARAM_MANAGE, "true").build(); |
| 1257 | } |
| 1258 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1259 | /** |
| 1260 | * Extract the manage mode from a URI built by |
| 1261 | * {@link #setManageMode(Uri)}. |
| 1262 | * {@hide} |
| 1263 | */ |
| 1264 | @SystemApi |
Jeff Sharkey | 4ec9739 | 2013-09-10 12:04:26 -0700 | [diff] [blame] | 1265 | public static boolean isManageMode(Uri uri) { |
| 1266 | return uri.getBooleanQueryParameter(PARAM_MANAGE, false); |
| 1267 | } |
| 1268 | |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 1269 | /** |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 1270 | * Return thumbnail representing the document at the given URI. Callers are |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1271 | * responsible for their own in-memory caching. |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 1272 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1273 | * @param documentUri document to return thumbnail for, which must have |
| 1274 | * {@link Document#FLAG_SUPPORTS_THUMBNAIL} set. |
| 1275 | * @param size optimal thumbnail size desired. A provider may return a |
| 1276 | * thumbnail of a different size, but never more than double the |
| 1277 | * requested size. |
Jeff Sharkey | e8c00d8 | 2013-10-15 15:46:10 -0700 | [diff] [blame] | 1278 | * @param signal signal used to indicate if caller is no longer interested |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1279 | * in the thumbnail. |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 1280 | * @return decoded thumbnail, or {@code null} if problem was encountered. |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1281 | * @see DocumentsProvider#openDocumentThumbnail(String, Point, |
| 1282 | * android.os.CancellationSignal) |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 1283 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1284 | public static @Nullable Bitmap getDocumentThumbnail(@NonNull ContentResolver content, |
| 1285 | @NonNull Uri documentUri, @NonNull Point size, @Nullable CancellationSignal signal) |
| 1286 | throws FileNotFoundException { |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 1287 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1288 | return ContentResolver.loadThumbnail(content, documentUri, Point.convert(size), signal, |
| 1289 | ImageDecoder.ALLOCATOR_SOFTWARE); |
Jeff Sharkey | 7aa7601 | 2013-09-30 14:26:27 -0700 | [diff] [blame] | 1290 | } catch (Exception e) { |
Jeff Sharkey | 3381931 | 2013-10-29 11:56:37 -0700 | [diff] [blame] | 1291 | if (!(e instanceof OperationCanceledException)) { |
| 1292 | Log.w(TAG, "Failed to load thumbnail for " + documentUri + ": " + e); |
| 1293 | } |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1294 | rethrowIfNecessary(e); |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 1295 | return null; |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 1296 | } |
| 1297 | } |
| 1298 | |
Jeff Sharkey | 5b83f85 | 2013-08-14 18:29:19 -0700 | [diff] [blame] | 1299 | /** |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1300 | * Create a new document with given MIME type and display name. |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 1301 | * |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 1302 | * @param parentDocumentUri directory with {@link Document#FLAG_DIR_SUPPORTS_CREATE} |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1303 | * @param mimeType MIME type of new document |
| 1304 | * @param displayName name of new document |
| 1305 | * @return newly created document, or {@code null} if failed |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 1306 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1307 | public static @Nullable Uri createDocument(@NonNull ContentResolver content, |
| 1308 | @NonNull Uri parentDocumentUri, @NonNull String mimeType, @NonNull String displayName) |
| 1309 | throws FileNotFoundException { |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 1310 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1311 | final Bundle in = new Bundle(); |
| 1312 | in.putParcelable(DocumentsContract.EXTRA_URI, parentDocumentUri); |
| 1313 | in.putString(Document.COLUMN_MIME_TYPE, mimeType); |
| 1314 | in.putString(Document.COLUMN_DISPLAY_NAME, displayName); |
| 1315 | |
| 1316 | final Bundle out = content.call(parentDocumentUri.getAuthority(), |
| 1317 | METHOD_CREATE_DOCUMENT, null, in); |
| 1318 | return out.getParcelable(DocumentsContract.EXTRA_URI); |
Jeff Sharkey | 7aa7601 | 2013-09-30 14:26:27 -0700 | [diff] [blame] | 1319 | } catch (Exception e) { |
| 1320 | Log.w(TAG, "Failed to create document", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1321 | rethrowIfNecessary(e); |
Jeff Sharkey | 7aa7601 | 2013-09-30 14:26:27 -0700 | [diff] [blame] | 1322 | return null; |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 1323 | } |
| 1324 | } |
| 1325 | |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1326 | /** |
| 1327 | * Test if a document is descendant (child, grandchild, etc) from the given |
| 1328 | * parent. |
| 1329 | * |
| 1330 | * @param parentDocumentUri parent to verify against. |
| 1331 | * @param childDocumentUri child to verify. |
| 1332 | * @return if given document is a descendant of the given parent. |
| 1333 | * @see Root#FLAG_SUPPORTS_IS_CHILD |
| 1334 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1335 | public static boolean isChildDocument(@NonNull ContentResolver content, |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 1336 | @NonNull Uri parentDocumentUri, @NonNull Uri childDocumentUri) |
| 1337 | throws FileNotFoundException { |
| 1338 | Preconditions.checkNotNull(content, "content can not be null"); |
| 1339 | Preconditions.checkNotNull(parentDocumentUri, "parentDocumentUri can not be null"); |
| 1340 | Preconditions.checkNotNull(childDocumentUri, "childDocumentUri can not be null"); |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1341 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1342 | final Bundle in = new Bundle(); |
| 1343 | in.putParcelable(DocumentsContract.EXTRA_URI, parentDocumentUri); |
| 1344 | in.putParcelable(DocumentsContract.EXTRA_TARGET_URI, childDocumentUri); |
| 1345 | |
| 1346 | final Bundle out = content.call(parentDocumentUri.getAuthority(), |
| 1347 | METHOD_IS_CHILD_DOCUMENT, null, in); |
| 1348 | if (out == null) { |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 1349 | throw new RemoteException("Failed to get a response from isChildDocument query."); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1350 | } |
| 1351 | if (!out.containsKey(DocumentsContract.EXTRA_RESULT)) { |
| 1352 | throw new RemoteException("Response did not include result field.."); |
| 1353 | } |
| 1354 | return out.getBoolean(DocumentsContract.EXTRA_RESULT); |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1355 | } catch (Exception e) { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1356 | Log.w(TAG, "Failed to create document", e); |
| 1357 | rethrowIfNecessary(e); |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1358 | return false; |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1359 | } |
| 1360 | } |
| 1361 | |
Jeff Sharkey | 5b83f85 | 2013-08-14 18:29:19 -0700 | [diff] [blame] | 1362 | /** |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 1363 | * Change the display name of an existing document. |
| 1364 | * <p> |
| 1365 | * If the underlying provider needs to create a new |
| 1366 | * {@link Document#COLUMN_DOCUMENT_ID} to represent the updated display |
| 1367 | * name, that new document is returned and the original document is no |
| 1368 | * longer valid. Otherwise, the original document is returned. |
| 1369 | * |
| 1370 | * @param documentUri document with {@link Document#FLAG_SUPPORTS_RENAME} |
| 1371 | * @param displayName updated name for document |
| 1372 | * @return the existing or new document after the rename, or {@code null} if |
| 1373 | * failed. |
| 1374 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1375 | public static @Nullable Uri renameDocument(@NonNull ContentResolver content, |
| 1376 | @NonNull Uri documentUri, @NonNull String displayName) throws FileNotFoundException { |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 1377 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1378 | final Bundle in = new Bundle(); |
| 1379 | in.putParcelable(DocumentsContract.EXTRA_URI, documentUri); |
| 1380 | in.putString(Document.COLUMN_DISPLAY_NAME, displayName); |
| 1381 | |
| 1382 | final Bundle out = content.call(documentUri.getAuthority(), |
| 1383 | METHOD_RENAME_DOCUMENT, null, in); |
| 1384 | final Uri outUri = out.getParcelable(DocumentsContract.EXTRA_URI); |
| 1385 | return (outUri != null) ? outUri : documentUri; |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 1386 | } catch (Exception e) { |
| 1387 | Log.w(TAG, "Failed to rename document", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1388 | rethrowIfNecessary(e); |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 1389 | return null; |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 1390 | } |
| 1391 | } |
| 1392 | |
Jeff Sharkey | b7e1255 | 2014-05-21 22:22:03 -0700 | [diff] [blame] | 1393 | /** |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1394 | * Delete the given document. |
| 1395 | * |
Jeff Sharkey | ae9b51b | 2013-08-31 15:02:20 -0700 | [diff] [blame] | 1396 | * @param documentUri document with {@link Document#FLAG_SUPPORTS_DELETE} |
Jeff Sharkey | 7aa7601 | 2013-09-30 14:26:27 -0700 | [diff] [blame] | 1397 | * @return if the document was deleted successfully. |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1398 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1399 | public static boolean deleteDocument(@NonNull ContentResolver content, @NonNull Uri documentUri) |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 1400 | throws FileNotFoundException { |
Jeff Sharkey | de2b22f | 2013-09-11 17:33:06 -0700 | [diff] [blame] | 1401 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1402 | final Bundle in = new Bundle(); |
| 1403 | in.putParcelable(DocumentsContract.EXTRA_URI, documentUri); |
| 1404 | |
| 1405 | content.call(documentUri.getAuthority(), |
| 1406 | METHOD_DELETE_DOCUMENT, null, in); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1407 | return true; |
| 1408 | } catch (Exception e) { |
| 1409 | Log.w(TAG, "Failed to delete document", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1410 | rethrowIfNecessary(e); |
Jeff Sharkey | aeb16e2 | 2013-08-27 18:26:48 -0700 | [diff] [blame] | 1411 | return false; |
| 1412 | } |
Jeff Sharkey | 5b83f85 | 2013-08-14 18:29:19 -0700 | [diff] [blame] | 1413 | } |
Jeff Sharkey | 7aa7601 | 2013-09-30 14:26:27 -0700 | [diff] [blame] | 1414 | |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 1415 | /** |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 1416 | * Copies the given document. |
| 1417 | * |
| 1418 | * @param sourceDocumentUri document with {@link Document#FLAG_SUPPORTS_COPY} |
| 1419 | * @param targetParentDocumentUri document which will become a parent of the source |
| 1420 | * document's copy. |
| 1421 | * @return the copied document, or {@code null} if failed. |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 1422 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1423 | public static @Nullable Uri copyDocument(@NonNull ContentResolver content, |
| 1424 | @NonNull Uri sourceDocumentUri, @NonNull Uri targetParentDocumentUri) |
| 1425 | throws FileNotFoundException { |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 1426 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1427 | final Bundle in = new Bundle(); |
| 1428 | in.putParcelable(DocumentsContract.EXTRA_URI, sourceDocumentUri); |
| 1429 | in.putParcelable(DocumentsContract.EXTRA_TARGET_URI, targetParentDocumentUri); |
| 1430 | |
| 1431 | final Bundle out = content.call(sourceDocumentUri.getAuthority(), |
| 1432 | METHOD_COPY_DOCUMENT, null, in); |
| 1433 | return out.getParcelable(DocumentsContract.EXTRA_URI); |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 1434 | } catch (Exception e) { |
| 1435 | Log.w(TAG, "Failed to copy document", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1436 | rethrowIfNecessary(e); |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 1437 | return null; |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 1438 | } |
| 1439 | } |
| 1440 | |
Tomasz Mikolajewski | 74fe181 | 2015-06-12 17:13:26 -0700 | [diff] [blame] | 1441 | /** |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1442 | * Moves the given document under a new parent. |
| 1443 | * |
| 1444 | * @param sourceDocumentUri document with {@link Document#FLAG_SUPPORTS_MOVE} |
Tomasz Mikolajewski | d46ecbc | 2016-01-25 14:26:54 +0900 | [diff] [blame] | 1445 | * @param sourceParentDocumentUri parent document of the document to move. |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1446 | * @param targetParentDocumentUri document which will become a new parent of the source |
| 1447 | * document. |
| 1448 | * @return the moved document, or {@code null} if failed. |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1449 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1450 | public static @Nullable Uri moveDocument(@NonNull ContentResolver content, |
| 1451 | @NonNull Uri sourceDocumentUri, @NonNull Uri sourceParentDocumentUri, |
| 1452 | @NonNull Uri targetParentDocumentUri) throws FileNotFoundException { |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1453 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1454 | final Bundle in = new Bundle(); |
| 1455 | in.putParcelable(DocumentsContract.EXTRA_URI, sourceDocumentUri); |
| 1456 | in.putParcelable(DocumentsContract.EXTRA_PARENT_URI, sourceParentDocumentUri); |
| 1457 | in.putParcelable(DocumentsContract.EXTRA_TARGET_URI, targetParentDocumentUri); |
| 1458 | |
| 1459 | final Bundle out = content.call(sourceDocumentUri.getAuthority(), |
| 1460 | METHOD_MOVE_DOCUMENT, null, in); |
| 1461 | return out.getParcelable(DocumentsContract.EXTRA_URI); |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1462 | } catch (Exception e) { |
| 1463 | Log.w(TAG, "Failed to move document", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1464 | rethrowIfNecessary(e); |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1465 | return null; |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1466 | } |
| 1467 | } |
| 1468 | |
Tomasz Mikolajewski | a375a99 | 2015-06-25 15:39:27 +0900 | [diff] [blame] | 1469 | /** |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 1470 | * Removes the given document from a parent directory. |
| 1471 | * |
| 1472 | * <p>In contrast to {@link #deleteDocument} it requires specifying the parent. |
| 1473 | * This method is especially useful if the document can be in multiple parents. |
| 1474 | * |
| 1475 | * @param documentUri document with {@link Document#FLAG_SUPPORTS_REMOVE} |
| 1476 | * @param parentDocumentUri parent document of the document to remove. |
| 1477 | * @return true if the document was removed successfully. |
| 1478 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1479 | public static boolean removeDocument(@NonNull ContentResolver content, @NonNull Uri documentUri, |
| 1480 | @NonNull Uri parentDocumentUri) throws FileNotFoundException { |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 1481 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1482 | final Bundle in = new Bundle(); |
| 1483 | in.putParcelable(DocumentsContract.EXTRA_URI, documentUri); |
| 1484 | in.putParcelable(DocumentsContract.EXTRA_PARENT_URI, parentDocumentUri); |
| 1485 | |
| 1486 | content.call(documentUri.getAuthority(), |
| 1487 | METHOD_REMOVE_DOCUMENT, null, in); |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 1488 | return true; |
| 1489 | } catch (Exception e) { |
| 1490 | Log.w(TAG, "Failed to remove document", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1491 | rethrowIfNecessary(e); |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 1492 | return false; |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 1493 | } |
| 1494 | } |
| 1495 | |
Garfield Tan | 8787703 | 2017-03-22 12:01:14 -0700 | [diff] [blame] | 1496 | /** |
| 1497 | * Ejects the given root. It throws {@link IllegalStateException} when ejection failed. |
| 1498 | * |
| 1499 | * @param rootUri root with {@link Root#FLAG_SUPPORTS_EJECT} to be ejected |
| 1500 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1501 | public static void ejectRoot(@NonNull ContentResolver content, @NonNull Uri rootUri) { |
Ben Lin | e7822fb | 2016-06-24 15:21:08 -0700 | [diff] [blame] | 1502 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1503 | final Bundle in = new Bundle(); |
| 1504 | in.putParcelable(DocumentsContract.EXTRA_URI, rootUri); |
| 1505 | |
| 1506 | content.call(rootUri.getAuthority(), |
| 1507 | METHOD_EJECT_ROOT, null, in); |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1508 | } catch (Exception e) { |
| 1509 | Log.w(TAG, "Failed to eject", e); |
Ben Lin | e7822fb | 2016-06-24 15:21:08 -0700 | [diff] [blame] | 1510 | } |
| 1511 | } |
| 1512 | |
Tomasz Mikolajewski | cbcd394 | 2016-01-28 12:39:25 +0900 | [diff] [blame] | 1513 | /** |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1514 | * Returns metadata associated with the document. The type of metadata returned |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 1515 | * is specific to the document type. For example the data returned for an image |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1516 | * file will likely consist primarily or solely of EXIF metadata. |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1517 | * |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 1518 | * <p>The returned {@link Bundle} will contain zero or more entries depending |
| 1519 | * on the type of data supported by the document provider. |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1520 | * |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 1521 | * <ol> |
Ivan Chiang | b26b09f | 2018-11-28 18:20:32 +0800 | [diff] [blame] | 1522 | * <li>A {@link DocumentsContract#METADATA_TYPES} containing a {@code String[]} value. |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 1523 | * The string array identifies the type or types of metadata returned. Each |
| 1524 | * value in the can be used to access a {@link Bundle} of data |
| 1525 | * containing that type of data. |
| 1526 | * <li>An entry each for each type of returned metadata. Each set of metadata is |
| 1527 | * itself represented as a bundle and accessible via a string key naming |
| 1528 | * the type of data. |
| 1529 | * </ol> |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1530 | * |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 1531 | * <p>Example: |
| 1532 | * <p><pre><code> |
| 1533 | * Bundle metadata = DocumentsContract.getDocumentMetadata(client, imageDocUri, tags); |
| 1534 | * if (metadata.containsKey(DocumentsContract.METADATA_EXIF)) { |
| 1535 | * Bundle exif = metadata.getBundle(DocumentsContract.METADATA_EXIF); |
| 1536 | * int imageLength = exif.getInt(ExifInterface.TAG_IMAGE_LENGTH); |
| 1537 | * } |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1538 | * </code></pre> |
| 1539 | * |
Steve McKay | 17a9ce3 | 2017-07-27 13:37:14 -0700 | [diff] [blame] | 1540 | * @param documentUri a Document URI |
| 1541 | * @return a Bundle of Bundles. |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1542 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1543 | public static @Nullable Bundle getDocumentMetadata(@NonNull ContentResolver content, |
Ivan Chiang | 857a222 | 2019-01-09 15:24:21 +0800 | [diff] [blame] | 1544 | @NonNull Uri documentUri) throws FileNotFoundException { |
| 1545 | Preconditions.checkNotNull(content, "content can not be null"); |
| 1546 | Preconditions.checkNotNull(documentUri, "documentUri can not be null"); |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1547 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1548 | final Bundle in = new Bundle(); |
| 1549 | in.putParcelable(EXTRA_URI, documentUri); |
| 1550 | |
| 1551 | return content.call(documentUri.getAuthority(), |
| 1552 | METHOD_GET_DOCUMENT_METADATA, null, in); |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1553 | } catch (Exception e) { |
| 1554 | Log.w(TAG, "Failed to get document metadata"); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1555 | rethrowIfNecessary(e); |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1556 | return null; |
Julian Mancini | b650515 | 2017-06-27 13:29:09 -0700 | [diff] [blame] | 1557 | } |
| 1558 | } |
| 1559 | |
| 1560 | /** |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 1561 | * Finds the canonical path from the top of the document tree. |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1562 | * |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 1563 | * The {@link Path#getPath()} of the return value contains the document ID |
| 1564 | * of all documents along the path from the top the document tree to the |
| 1565 | * requested document, both inclusive. |
| 1566 | * |
| 1567 | * The {@link Path#getRootId()} of the return value returns {@code null}. |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1568 | * |
| 1569 | * @param treeUri treeUri of the document which path is requested. |
Garfield Tan | b690b4d | 2017-03-01 16:05:23 -0800 | [diff] [blame] | 1570 | * @return the path of the document, or {@code null} if failed. |
Garfield Tan | 3f6b68a | 2016-11-01 14:13:38 -0700 | [diff] [blame] | 1571 | * @see DocumentsProvider#findDocumentPath(String, String) |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1572 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1573 | public static @Nullable Path findDocumentPath(@NonNull ContentResolver content, |
| 1574 | @NonNull Uri treeUri) throws FileNotFoundException { |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1575 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1576 | final Bundle in = new Bundle(); |
| 1577 | in.putParcelable(DocumentsContract.EXTRA_URI, treeUri); |
| 1578 | |
| 1579 | final Bundle out = content.call(treeUri.getAuthority(), |
| 1580 | METHOD_FIND_DOCUMENT_PATH, null, in); |
| 1581 | return out.getParcelable(DocumentsContract.EXTRA_RESULT); |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1582 | } catch (Exception e) { |
| 1583 | Log.w(TAG, "Failed to find path", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1584 | rethrowIfNecessary(e); |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1585 | return null; |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1586 | } |
| 1587 | } |
| 1588 | |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1589 | /** |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1590 | * Creates an intent for obtaining a web link for the specified document. |
| 1591 | * |
| 1592 | * <p>Note, that due to internal limitations, if there is already a web link |
| 1593 | * intent created for the specified document but with different options, |
kopriva | debd4ee | 2018-09-13 10:59:46 -0700 | [diff] [blame] | 1594 | * then it may be overridden. |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1595 | * |
| 1596 | * <p>Providers are required to show confirmation UI for all new permissions granted |
| 1597 | * for the linked document. |
| 1598 | * |
Tomasz Mikolajewski | 463b686 | 2017-03-22 17:34:05 +0900 | [diff] [blame] | 1599 | * <p>If list of recipients is known, then it should be passed in options as |
| 1600 | * {@link Intent#EXTRA_EMAIL} as a list of email addresses. Note, that |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1601 | * this is just a hint for the provider, which can ignore the list. In either |
| 1602 | * case the provider is required to show a UI for letting the user confirm |
| 1603 | * any new permission grants. |
| 1604 | * |
Tomasz Mikolajewski | 463b686 | 2017-03-22 17:34:05 +0900 | [diff] [blame] | 1605 | * <p>Note, that the entire <code>options</code> bundle will be sent to the provider |
| 1606 | * backing the passed <code>uri</code>. Make sure that you trust the provider |
| 1607 | * before passing any sensitive information. |
Tomasz Mikolajewski | f1d5540 | 2017-03-03 15:09:40 +0900 | [diff] [blame] | 1608 | * |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1609 | * <p>Since this API may show a UI, it cannot be called from background. |
| 1610 | * |
| 1611 | * <p>In order to obtain the Web Link use code like this: |
| 1612 | * <pre><code> |
| 1613 | * void onSomethingHappened() { |
| 1614 | * IntentSender sender = DocumentsContract.createWebLinkIntent(<i>...</i>); |
| 1615 | * if (sender != null) { |
| 1616 | * startIntentSenderForResult( |
Tomasz Mikolajewski | f1d5540 | 2017-03-03 15:09:40 +0900 | [diff] [blame] | 1617 | * sender, |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1618 | * WEB_LINK_REQUEST_CODE, |
| 1619 | * null, 0, 0, 0, null); |
| 1620 | * } |
| 1621 | * } |
| 1622 | * |
| 1623 | * <i>(...)</i> |
| 1624 | * |
| 1625 | * void onActivityResult(int requestCode, int resultCode, Intent data) { |
| 1626 | * if (requestCode == WEB_LINK_REQUEST_CODE && resultCode == RESULT_OK) { |
| 1627 | * Uri weblinkUri = data.getData(); |
| 1628 | * <i>...</i> |
| 1629 | * } |
| 1630 | * } |
| 1631 | * </code></pre> |
| 1632 | * |
| 1633 | * @param uri uri for the document to create a link to. |
| 1634 | * @param options Extra information for generating the link. |
| 1635 | * @return an intent sender to obtain the web link, or null if the document |
| 1636 | * is not linkable, or creating the intent sender failed. |
| 1637 | * @see DocumentsProvider#createWebLinkIntent(String, Bundle) |
| 1638 | * @see Intent#EXTRA_EMAIL |
| 1639 | */ |
Jeff Sharkey | a13887f | 2019-02-15 15:53:35 -0700 | [diff] [blame] | 1640 | public static @Nullable IntentSender createWebLinkIntent(@NonNull ContentResolver content, |
| 1641 | @NonNull Uri uri, @Nullable Bundle options) throws FileNotFoundException { |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1642 | try { |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1643 | final Bundle in = new Bundle(); |
| 1644 | in.putParcelable(DocumentsContract.EXTRA_URI, uri); |
| 1645 | |
| 1646 | // Options may be provider specific, so put them in a separate bundle to |
| 1647 | // avoid overriding the Uri. |
| 1648 | if (options != null) { |
| 1649 | in.putBundle(EXTRA_OPTIONS, options); |
| 1650 | } |
| 1651 | |
| 1652 | final Bundle out = content.call(uri.getAuthority(), |
| 1653 | METHOD_CREATE_WEB_LINK_INTENT, null, in); |
| 1654 | return out.getParcelable(DocumentsContract.EXTRA_RESULT); |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1655 | } catch (Exception e) { |
| 1656 | Log.w(TAG, "Failed to create a web link intent", e); |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1657 | rethrowIfNecessary(e); |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1658 | return null; |
Tomasz Mikolajewski | cf31656 | 2016-10-24 15:17:01 +0900 | [diff] [blame] | 1659 | } |
| 1660 | } |
| 1661 | |
| 1662 | /** |
Jeff Sharkey | c1c8f3f | 2013-10-14 14:57:33 -0700 | [diff] [blame] | 1663 | * Open the given image for thumbnail purposes, using any embedded EXIF |
| 1664 | * thumbnail if available, and providing orientation hints from the parent |
| 1665 | * image. |
| 1666 | * |
| 1667 | * @hide |
| 1668 | */ |
| 1669 | public static AssetFileDescriptor openImageThumbnail(File file) throws FileNotFoundException { |
| 1670 | final ParcelFileDescriptor pfd = ParcelFileDescriptor.open( |
| 1671 | file, ParcelFileDescriptor.MODE_READ_ONLY); |
| 1672 | Bundle extras = null; |
| 1673 | |
| 1674 | try { |
| 1675 | final ExifInterface exif = new ExifInterface(file.getAbsolutePath()); |
| 1676 | |
| 1677 | switch (exif.getAttributeInt(ExifInterface.TAG_ORIENTATION, -1)) { |
| 1678 | case ExifInterface.ORIENTATION_ROTATE_90: |
| 1679 | extras = new Bundle(1); |
| 1680 | extras.putInt(EXTRA_ORIENTATION, 90); |
| 1681 | break; |
| 1682 | case ExifInterface.ORIENTATION_ROTATE_180: |
| 1683 | extras = new Bundle(1); |
| 1684 | extras.putInt(EXTRA_ORIENTATION, 180); |
| 1685 | break; |
| 1686 | case ExifInterface.ORIENTATION_ROTATE_270: |
| 1687 | extras = new Bundle(1); |
| 1688 | extras.putInt(EXTRA_ORIENTATION, 270); |
| 1689 | break; |
| 1690 | } |
| 1691 | |
| 1692 | final long[] thumb = exif.getThumbnailRange(); |
| 1693 | if (thumb != null) { |
| 1694 | return new AssetFileDescriptor(pfd, thumb[0], thumb[1], extras); |
| 1695 | } |
| 1696 | } catch (IOException e) { |
| 1697 | } |
| 1698 | |
| 1699 | return new AssetFileDescriptor(pfd, 0, AssetFileDescriptor.UNKNOWN_LENGTH, extras); |
| 1700 | } |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1701 | |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1702 | private static void rethrowIfNecessary(Exception e) throws FileNotFoundException { |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 1703 | // We only want to throw applications targetting O and above |
Jeff Sharkey | e770d22 | 2018-12-07 15:15:59 -0700 | [diff] [blame] | 1704 | if (VMRuntime.getRuntime().getTargetSdkVersion() >= Build.VERSION_CODES.O) { |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 1705 | if (e instanceof ParcelableException) { |
| 1706 | ((ParcelableException) e).maybeRethrow(FileNotFoundException.class); |
Ben Lin | 227e6e8 | 2017-03-13 15:36:13 -0700 | [diff] [blame] | 1707 | } else if (e instanceof RemoteException) { |
Ben Lin | 8ea8200 | 2017-03-08 17:30:16 -0800 | [diff] [blame] | 1708 | ((RemoteException) e).rethrowAsRuntimeException(); |
| 1709 | } else if (e instanceof RuntimeException) { |
| 1710 | throw (RuntimeException) e; |
| 1711 | } |
| 1712 | } |
| 1713 | } |
| 1714 | |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1715 | /** |
Garfield Tan | 0b3cf66 | 2016-10-31 12:59:45 -0700 | [diff] [blame] | 1716 | * Holds a path from a document to a particular document under it. It |
| 1717 | * may also contains the root ID where the path resides. |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1718 | */ |
| 1719 | public static final class Path implements Parcelable { |
| 1720 | |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1721 | private final @Nullable String mRootId; |
| 1722 | private final List<String> mPath; |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1723 | |
| 1724 | /** |
| 1725 | * Creates a Path. |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1726 | * |
| 1727 | * @param rootId the ID of the root. May be null. |
Garfield Tan | 0b3cf66 | 2016-10-31 12:59:45 -0700 | [diff] [blame] | 1728 | * @param path the list of document ID from the parent document at |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1729 | * position 0 to the child document. |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1730 | */ |
Garfield Tan | 5f21480 | 2016-10-26 14:52:46 -0700 | [diff] [blame] | 1731 | public Path(@Nullable String rootId, List<String> path) { |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1732 | checkCollectionNotEmpty(path, "path"); |
| 1733 | checkCollectionElementsNotNull(path, "path"); |
| 1734 | |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1735 | mRootId = rootId; |
| 1736 | mPath = path; |
| 1737 | } |
| 1738 | |
Garfield Tan | 06940e1 | 2016-10-07 16:03:17 -0700 | [diff] [blame] | 1739 | /** |
| 1740 | * Returns the root id or null if the calling package doesn't have |
| 1741 | * permission to access root information. |
| 1742 | */ |
| 1743 | public @Nullable String getRootId() { |
| 1744 | return mRootId; |
| 1745 | } |
| 1746 | |
| 1747 | /** |
| 1748 | * Returns the path. The path is trimmed to the top of tree if |
| 1749 | * calling package doesn't have permission to access those |
| 1750 | * documents. |
| 1751 | */ |
| 1752 | public List<String> getPath() { |
| 1753 | return mPath; |
| 1754 | } |
| 1755 | |
| 1756 | @Override |
| 1757 | public boolean equals(Object o) { |
| 1758 | if (this == o) { |
| 1759 | return true; |
| 1760 | } |
| 1761 | if (o == null || !(o instanceof Path)) { |
| 1762 | return false; |
| 1763 | } |
| 1764 | Path path = (Path) o; |
| 1765 | return Objects.equals(mRootId, path.mRootId) && |
| 1766 | Objects.equals(mPath, path.mPath); |
| 1767 | } |
| 1768 | |
| 1769 | @Override |
| 1770 | public int hashCode() { |
| 1771 | return Objects.hash(mRootId, mPath); |
| 1772 | } |
| 1773 | |
| 1774 | @Override |
| 1775 | public String toString() { |
| 1776 | return new StringBuilder() |
| 1777 | .append("DocumentsContract.Path{") |
| 1778 | .append("rootId=") |
| 1779 | .append(mRootId) |
| 1780 | .append(", path=") |
| 1781 | .append(mPath) |
| 1782 | .append("}") |
| 1783 | .toString(); |
| 1784 | } |
| 1785 | |
Garfield Tan | aba97f3 | 2016-10-06 17:34:19 +0000 | [diff] [blame] | 1786 | @Override |
| 1787 | public void writeToParcel(Parcel dest, int flags) { |
| 1788 | dest.writeString(mRootId); |
| 1789 | dest.writeStringList(mPath); |
| 1790 | } |
| 1791 | |
| 1792 | @Override |
| 1793 | public int describeContents() { |
| 1794 | return 0; |
| 1795 | } |
| 1796 | |
| 1797 | public static final Creator<Path> CREATOR = new Creator<Path>() { |
| 1798 | @Override |
| 1799 | public Path createFromParcel(Parcel in) { |
| 1800 | final String rootId = in.readString(); |
| 1801 | final List<String> path = in.createStringArrayList(); |
| 1802 | return new Path(rootId, path); |
| 1803 | } |
| 1804 | |
| 1805 | @Override |
| 1806 | public Path[] newArray(int size) { |
| 1807 | return new Path[size]; |
| 1808 | } |
| 1809 | }; |
| 1810 | } |
Jeff Sharkey | 9ecfee0 | 2013-04-19 14:05:03 -0700 | [diff] [blame] | 1811 | } |