When a request is made via * a {@link ContentResolver} the system inspects the authority of the given URI and passes the * request to the content provider registered with the authority. The content provider can interpret * the rest of the URI however it wants. The {@link UriMatcher} class is helpful for parsing * URIs.
* *The primary methods that need to be implemented are: *
Data access methods (such as {@link #insert} and * {@link #update}) may be called from many threads at once, and must be thread-safe. * Other methods (such as {@link #onCreate}) are only called from the application * main thread, and must avoid performing lengthy operations. See the method * descriptions for their expected thread behavior.
* *Requests to {@link ContentResolver} are automatically forwarded to the appropriate * ContentProvider instance, so subclasses don't have to worry about the details of * cross-process calls.
* *For more information about using content providers, read the * Content Providers * developer guide.
*/ public abstract class ContentProvider implements ComponentCallbacks2 { private static final String TAG = "ContentProvider"; /* * Note: if you add methods to ContentProvider, you must add similar methods to * MockContentProvider. */ private Context mContext = null; private int mMyUid; private String mReadPermission; private String mWritePermission; private PathPermission[] mPathPermissions; private boolean mExported; private boolean mNoPerms; private final ThreadLocalAt construction time, the object is uninitialized, and most fields and * methods are unavailable. Subclasses should initialize themselves in * {@link #onCreate}, not the constructor. * *
Content providers are created on the application main thread at
* application launch time. The constructor must not perform lengthy
* operations, or application startup will be delayed.
*/
public ContentProvider() {
}
/**
* Constructor just for mocking.
*
* @param context A Context object which should be some mock instance (like the
* instance of {@link android.test.mock.MockContext}).
* @param readPermission The read permision you want this instance should have in the
* test, which is available via {@link #getReadPermission()}.
* @param writePermission The write permission you want this instance should have
* in the test, which is available via {@link #getWritePermission()}.
* @param pathPermissions The PathPermissions you want this instance should have
* in the test, which is available via {@link #getPathPermissions()}.
* @hide
*/
public ContentProvider(
Context context,
String readPermission,
String writePermission,
PathPermission[] pathPermissions) {
mContext = context;
mReadPermission = readPermission;
mWritePermission = writePermission;
mPathPermissions = pathPermissions;
}
/**
* Given an IContentProvider, try to coerce it back to the real
* ContentProvider object if it is running in the local process. This can
* be used if you know you are running in the same process as a provider,
* and want to get direct access to its implementation details. Most
* clients should not nor have a reason to use it.
*
* @param abstractInterface The ContentProvider interface that is to be
* coerced.
* @return If the IContentProvider is non-{@code null} and local, returns its actual
* ContentProvider instance. Otherwise returns {@code null}.
* @hide
*/
public static ContentProvider coerceToLocalContentProvider(
IContentProvider abstractInterface) {
if (abstractInterface instanceof Transport) {
return ((Transport)abstractInterface).getContentProvider();
}
return null;
}
/**
* Binder object that deals with remoting.
*
* @hide
*/
class Transport extends ContentProviderNative {
AppOpsManager mAppOpsManager = null;
int mReadOp = AppOpsManager.OP_NONE;
int mWriteOp = AppOpsManager.OP_NONE;
ContentProvider getContentProvider() {
return ContentProvider.this;
}
@Override
public String getProviderName() {
return getContentProvider().getClass().getName();
}
@Override
public Cursor query(String callingPkg, Uri uri, String[] projection,
String selection, String[] selectionArgs, String sortOrder,
ICancellationSignal cancellationSignal) {
if (enforceReadPermission(callingPkg, uri) != AppOpsManager.MODE_ALLOWED) {
return rejectQuery(uri, projection, selection, selectionArgs, sortOrder,
CancellationSignal.fromTransport(cancellationSignal));
}
final String original = setCallingPackage(callingPkg);
try {
return ContentProvider.this.query(
uri, projection, selection, selectionArgs, sortOrder,
CancellationSignal.fromTransport(cancellationSignal));
} finally {
setCallingPackage(original);
}
}
@Override
public String getType(Uri uri) {
return ContentProvider.this.getType(uri);
}
@Override
public Uri insert(String callingPkg, Uri uri, ContentValues initialValues) {
if (enforceWritePermission(callingPkg, uri) != AppOpsManager.MODE_ALLOWED) {
return rejectInsert(uri, initialValues);
}
final String original = setCallingPackage(callingPkg);
try {
return ContentProvider.this.insert(uri, initialValues);
} finally {
setCallingPackage(original);
}
}
@Override
public int bulkInsert(String callingPkg, Uri uri, ContentValues[] initialValues) {
if (enforceWritePermission(callingPkg, uri) != AppOpsManager.MODE_ALLOWED) {
return 0;
}
final String original = setCallingPackage(callingPkg);
try {
return ContentProvider.this.bulkInsert(uri, initialValues);
} finally {
setCallingPackage(original);
}
}
@Override
public ContentProviderResult[] applyBatch(String callingPkg,
ArrayList
* This will always return {@code null} when processing
* {@link #getType(Uri)} or {@link #getStreamTypes(Uri, String)} requests.
*
* @see Binder#getCallingUid()
* @see Context#grantUriPermission(String, Uri, int)
* @throws SecurityException if the calling package doesn't belong to the
* calling UID.
*/
public final String getCallingPackage() {
final String pkg = mCallingPackage.get();
if (pkg != null) {
mTransport.mAppOpsManager.checkPackage(Binder.getCallingUid(), pkg);
}
return pkg;
}
/**
* 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.
*
* @param permission Name of the permission required for read-only access.
*/
protected final void setReadPermission(String permission) {
mReadPermission = permission;
}
/**
* 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.
*/
public final String getReadPermission() {
return mReadPermission;
}
/**
* 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.
*
* @param permission Name of the permission required for read/write access.
*/
protected final void setWritePermission(String permission) {
mWritePermission = permission;
}
/**
* 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.
*/
public final String getWritePermission() {
return mWritePermission;
}
/**
* 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.
*
* @param permissions Array of path permission descriptions.
*/
protected final void setPathPermissions(PathPermission[] permissions) {
mPathPermissions = permissions;
}
/**
* 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.
*/
public final PathPermission[] getPathPermissions() {
return mPathPermissions;
}
/** @hide */
public final void setAppOps(int readOp, int writeOp) {
if (!mNoPerms) {
mTransport.mReadOp = readOp;
mTransport.mWriteOp = writeOp;
}
}
/** @hide */
public AppOpsManager getAppOpsManager() {
return mTransport.mAppOpsManager;
}
/**
* 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 {@link #query}, {@link #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, {@link 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
* {@link android.database.sqlite.SQLiteOpenHelper#getReadableDatabase} or
* {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase}
* from this method. (Instead, override
* {@link android.database.sqlite.SQLiteOpenHelper#onOpen} to initialize the
* database when it is first opened.)
*
* @return true if the provider was successfully loaded, false otherwise
*/
public abstract boolean onCreate();
/**
* {@inheritDoc}
* 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.)
*/
public void onConfigurationChanged(Configuration newConfig) {
}
/**
* {@inheritDoc}
* 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.
*/
public void onLowMemory() {
}
public void onTrimMemory(int level) {
}
/**
* @hide
* Implementation when a caller has performed a query on the content
* provider, but that call has been rejected for the operation given
* to {@link #setAppOps(int, int)}. The default implementation
* rewrites the selection argument to include a condition
* that is never true (so will always result in an empty cursor)
* and calls through to {@link #query(android.net.Uri, String[], String, String[],
* String, android.os.CancellationSignal)} with that.
*/
public Cursor rejectQuery(Uri uri, String[] projection,
String selection, String[] selectionArgs, String sortOrder,
CancellationSignal cancellationSignal) {
// The read is not allowed... to fake it out, we replace the given
// selection statement with a dummy one that will always be false.
// This way we will get a cursor back that has the correct structure
// but contains no rows.
if (selection == null || selection.isEmpty()) {
selection = "'A' = 'B'";
} else {
selection = "'A' = 'B' AND (" + selection + ")";
}
return query(uri, projection, selection, selectionArgs, sortOrder, cancellationSignal);
}
/**
* Implement this to handle query requests from clients.
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
* Example client call:
*
*
* Example client call:
*
*
* If you implement this method then you must also implement the version of
* {@link #query(Uri, String[], String, String[], String)} that does not take a cancellation
* signal to ensure correct operation on older versions of the Android Framework in
* which the cancellation signal overload was not available.
*
* @param uri The URI to query. This will be the full URI sent by the client;
* if the client is requesting a specific record, the URI will end in a record number
* that the implementation should parse and add to a WHERE or HAVING clause, specifying
* that _id value.
* @param projection The list of columns to put into the cursor. If
* {@code null} all columns are included.
* @param selection A selection criteria to apply when filtering rows.
* If {@code null} then all rows are included.
* @param selectionArgs You may include ?s in selection, which will be replaced by
* the values from selectionArgs, in order that they appear in the selection.
* The values will be bound as Strings.
* @param sortOrder How the rows in the cursor should be sorted.
* If {@code null} then the provider is free to define the sort order.
* @param cancellationSignal A signal to cancel the operation in progress, or {@code null} if none.
* If the operation is canceled, then {@link OperationCanceledException} will be thrown
* when the query is executed.
* @return a Cursor or {@code null}.
*/
public Cursor query(Uri uri, String[] projection,
String selection, String[] selectionArgs, String sortOrder,
CancellationSignal cancellationSignal) {
return query(uri, projection, selection, selectionArgs, sortOrder);
}
/**
* Implement this to handle requests for the MIME type of the data at the
* given URI. The returned MIME type should start with
* Note that there are no permissions needed for an application to
* access this information; if your content provider requires read and/or
* write permissions, or is not exported, all applications can still call
* this method regardless of their access permissions. This allows them
* to retrieve the MIME type for a URI when dispatching intents.
*
* @param uri the URI to query.
* @return a MIME type string, or {@code null} if there is no type.
*/
public abstract String getType(Uri uri);
/**
* Implement this to support canonicalization of URIs that refer to your
* content provider. A canonical URI is one that can be transported across
* devices, backup/restore, and other contexts, and still be able to refer
* to the same data item. Typically this is implemented by adding query
* params to the URI allowing the content provider to verify that an incoming
* canonical URI references the same data as it was originally intended for and,
* if it doesn't, to find that data (if it exists) in the current environment.
*
* For example, if the content provider holds people and a normal URI in it
* is created with a row index into that people database, the cananical representation
* may have an additional query param at the end which specifies the name of the
* person it is intended for. Later calls into the provider with that URI will look
* up the row of that URI's base index and, if it doesn't match or its entry's
* name doesn't match the name in the query param, perform a query on its database
* to find the correct row to operate on. If you implement support for canonical URIs, all incoming calls with
* URIs (including this one) must perform this verification and recovery of any
* canonical URIs they receive. In addition, you must also implement
* {@link #uncanonicalize} to strip the canonicalization of any of these URIs. The default implementation of this method returns null, indicating that
* canonical URIs are not supported. 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 This method returns a ParcelFileDescriptor, which is returned directly
* to the caller. This way large data (such as images and documents) can be
* returned without copying the content.
*
* The returned ParcelFileDescriptor is owned by the caller, so it is
* their responsibility to close it when done. That is, the implementation
* of this method should create a new ParcelFileDescriptor for each call.
*
* If opened with the exclusive "r" or "w" modes, the returned
* ParcelFileDescriptor can be a pipe or socket pair to enable streaming
* of data. Opening with the "rw" or "rwt" modes implies a file on disk that
* supports seeking.
*
* If you need to detect when the returned ParcelFileDescriptor has been
* closed, or if the remote process has crashed or encountered some other
* error, you can use {@link ParcelFileDescriptor#open(File, int,
* android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener)},
* {@link ParcelFileDescriptor#createReliablePipe()}, or
* {@link ParcelFileDescriptor#createReliableSocketPair()}.
*
* For use in Intents, you will want to implement {@link #getType}
* to return the appropriate MIME type for the data returned here with
* the same URI. This will allow intent resolution to automatically determine the data MIME
* type and select the appropriate matching targets as part of its operation. For better interoperability with other applications, it is recommended
* that for any URIs that can be opened, you also support queries on them
* containing at least the columns specified by {@link android.provider.OpenableColumns}.
* You may also want to support other common columns if you have additional meta-data
* to supply, such as {@link android.provider.MediaStore.MediaColumns#DATE_ADDED}
* in {@link android.provider.MediaStore.MediaColumns}. This method returns a ParcelFileDescriptor, which is returned directly
* to the caller. This way large data (such as images and documents) can be
* returned without copying the content.
*
* The returned ParcelFileDescriptor is owned by the caller, so it is
* their responsibility to close it when done. That is, the implementation
* of this method should create a new ParcelFileDescriptor for each call.
*
* If opened with the exclusive "r" or "w" modes, the returned
* ParcelFileDescriptor can be a pipe or socket pair to enable streaming
* of data. Opening with the "rw" or "rwt" modes implies a file on disk that
* supports seeking.
*
* If you need to detect when the returned ParcelFileDescriptor has been
* closed, or if the remote process has crashed or encountered some other
* error, you can use {@link ParcelFileDescriptor#open(File, int,
* android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener)},
* {@link ParcelFileDescriptor#createReliablePipe()}, or
* {@link ParcelFileDescriptor#createReliableSocketPair()}.
*
* For use in Intents, you will want to implement {@link #getType}
* to return the appropriate MIME type for the data returned here with
* the same URI. This will allow intent resolution to automatically determine the data MIME
* type and select the appropriate matching targets as part of its operation. For better interoperability with other applications, it is recommended
* that for any URIs that can be opened, you also support queries on them
* containing at least the columns specified by {@link android.provider.OpenableColumns}.
* You may also want to support other common columns if you have additional meta-data
* to supply, such as {@link android.provider.MediaStore.MediaColumns#DATE_ADDED}
* in {@link android.provider.MediaStore.MediaColumns}. If you implement this, your clients must be able to deal with such
* file slices, either directly with
* {@link ContentResolver#openAssetFileDescriptor}, or by using the higher-level
* {@link ContentResolver#openInputStream ContentResolver.openInputStream}
* or {@link ContentResolver#openOutputStream ContentResolver.openOutputStream}
* methods.
*
* The returned AssetFileDescriptor can be a pipe or socket pair to enable
* streaming of data.
*
* If you are implementing this to return a full file, you
* should create the AssetFileDescriptor with
* {@link AssetFileDescriptor#UNKNOWN_LENGTH} to be compatible with
* applications that cannot handle sub-sections of files. For use in Intents, you will want to implement {@link #getType}
* to return the appropriate MIME type for the data returned here with
* the same URI. This will allow intent resolution to automatically determine the data MIME
* type and select the appropriate matching targets as part of its operation. For better interoperability with other applications, it is recommended
* that for any URIs that can be opened, you also support queries on them
* containing at least the columns specified by {@link android.provider.OpenableColumns}. If you implement this, your clients must be able to deal with such
* file slices, either directly with
* {@link ContentResolver#openAssetFileDescriptor}, or by using the higher-level
* {@link ContentResolver#openInputStream ContentResolver.openInputStream}
* or {@link ContentResolver#openOutputStream ContentResolver.openOutputStream}
* methods.
*
* The returned AssetFileDescriptor can be a pipe or socket pair to enable
* streaming of data.
*
* If you are implementing this to return a full file, you
* should create the AssetFileDescriptor with
* {@link AssetFileDescriptor#UNKNOWN_LENGTH} to be compatible with
* applications that cannot handle sub-sections of files. For use in Intents, you will want to implement {@link #getType}
* to return the appropriate MIME type for the data returned here with
* the same URI. This will allow intent resolution to automatically determine the data MIME
* type and select the appropriate matching targets as part of its operation. For better interoperability with other applications, it is recommended
* that for any URIs that can be opened, you also support queries on them
* containing at least the columns specified by {@link android.provider.OpenableColumns}. The default implementation compares the given mimeType against the
* result of {@link #getType(Uri)} and, if they match, simply calls
* {@link #openAssetFile(Uri, String)}.
*
* See {@link ClipData} for examples of the use and implementation
* of this method.
*
* The returned AssetFileDescriptor can be a pipe or socket pair to enable
* streaming of data.
*
* For better interoperability with other applications, it is recommended
* that for any URIs that can be opened, you also support queries on them
* containing at least the columns specified by {@link android.provider.OpenableColumns}.
* You may also want to support other common columns if you have additional meta-data
* to supply, such as {@link android.provider.MediaStore.MediaColumns#DATE_ADDED}
* in {@link android.provider.MediaStore.MediaColumns}. The default implementation compares the given mimeType against the
* result of {@link #getType(Uri)} and, if they match, simply calls
* {@link #openAssetFile(Uri, String)}.
*
* See {@link ClipData} for examples of the use and implementation
* of this method.
*
* The returned AssetFileDescriptor can be a pipe or socket pair to enable
* streaming of data.
*
* For better interoperability with other applications, it is recommended
* that for any URIs that can be opened, you also support queries on them
* containing at least the columns specified by {@link android.provider.OpenableColumns}.
* You may also want to support other common columns if you have additional meta-data
* to supply, such as {@link android.provider.MediaStore.MediaColumns#DATE_ADDED}
* in {@link android.provider.MediaStore.MediaColumns}. 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.
* 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.
* // Request a specific record.
* Cursor managedCursor = managedQuery(
ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
projection, // Which columns to return.
null, // WHERE clause.
null, // WHERE clause value substitution
People.NAME + " ASC"); // Sort order.
* Example implementation:// SQLiteQueryBuilder is a helper class that creates the
// proper SQL syntax for us.
SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();
// Set the table we're querying.
qBuilder.setTables(DATABASE_TABLE_NAME);
// If the query ends in a specific record number, we're
// being asked for a specific record, so set the
// WHERE clause in our query.
if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
qBuilder.appendWhere("_id=" + uri.getPathLeafId());
}
// Make the query.
Cursor c = qBuilder.query(mDb,
projection,
selection,
selectionArgs,
groupBy,
having,
sortOrder);
c.setNotificationUri(getContext().getContentResolver(), uri);
return c;
*
* @param uri The URI to query. This will be the full URI sent by the client;
* if the client is requesting a specific record, the URI will end in a record number
* that the implementation should parse and add to a WHERE or HAVING clause, specifying
* that _id value.
* @param projection The list of columns to put into the cursor. If
* {@code null} all columns are included.
* @param selection A selection criteria to apply when filtering rows.
* If {@code null} then all rows are included.
* @param selectionArgs You may include ?s in selection, which will be replaced by
* the values from selectionArgs, in order that they appear in the selection.
* The values will be bound as Strings.
* @param sortOrder How the rows in the cursor should be sorted.
* If {@code null} then the provider is free to define the sort order.
* @return a Cursor or {@code null}.
*/
public abstract Cursor query(Uri uri, String[] projection,
String selection, String[] selectionArgs, String sortOrder);
/**
* Implement this to handle query requests from clients with support for cancellation.
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
* // Request a specific record.
* Cursor managedCursor = managedQuery(
ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
projection, // Which columns to return.
null, // WHERE clause.
null, // WHERE clause value substitution
People.NAME + " ASC"); // Sort order.
* Example implementation:// SQLiteQueryBuilder is a helper class that creates the
// proper SQL syntax for us.
SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();
// Set the table we're querying.
qBuilder.setTables(DATABASE_TABLE_NAME);
// If the query ends in a specific record number, we're
// being asked for a specific record, so set the
// WHERE clause in our query.
if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
qBuilder.appendWhere("_id=" + uri.getPathLeafId());
}
// Make the query.
Cursor c = qBuilder.query(mDb,
projection,
selection,
selectionArgs,
groupBy,
having,
sortOrder);
c.setNotificationUri(getContext().getContentResolver(), uri);
return c;
* vnd.android.cursor.item for a single record,
* or vnd.android.cursor.dir/ for multiple items.
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
* content://contacts/people/22 and the implementation is
* responsible for parsing the record number (22) when creating a SQL statement.
*
* @param uri The full URI to query, including a row ID (if a specific record is requested).
* @param selection An optional restriction to apply to rows when deleting.
* @return The number of rows affected.
* @throws SQLException
*/
public abstract int delete(Uri uri, String selection, String[] selectionArgs);
/**
* 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 {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyChange()}
* after updating.
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
* @param uri The URI to query. This can potentially have a record ID if this
* is an update request for a specific record.
* @param values A set of column_name/value pairs to update in the database.
* This must not be {@code null}.
* @param selection An optional filter to match rows to update.
* @return the number of rows affected.
*/
public abstract int update(Uri uri, ContentValues values, String selection,
String[] selectionArgs);
/**
* Override this to handle requests to open a file blob.
* The default implementation always throws {@link FileNotFoundException}.
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
*