DocumentsProvider

Kotlin |Java

abstract class DocumentsProvider : ContentProvider

kotlin.Any
↳	android.content.ContentProvider
	↳	android.provider.DocumentsProvider

Base class for a document provider. A document provider offers read and write access to durable files, such as files stored on a local disk, or files in a cloud storage service. To create a document provider, extend this class, implement the abstract methods, and add it to your manifest like this:

<manifest>
     ...
     <application>
         ...
         <provider
             android:name="com.example.MyCloudProvider"
             android:authorities="com.example.mycloudprovider"
             android:exported="true"
             android:grantUriPermissions="true"
             android:permission="android.permission.MANAGE_DOCUMENTS"
             android:enabled="@bool/isAtLeastKitKat">
             <intent-filter>
                 <action android:name="android.content.action.DOCUMENTS_PROVIDER" />
             </intent-filter>
         </provider>
         ...
     </application>
 </manifest>

When defining your provider, you must protect it with android.Manifest.permission#MANAGE_DOCUMENTS, which is a permission only the system can obtain. Applications cannot use a documents provider directly; they must go through Intent.ACTION_OPEN_DOCUMENT or Intent.ACTION_CREATE_DOCUMENT which requires a user to actively navigate and select documents. When a user selects documents through that UI, the system issues narrow URI permission grants to the requesting application.

Documents

A document can be either an openable stream (with a specific MIME type), or a directory containing additional documents (with the Document.MIME_TYPE_DIR MIME type). Each directory represents the top of a subtree containing zero or more documents, which can recursively contain even more documents and directories.

Each document can have different capabilities, as described by Document.COLUMN_FLAGS. For example, if a document can be represented as a thumbnail, your provider can set Document.FLAG_SUPPORTS_THUMBNAIL and implement openDocumentThumbnail(java.lang.String,android.graphics.Point,android.os.CancellationSignal) to return that thumbnail.

Each document under a provider is uniquely referenced by its Document.COLUMN_DOCUMENT_ID, which must not change once returned. A single document can be included in multiple directories when responding to queryChildDocuments(java.lang.String,java.lang.String[],java.lang.String). For example, a provider might surface a single photo in multiple locations: once in a directory of geographic locations, and again in a directory of dates.

Roots

All documents are surfaced through one or more "roots." Each root represents the top of a document tree that a user can navigate. For example, a root could represent an account or a physical storage device. Similar to documents, each root can have capabilities expressed through Root.COLUMN_FLAGS.

Summary

Inherited constants

From class ComponentCallbacks2

`Int`	`TRIM_MEMORY_BACKGROUND` Level for `onTrimMemory(int)`: the process has gone on to the LRU list. This is a good opportunity to clean up resources that can efficiently and quickly be re-built if the user returns to the app.
`Int`	`TRIM_MEMORY_COMPLETE` Level for `onTrimMemory(int)`: the process is nearing the end of the background LRU list, and if more memory isn't found soon it will be killed.
`Int`	`TRIM_MEMORY_MODERATE` Level for `onTrimMemory(int)`: the process is around the middle of the background LRU list; freeing memory can help the system keep other processes running later in the list for better overall performance.
`Int`	`TRIM_MEMORY_RUNNING_CRITICAL` Level for `onTrimMemory(int)`: the process is not an expendable background process, but the device is running extremely low on memory and is about to not be able to keep any background processes running. Your running process should free up as many non-critical resources as it can to allow that memory to be used elsewhere. The next thing that will happen after this is `onLowMemory()` called to report that nothing at all can be kept in the background, a situation that can start to notably impact the user.
`Int`	`TRIM_MEMORY_RUNNING_LOW` Level for `onTrimMemory(int)`: the process is not an expendable background process, but the device is running low on memory. Your running process should free up unneeded resources to allow that memory to be used elsewhere.
`Int`	`TRIM_MEMORY_RUNNING_MODERATE` Level for `onTrimMemory(int)`: the process is not an expendable background process, but the device is running moderately low on memory. Your running process may want to release some unneeded resources for use elsewhere.
`Int`	`TRIM_MEMORY_UI_HIDDEN` Level for `onTrimMemory(int)`: the process had been showing a user interface, and is no longer doing so. Large allocations with the UI should be released at this point to allow memory to be better managed.

Public constructors
`DocumentsProvider()`

Public methods
open Unit	`attachInfo(context: Context!, info: ProviderInfo!)` Implementation is provided by the parent class.
open Bundle?	`call(method: String, arg: String?, extras: Bundle?)` Implementation is provided by the parent class.
open Uri?	`canonicalize(uri: Uri)` Implementation is provided by the parent class.
open String!	`copyDocument(sourceDocumentId: String!, targetParentDocumentId: String!)` Copy the requested document or a document tree.
open String!	`createDocument(parentDocumentId: String!, mimeType: String!, displayName: String!)` Create a new document and return its newly generated `Document.COLUMN_DOCUMENT_ID`.
open IntentSender!	`createWebLinkIntent(documentId: String!, options: Bundle?)` Creates an intent sender for a web link, if the document is web linkable.
Int	`delete(uri: Uri, selection: String?, selectionArgs: Array<String!>?)` Implementation is provided by the parent class.
open Unit	`deleteDocument(documentId: String!)` Delete the requested document.
open Unit	`ejectRoot(rootId: String!)` Ejects the root.
open DocumentsContract.Path!	`findDocumentPath(parentDocumentId: String?, childDocumentId: String!)` Finds the canonical path for the requested document.
open Bundle?	`getDocumentMetadata(documentId: String)` Returns metadata associated with the document.
open Array<String!>!	`getDocumentStreamTypes(documentId: String!, mimeTypeFilter: String!)` Return a list of streamable MIME types matching the filter, which can be passed to `openTypedDocument(java.lang.String,java.lang.String,android.os.Bundle,android.os.CancellationSignal)`.
open String!	`getDocumentType(documentId: String!)` Return concrete MIME type of the requested document.
open Array<String!>?	`getStreamTypes(uri: Uri, mimeTypeFilter: String)` Called by a client to determine the types of data streams that this content provider support for the given URI.
String?	`getType(uri: Uri)` Implementation is provided by the parent class.
String?	`getTypeAnonymous(uri: Uri)` An unrestricted version of getType, which does not reveal sensitive information
Uri?	`insert(uri: Uri, values: ContentValues?)` Implementation is provided by the parent class.
open Boolean	`isChildDocument(parentDocumentId: String!, documentId: String!)` Test if a document is descendant (child, grandchild, etc) from the given parent.
open String!	`moveDocument(sourceDocumentId: String!, sourceParentDocumentId: String!, targetParentDocumentId: String!)` Move the requested document or a document tree.
AssetFileDescriptor?	`openAssetFile(uri: Uri, mode: String)` Implementation is provided by the parent class.
AssetFileDescriptor?	`openAssetFile(uri: Uri, mode: String, signal: CancellationSignal?)` Implementation is provided by the parent class.
abstract ParcelFileDescriptor!	`openDocument(documentId: String!, mode: String!, signal: CancellationSignal?)` Open and return the requested document.
open AssetFileDescriptor!	`openDocumentThumbnail(documentId: String!, sizeHint: Point!, signal: CancellationSignal!)` Open and return a thumbnail of the requested document.
ParcelFileDescriptor?	`openFile(uri: Uri, mode: String)` Implementation is provided by the parent class.
ParcelFileDescriptor?	`openFile(uri: Uri, mode: String, signal: CancellationSignal?)` Implementation is provided by the parent class.
AssetFileDescriptor?	`openTypedAssetFile(uri: Uri, mimeTypeFilter: String, opts: Bundle?)` Implementation is provided by the parent class.
AssetFileDescriptor?	`openTypedAssetFile(uri: Uri, mimeTypeFilter: String, opts: Bundle?, signal: CancellationSignal?)` Implementation is provided by the parent class.
open AssetFileDescriptor!	`openTypedDocument(documentId: String!, mimeTypeFilter: String!, opts: Bundle!, signal: CancellationSignal!)` Open and return the document in a format matching the specified MIME type filter.
Cursor?	`query(uri: Uri, projection: Array<String!>?, queryArgs: Bundle?, cancellationSignal: CancellationSignal?)` Implementation is provided by the parent class.
Cursor?	`query(uri: Uri, projection: Array<String!>?, selection: String?, selectionArgs: Array<String!>?, sortOrder: String?)`
open Cursor?	`query(uri: Uri, projection: Array<String!>?, selection: String?, selectionArgs: Array<String!>?, sortOrder: String?, cancellationSignal: CancellationSignal?)` WARNING: Sub-classes should not override this method.
open Cursor!	`queryChildDocuments(parentDocumentId: String!, projection: Array<String!>?, queryArgs: Bundle?)` Override this method to return the children documents contained in the requested directory.
abstract Cursor!	`queryChildDocuments(parentDocumentId: String!, projection: Array<String!>!, sortOrder: String!)` Return the children documents contained in the requested directory.
abstract Cursor!	`queryDocument(documentId: String!, projection: Array<String!>!)` Return metadata for the single requested document.
open Cursor!	`queryRecentDocuments(rootId: String!, projection: Array<String!>!)` Return recently modified documents under the requested root.
open Cursor?	`queryRecentDocuments(rootId: String, projection: Array<String!>?, queryArgs: Bundle?, signal: CancellationSignal?)` Return recently modified documents under the requested root.
abstract Cursor!	`queryRoots(projection: Array<String!>!)` Return all roots currently provided.
open Cursor!	`querySearchDocuments(rootId: String!, query: String!, projection: Array<String!>!)` Return documents that match the given query under the requested root.
open Cursor?	`querySearchDocuments(rootId: String, projection: Array<String!>?, queryArgs: Bundle)` Return documents that match the given query under the requested root.
open Unit	`removeDocument(documentId: String!, parentDocumentId: String!)` Removes the requested document or a document tree.
open String!	`renameDocument(documentId: String!, displayName: String!)` Rename an existing document.
Unit	`revokeDocumentPermission(documentId: String!)` Revoke any active permission grants for the given `Document.COLUMN_DOCUMENT_ID`, usually called when a document becomes invalid.
Int	`update(uri: Uri, values: ContentValues?, selection: String?, selectionArgs: Array<String!>?)` Implementation is provided by the parent class.

Inherited functions

From class ContentProvider

`Array<ContentProviderResult!>`	`applyBatch(authority: String, operations: ArrayList<ContentProviderOperation!>)` Override this to handle requests to perform a batch of operations, or the default implementation will iterate over the operations and call `ContentProviderOperation.apply` on each of them. If all calls to `ContentProviderOperation.apply` succeed then a `ContentProviderResult` array with as many elements as there were operations will be returned. If any of the calls fail, it is up to the implementation how many of the others take effect. This method can be called from multiple threads, as described in Processes and Threads.
`Array<ContentProviderResult!>`	`applyBatch(operations: ArrayList<ContentProviderOperation!>)`
`Int`	`bulkInsert(uri: Uri, values: Array<ContentValues!>)` Override this to handle requests to insert a set of new rows, or the default implementation will iterate over the values and call #insert on each of them. As a courtesy, call `notifyChange()` after inserting. This method can be called from multiple threads, as described in Processes and Threads.
`Bundle?`	`call(authority: String, method: String, arg: String?, extras: Bundle?)` Call a provider-defined method. This can be used to implement interfaces that are cheaper and/or unnatural for a table-like model. WARNING: The framework does no permission checking on this entry into the content provider besides the basic ability for the application to get access to the provider at all. For example, it has no idea whether the call being executed may read or write data in the provider, so can't enforce those individual permissions. Any implementation of this method must do its own permission checks on incoming calls to make sure they are allowed.
`ContentProvider.CallingIdentity`	`clearCallingIdentity()` Reset the identity of the incoming IPC on the current thread. Internally this calls `Binder.clearCallingIdentity()` and also clears any value stored in `getCallingPackage()`.
`Int`	`delete(uri: Uri, extras: Bundle?)` Implement this to handle requests to delete one or more rows. The implementation should apply the selection clause when performing deletion, allowing the operation to affect multiple rows in a directory. As a courtesy, call `notifyChange()` after deleting. This method can be called from multiple threads, as described in Processes and Threads. The implementation is responsible for parsing out a row ID at the end of the URI, if a specific row is being deleted. That is, the client would pass in `content://contacts/people/22` and the implementation is responsible for parsing the record number (22) when creating a SQL statement.
`Unit`	`dump(fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!)` Print the Provider's state into the given stream. This gets invoked if you run "adb shell dumpsys activity provider <provider_component_name>".
`AttributionSource?`	`getCallingAttributionSource()` Gets the attribution source of the calling app. If you want to attribute the data access to the calling app you can create an attribution context via `android.content.Context#createContext(ContextParams)` and passing this identity to `ContextParams.Builder.setNextAttributionSource(`.
`String?`	`getCallingAttributionTag()` Return the attribution tag of the caller that initiated the request being processed on the current thread. Returns `null` if not currently processing a request of the request is for the default attribution. This will always return `null` when processing `getTypeAnonymous(android.net.Uri)` requests For `getType(android.net.Uri)` requests, this will be only available for cases, where the caller can be identified. See `getTypeAnonymous(android.net.Uri)`
`String?`	`getCallingPackage()` Return the package name of the caller that initiated the request being processed on the current thread. The returned package will have been verified to belong to the calling UID. Returns `null` if not currently processing a request. This will always return `null` when processing `getTypeAnonymous(android.net.Uri)` requests For `getType(android.net.Uri)` requests, this will be only available for cases, where the caller can be identified. See `getTypeAnonymous(android.net.Uri)`
`String?`	`getCallingPackageUnchecked()` Return the package name of the caller that initiated the request being processed on the current thread. The returned package will have not been verified to belong to the calling UID. Returns `null` if not currently processing a request. This will always return `null` when processing `getTypeAnonymous(android.net.Uri)` requests For `getType(android.net.Uri)` requests, this will be only available for cases, where the caller can be identified. See `getTypeAnonymous(android.net.Uri)`
`Context?`	`getContext()` Retrieves the Context this provider is running in. Only available once `onCreate` has been called -- this will return `null` in the constructor.
`Array<PathPermission!>?`	`getPathPermissions()` Return the path-based permissions required for read and/or write access to this content provider. This method can be called from multiple threads, as described in Processes and Threads.
`String?`	`getReadPermission()` Return the name of the permission required for read-only access to this content provider. This method can be called from multiple threads, as described in Processes and Threads.
`String?`	`getWritePermission()` Return the name of the permission required for read/write access to this content provider. This method can be called from multiple threads, as described in Processes and Threads.
`Uri?`	`insert(uri: Uri, values: ContentValues?, extras: Bundle?)` Implement this to handle requests to insert a new row. As a courtesy, call `notifyChange()` after inserting. This method can be called from multiple threads, as described in Processes and Threads.
`Boolean`	`isTemporary()` Returns true if this instance is a temporary content provider.
`Unit`	`onCallingPackageChanged()` Called whenever the value of `getCallingPackage()` changes, giving the provider an opportunity to invalidate any security related caching it may be performing. This typically happens when a `ContentProvider` makes a nested call back into itself when already processing a call from a remote process.
`Unit`	`onConfigurationChanged(newConfig: Configuration)` Called by the system when the device configuration changes while your component is running. Note that, unlike activities, other components are never restarted when a configuration changes: they must always deal with the results of the change, such as by re-retrieving resources. At the time that this function has been called, your Resources object will have been updated to return resource values matching the new configuration. For more information, read Handling Runtime Changes. This method is always called on the application main thread, and must not perform lengthy operations. The default content provider implementation does nothing. Override this method to take appropriate action. (Content providers do not usually care about things like screen orientation, but may want to know about locale changes.)
`Boolean`	`onCreate()` Implement this to initialize your content provider on startup. This method is called for all registered content providers on the application main thread at application launch time. It must not perform lengthy operations, or application startup will be delayed. You should defer nontrivial initialization (such as opening, upgrading, and scanning databases) until the content provider is used (via #query, #insert, etc). Deferred initialization keeps application startup fast, avoids unnecessary work if the provider turns out not to be needed, and stops database errors (such as a full disk) from halting application launch. If you use SQLite, `android.database.sqlite.SQLiteOpenHelper` is a helpful utility class that makes it easy to manage databases, and will automatically defer opening until first use. If you do use SQLiteOpenHelper, make sure to avoid calling `android.database.sqlite.SQLiteOpenHelper#getReadableDatabase` or `android.database.sqlite.SQLiteOpenHelper#getWritableDatabase` from this method. (Instead, override `android.database.sqlite.SQLiteOpenHelper#onOpen` to initialize the database when it is first opened.)
`Unit`	`onLowMemory()` This is called when the overall system is running low on memory, and actively running processes should trim their memory usage. While the exact point at which this will be called is not defined, generally it will happen when all background process have been killed. That is, before reaching the point of killing processes hosting service and foreground UI that we would like to avoid killing. This method is always called on the application main thread, and must not perform lengthy operations. The default content provider implementation does nothing. Subclasses may override this method to take appropriate action.
`Unit`	`onTrimMemory(level: Int)`
`ParcelFileDescriptor`	`openFileHelper(uri: Uri, mode: String)` Convenience for subclasses that wish to implement #openFile by looking up a column named "_data" at the given URI.
`ParcelFileDescriptor`	`openPipeHelper(uri: Uri, mimeType: String, opts: Bundle?, args: T?, func: ContentProvider.PipeDataWriter<T>)` A helper function for implementing #openTypedAssetFile, for creating a data pipe and background thread allowing you to stream generated data back to the client. This function returns a new ParcelFileDescriptor that should be returned to the caller (the caller is responsible for closing it).
`Boolean`	`refresh(uri: Uri!, extras: Bundle?, cancellationSignal: CancellationSignal?)` Implement this to support refresh of content identified by `uri`. By default, this method returns false; providers who wish to implement this should return true to signal the client that the provider has tried refreshing with its own implementation. This allows clients to request an explicit refresh of content identified by `uri`. Client code should only invoke this method when there is a strong indication (such as a user initiated pull to refresh gesture) that the content is stale. Remember to send `ContentResolver.notifyChange(Uri, android.database.ContentObserver)` notifications when content changes.
`Context`	`requireContext()` Retrieves a Non-Nullable Context this provider is running in, this is intended to be called after `onCreate`. When called before context was created, an IllegalStateException will be thrown. Note A provider must be declared in the manifest and created automatically by the system, and context is only available after `onCreate` is called.
`Unit`	`restoreCallingIdentity(identity: ContentProvider.CallingIdentity)` Restore the identity of the incoming IPC on the current thread back to a previously identity that was returned by `clearCallingIdentity`. Internally this calls `Binder.restoreCallingIdentity(long)` and also restores any value stored in `getCallingPackage()`.
`Unit`	`setPathPermissions(permissions: Array<PathPermission!>?)` Change the path-based permission required to read and/or write data in the content provider. This is normally set for you from its manifest information when the provider is first created.
`Unit`	`setReadPermission(permission: String?)` Change the permission required to read data from the content provider. This is normally set for you from its manifest information when the provider is first created.
`Unit`	`setWritePermission(permission: String?)` Change the permission required to read and write data in the content provider. This is normally set for you from its manifest information when the provider is first created.
`Unit`	`shutdown()` Implement this to shut down the ContentProvider instance. You can then invoke this method in unit tests. Android normally handles ContentProvider startup and shutdown automatically. You do not need to start up or shut down a ContentProvider. When you invoke a test method on a ContentProvider, however, a ContentProvider instance is started and keeps running after the test finishes, even if a succeeding test instantiates another ContentProvider. A conflict develops because the two instances are usually running against the same underlying data source (for example, an sqlite database). Implementing shutDown() avoids this conflict by providing a way to terminate the ContentProvider. This method can also prevent memory leaks from multiple instantiations of the ContentProvider, and it can ensure unit test isolation by allowing you to completely clean up the test fixture before moving on to the next test.
`Uri?`	`uncanonicalize(url: Uri)` Remove canonicalization from canonical URIs previously returned by `canonicalize`. For example, if your implementation is to add a query param to canonicalize a URI, this method can simply trip any query params on the URI. The default implementation always returns the same url that was passed in.
`Int`	`update(uri: Uri, values: ContentValues?, extras: Bundle?)` Implement this to handle requests to update one or more rows. The implementation should update all rows matching the selection to set the columns according to the provided values map. As a courtesy, call `notifyChange()` after updating. This method can be called from multiple threads, as described in Processes and Threads.

From class ComponentCallbacks

Unit

onConfigurationChanged(newConfig: Configuration)

Called by the system when the device configuration changes while your component is running. Note that, unlike activities, other components are never restarted when a configuration changes: they must always deal with the results of the change, such as by re-retrieving resources.

At the time that this function has been called, your Resources object will have been updated to return resource values matching the new configuration.

For more information, read Handling Runtime Changes.

Unit

onLowMemory()

This is called when the overall system is running low on memory, and actively running processes should trim their memory usage. While the exact point at which this will be called is not defined, generally it will happen when all background process have been killed. That is, before reaching the point of killing processes hosting service and foreground UI that we would like to avoid killing.

Public constructors