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 Transport mTransport = new Transport(); /** * Construct a ContentProvider instance. Content providers must be * declared * in the manifest, accessed with {@link ContentResolver}, and created * automatically by the system, so applications usually do not create * ContentProvider instances directly. * *At 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));
}
return ContentProvider.this.query(uri, projection, selection, selectionArgs, sortOrder,
CancellationSignal.fromTransport(cancellationSignal));
}
@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);
}
return ContentProvider.this.insert(uri, initialValues);
}
@Override
public int bulkInsert(String callingPkg, Uri uri, ContentValues[] initialValues) {
if (enforceWritePermission(callingPkg, uri) != AppOpsManager.MODE_ALLOWED) {
return 0;
}
return ContentProvider.this.bulkInsert(uri, initialValues);
}
@Override
public ContentProviderResult[] applyBatch(String callingPkg,
ArrayList 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);
/**
* @hide
* Implementation when a caller has performed an insert on the content
* provider, but that call has been rejected for the operation given
* to {@link #setAppOps(int, int)}. The default implementation simply
* returns a dummy URI that is the base URI with a 0 path element
* appended.
*/
public Uri rejectInsert(Uri uri, ContentValues values) {
// If not allowed, we need to return some reasonable URI. Maybe the
// content provider should be responsible for this, but for now we
// will just return the base URI with a dummy '0' tagged on to it.
// You shouldn't be able to read if you can't write, anyway, so it
// shouldn't matter much what is returned.
return uri.buildUpon().appendPath("0").build();
}
/**
* Implement this to handle requests to insert a new row.
* As a courtesy, call {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyChange()}
* after inserting.
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
* @param uri The content:// URI of the insertion request. This must not be {@code null}.
* @param values A set of column_name/value pairs to add to the database.
* This must not be {@code null}.
* @return The URI for the newly inserted item.
*/
public abstract Uri insert(Uri uri, ContentValues values);
/**
* Override this to handle requests to insert a set of new rows, or the
* default implementation will iterate over the values and call
* {@link #insert} on each of them.
* As a courtesy, call {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyChange()}
* after inserting.
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
* @param uri The content:// URI of the insertion request.
* @param values An array of sets of column_name/value pairs to add to the database.
* This must not be {@code null}.
* @return The number of values that were inserted.
*/
public int bulkInsert(Uri uri, ContentValues[] values) {
int numValues = values.length;
for (int i = 0; i < numValues; i++) {
insert(uri, values[i]);
}
return numValues;
}
/**
* 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 {@link ContentResolver#notifyChange(android.net.Uri ,android.database.ContentObserver) notifyDelete()}
* 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 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.
*
* 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.
*
* 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 can not 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.
*
* 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.
*
*