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; // Since most Providers have only one authority, we keep both a String and a String[] to improve // performance. private String mAuthority; private String[] mAuthorities; private String mReadPermission; private String mWritePermission; private PathPermission[] mPathPermissions; private boolean mExported; private boolean mNoPerms; private boolean mSingleUser; 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, @Nullable String[] projection,
@Nullable Bundle queryArgs, @Nullable ICancellationSignal cancellationSignal) {
validateIncomingUri(uri);
uri = maybeGetUriWithoutUserId(uri);
if (enforceReadPermission(callingPkg, uri, null) != AppOpsManager.MODE_ALLOWED) {
// The caller has no access to the data, so return an empty cursor with
// the columns in the requested order. The caller may ask for an invalid
// column and we would not catch that but this is not a problem in practice.
// We do not call ContentProvider#query with a modified where clause since
// the implementation is not guaranteed to be backed by a SQL database, hence
// it may not handle properly the tautology where clause we would have created.
if (projection != null) {
return new MatrixCursor(projection, 0);
}
// Null projection means all columns but we have no idea which they are.
// However, the caller may be expecting to access them my index. Hence,
// we have to execute the query as if allowed to get a cursor with the
// columns. We then use the column names to return an empty cursor.
Cursor cursor = ContentProvider.this.query(
uri, projection, queryArgs,
CancellationSignal.fromTransport(cancellationSignal));
if (cursor == null) {
return null;
}
// Return an empty cursor for all columns.
return new MatrixCursor(cursor.getColumnNames(), 0);
}
final String original = setCallingPackage(callingPkg);
try {
return ContentProvider.this.query(
uri, projection, queryArgs,
CancellationSignal.fromTransport(cancellationSignal));
} finally {
setCallingPackage(original);
}
}
@Override
public String getType(Uri uri) {
validateIncomingUri(uri);
uri = maybeGetUriWithoutUserId(uri);
return ContentProvider.this.getType(uri);
}
@Override
public Uri insert(String callingPkg, Uri uri, ContentValues initialValues) {
validateIncomingUri(uri);
int userId = getUserIdFromUri(uri);
uri = maybeGetUriWithoutUserId(uri);
if (enforceWritePermission(callingPkg, uri, null) != AppOpsManager.MODE_ALLOWED) {
return rejectInsert(uri, initialValues);
}
final String original = setCallingPackage(callingPkg);
try {
return maybeAddUserId(ContentProvider.this.insert(uri, initialValues), userId);
} finally {
setCallingPackage(original);
}
}
@Override
public int bulkInsert(String callingPkg, Uri uri, ContentValues[] initialValues) {
validateIncomingUri(uri);
uri = maybeGetUriWithoutUserId(uri);
if (enforceWritePermission(callingPkg, uri, null) != 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 @Nullable String getCallingPackage() {
final String pkg = mCallingPackage.get();
if (pkg != null) {
mTransport.mAppOpsManager.checkPackage(Binder.getCallingUid(), pkg);
}
return pkg;
}
/**
* Change the authorities of the ContentProvider.
* This is normally set for you from its manifest information when the provider is first
* created.
* @hide
* @param authorities the semi-colon separated authorities of the ContentProvider.
*/
protected final void setAuthorities(String authorities) {
if (authorities != null) {
if (authorities.indexOf(';') == -1) {
mAuthority = authorities;
mAuthorities = null;
} else {
mAuthority = null;
mAuthorities = authorities.split(";");
}
}
}
/** @hide */
protected final boolean matchesOurAuthorities(String authority) {
if (mAuthority != null) {
return mAuthority.equals(authority);
}
if (mAuthorities != null) {
int length = mAuthorities.length;
for (int i = 0; i < length; i++) {
if (mAuthorities[i].equals(authority)) return true;
}
}
return false;
}
/**
* 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(@Nullable 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 @Nullable 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(@Nullable 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 @Nullable 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(@Nullable 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 @Nullable 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.)
*/
@Override
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.
*/
@Override
public void onLowMemory() {
}
@Override
public void onTrimMemory(int level) {
}
/**
* Implement this to handle query requests from clients.
*
* Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher should override
* {@link #query(Uri, String[], Bundle, CancellationSignal)} and provide a stub
* implementation of this method.
*
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
* Example client call:
*
* Apps targeting {@link android.os.Build.VERSION_CODES#O} or higher should override
* {@link #query(Uri, String[], Bundle, CancellationSignal)} instead of this method.
*
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
* 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 @Nullable Cursor query(@NonNull Uri uri, @Nullable String[] projection,
@Nullable String selection, @Nullable String[] selectionArgs,
@Nullable String sortOrder, @Nullable CancellationSignal cancellationSignal) {
return query(uri, projection, selection, selectionArgs, sortOrder);
}
/**
* Implement this to handle query requests where the arguments are packed into a {@link Bundle}.
* Arguments may include traditional SQL style query arguments. When present these
* should be handled according to the contract established in
* {@link #query(Uri, String[], String, String[], String, CancellationSignal).
*
* Traditional SQL arguments can be found in the bundle using the following keys:
* This method can be called from multiple threads, as described in
* Processes
* and Threads.
*
*
* Example client call:
*
*
* @see #query(Uri, String[], String, String[], String, CancellationSignal) for
* implementation details.
*
* @param uri The URI to query. This will be the full URI sent by the client.
* @param projection The list of columns to put into the cursor.
* If {@code null} provide a default set of columns.
* @param queryArgs A Bundle containing all additional information necessary for the query.
* Values in the Bundle may include SQL style arguments.
* @param cancellationSignal A signal to cancel the operation in progress,
* or {@code null}.
* @return a Cursor or {@code null}.
*/
public @Nullable Cursor query(@NonNull Uri uri, @Nullable String[] projection,
@Nullable Bundle queryArgs, @Nullable CancellationSignal cancellationSignal) {
queryArgs = queryArgs != null ? queryArgs : Bundle.EMPTY;
// if client doesn't supply an SQL sort order argument, attempt to build one from
// QUERY_ARG_SORT* arguments.
String sortClause = queryArgs.getString(ContentResolver.QUERY_ARG_SQL_SORT_ORDER);
if (sortClause == null && queryArgs.containsKey(ContentResolver.QUERY_ARG_SORT_COLUMNS)) {
sortClause = ContentResolver.createSqlSortClause(queryArgs);
}
return query(
uri,
projection,
queryArgs.getString(ContentResolver.QUERY_ARG_SQL_SELECTION),
queryArgs.getStringArray(ContentResolver.QUERY_ARG_SQL_SELECTION_ARGS),
sortClause,
cancellationSignal);
}
/**
* 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 @Nullable String getType(@NonNull 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.
* This allows clients to request an explicit refresh of content identified by {@code 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 {@link ContentResolver#notifyChange(Uri, android.database.ContentObserver)}
* notifications when content changes.
*
* @param uri The Uri identifying the data to refresh.
* @param args Additional options from the client. The definitions of these are specific to the
* content provider being called.
* @param cancellationSignal A signal to cancel the operation in progress, or {@code null} if
* none. For example, if you called refresh on a particular uri, you should call
* {@link CancellationSignal#throwIfCanceled()} to check whether the client has
* canceled the refresh request.
* @return true if the provider actually tried refreshing.
*/
public boolean refresh(Uri uri, @Nullable Bundle args,
@Nullable CancellationSignal cancellationSignal) {
return false;
}
/**
* @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 @Nullable Uri insert(@NonNull Uri uri, @Nullable 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(@NonNull Uri uri, @NonNull 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) 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 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()}.
*
* If you need to return a large file that isn't backed by a real file on
* disk, such as a file on a network share or cloud storage service,
* consider using
* {@link StorageManager#openProxyFileDescriptor(int, android.os.ProxyFileDescriptorCallback, android.os.Handler)}
* which will let you to stream the content on-demand.
*
* 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 @Nullable Cursor query(@NonNull Uri uri, @Nullable String[] projection,
@Nullable String selection, @Nullable String[] selectionArgs,
@Nullable String sortOrder);
/**
* Implement this to handle query requests from clients with support for cancellation.
*
* // 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;
* // Request 20 records starting at row index 30.
Bundle queryArgs = new Bundle();
queryArgs.putInt(ContentResolver.QUERY_ARG_OFFSET, 30);
queryArgs.putInt(ContentResolver.QUERY_ARG_LIMIT, 20);
Cursor cursor = getContentResolver().query(
contentUri, // Content Uri is specific to individual content providers.
projection, // String[] describing which columns to return.
queryArgs, // Query arguments.
null); // Cancellation signal.
*
* Example implementation:
int recordsetSize = 0x1000; // Actual value is implementation specific.
queryArgs = queryArgs != null ? queryArgs : Bundle.EMPTY; // ensure queryArgs is non-null
int offset = queryArgs.getInt(ContentResolver.QUERY_ARG_OFFSET, 0);
int limit = queryArgs.getInt(ContentResolver.QUERY_ARG_LIMIT, Integer.MIN_VALUE);
MatrixCursor c = new MatrixCursor(PROJECTION, limit);
// Calculate the number of items to include in the cursor.
int numItems = MathUtils.constrain(recordsetSize - offset, 0, limit);
// Build the paged result set....
for (int i = offset; i < offset + numItems; i++) {
// populate row from your data.
}
Bundle extras = new Bundle();
c.setExtras(extras);
// Any QUERY_ARG_* key may be included if honored.
// In an actual implementation, include only keys that are both present in queryArgs
// and reflected in the Cursor output. For example, if QUERY_ARG_OFFSET were included
// in queryArgs, but was ignored because it contained an invalid value (like –273),
// then QUERY_ARG_OFFSET should be omitted.
extras.putStringArray(ContentResolver.EXTRA_HONORED_ARGS, new String[] {
ContentResolver.QUERY_ARG_OFFSET,
ContentResolver.QUERY_ARG_LIMIT
});
extras.putInt(ContentResolver.EXTRA_TOTAL_COUNT, recordsetSize);
cursor.setNotificationUri(getContext().getContentResolver(), uri);
return cursor;
* 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(@NonNull Uri uri, @Nullable String selection,
@Nullable 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(@NonNull Uri uri, @Nullable ContentValues values,
@Nullable String selection, @Nullable 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.
*
*