ContentProviderpublic abstract class ContentProvider extends Object implements ComponentCallbacks2| Content providers are one of the primary building blocks of Android applications, providing
content to applications. They encapsulate data and provide it to applications through the single
{@link ContentResolver} interface. A content provider is only required if you need to share
data between multiple applications. For example, the contacts data is used by multiple
applications and must be stored in a content provider. If you don't need to share data amongst
multiple applications you can use a database directly via
{@link android.database.sqlite.SQLiteDatabase}.
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:
- {@link #onCreate} which is called to initialize the provider
- {@link #query} which returns data to the caller
- {@link #insert} which inserts new data into the content provider
- {@link #update} which updates existing data in the content provider
- {@link #delete} which deletes data from the content provider
- {@link #getType} which returns the MIME type of data in the content provider
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.
Developer Guides
For more information about using content providers, read the
Content Providers
developer guide. |
| Fields Summary |
|---|
| private static final String | TAG | | private Context | mContext | | private int | mMyUid | | private String | mAuthority | | private String[] | mAuthorities | | private String | mReadPermission | | private String | mWritePermission | | private android.content.pm.PathPermission[] | mPathPermissions | | private boolean | mExported | | private boolean | mNoPerms | | private boolean | mSingleUser | | private final ThreadLocal | mCallingPackage | | private Transport | mTransport |
| Constructors Summary |
|---|
public ContentProvider()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(Context context, String readPermission, String writePermission, android.content.pm.PathPermission[] pathPermissions)Constructor just for mocking.
mContext = context;
mReadPermission = readPermission;
mWritePermission = writePermission;
mPathPermissions = pathPermissions;
|
| Methods Summary |
|---|
| public ContentProviderResult[] | applyBatch(java.util.ArrayList operations)Override this to handle requests to perform a batch of operations, or the
default implementation will iterate over the operations and call
{@link ContentProviderOperation#apply} on each of them.
If all calls to {@link ContentProviderOperation#apply} succeed
then a {@link 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.
final int numOperations = operations.size();
final ContentProviderResult[] results = new ContentProviderResult[numOperations];
for (int i = 0; i < numOperations; i++) {
results[i] = operations.get(i).apply(this, results, i);
}
return results;
| | public void | attachInfo(Context context, android.content.pm.ProviderInfo info)After being instantiated, this is called to tell the content provider
about itself.
attachInfo(context, info, false);
| | private void | attachInfo(Context context, android.content.pm.ProviderInfo info, boolean testing)
mNoPerms = testing;
/*
* Only allow it to be set once, so after the content service gives
* this to us clients can't change it.
*/
if (mContext == null) {
mContext = context;
if (context != null) {
mTransport.mAppOpsManager = (AppOpsManager) context.getSystemService(
Context.APP_OPS_SERVICE);
}
mMyUid = Process.myUid();
if (info != null) {
setReadPermission(info.readPermission);
setWritePermission(info.writePermission);
setPathPermissions(info.pathPermissions);
mExported = info.exported;
mSingleUser = (info.flags & ProviderInfo.FLAG_SINGLE_USER) != 0;
setAuthorities(info.authority);
}
ContentProvider.this.onCreate();
}
| | public void | attachInfoForTesting(Context context, android.content.pm.ProviderInfo info)Like {@link #attachInfo(Context, android.content.pm.ProviderInfo)}, but for use
when directly instantiating the provider for testing.
attachInfo(context, info, true);
| | public int | bulkInsert(android.net.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.
int numValues = values.length;
for (int i = 0; i < numValues; i++) {
insert(uri, values[i]);
}
return numValues;
| | public android.os.Bundle | call(java.lang.String method, java.lang.String arg, android.os.Bundle extras)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.
return null;
| | public android.net.Uri | canonicalize(android.net.Uri url)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.
return null;
| | boolean | checkUser(int pid, int uid, Context context)
return UserHandle.getUserId(uid) == context.getUserId()
|| mSingleUser
|| context.checkPermission(INTERACT_ACROSS_USERS, pid, uid)
== PERMISSION_GRANTED;
| | public static android.content.ContentProvider | coerceToLocalContentProvider(IContentProvider abstractInterface)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.
if (abstractInterface instanceof Transport) {
return ((Transport)abstractInterface).getContentProvider();
}
return null;
| | public abstract int | delete(android.net.Uri uri, java.lang.String selection, java.lang.String[] selectionArgs)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 content://contacts/people/22 and the implementation is
responsible for parsing the record number (22) when creating a SQL statement.
| | public void | dump(java.io.FileDescriptor fd, java.io.PrintWriter writer, java.lang.String[] args)Print the Provider's state into the given stream. This gets invoked if
you run "adb shell dumpsys activity provider <provider_component_name>".
writer.println("nothing to dump");
| | protected void | enforceReadPermissionInner(android.net.Uri uri, android.os.IBinder callerToken){@hide}
final Context context = getContext();
final int pid = Binder.getCallingPid();
final int uid = Binder.getCallingUid();
String missingPerm = null;
if (UserHandle.isSameApp(uid, mMyUid)) {
return;
}
if (mExported && checkUser(pid, uid, context)) {
final String componentPerm = getReadPermission();
if (componentPerm != null) {
if (context.checkPermission(componentPerm, pid, uid, callerToken)
== PERMISSION_GRANTED) {
return;
} else {
missingPerm = componentPerm;
}
}
// track if unprotected read is allowed; any denied
// <path-permission> below removes this ability
boolean allowDefaultRead = (componentPerm == null);
final PathPermission[] pps = getPathPermissions();
if (pps != null) {
final String path = uri.getPath();
for (PathPermission pp : pps) {
final String pathPerm = pp.getReadPermission();
if (pathPerm != null && pp.match(path)) {
if (context.checkPermission(pathPerm, pid, uid, callerToken)
== PERMISSION_GRANTED) {
return;
} else {
// any denied <path-permission> means we lose
// default <provider> access.
allowDefaultRead = false;
missingPerm = pathPerm;
}
}
}
}
// if we passed <path-permission> checks above, and no default
// <provider> permission, then allow access.
if (allowDefaultRead) return;
}
// last chance, check against any uri grants
final int callingUserId = UserHandle.getUserId(uid);
final Uri userUri = (mSingleUser && !UserHandle.isSameUser(mMyUid, uid))
? maybeAddUserId(uri, callingUserId) : uri;
if (context.checkUriPermission(userUri, pid, uid, Intent.FLAG_GRANT_READ_URI_PERMISSION,
callerToken) == PERMISSION_GRANTED) {
return;
}
final String failReason = mExported
? " requires " + missingPerm + ", or grantUriPermission()"
: " requires the provider be exported, or grantUriPermission()";
throw new SecurityException("Permission Denial: reading "
+ ContentProvider.this.getClass().getName() + " uri " + uri + " from pid=" + pid
+ ", uid=" + uid + failReason);
| | protected void | enforceWritePermissionInner(android.net.Uri uri, android.os.IBinder callerToken){@hide}
final Context context = getContext();
final int pid = Binder.getCallingPid();
final int uid = Binder.getCallingUid();
String missingPerm = null;
if (UserHandle.isSameApp(uid, mMyUid)) {
return;
}
if (mExported && checkUser(pid, uid, context)) {
final String componentPerm = getWritePermission();
if (componentPerm != null) {
if (context.checkPermission(componentPerm, pid, uid, callerToken)
== PERMISSION_GRANTED) {
return;
} else {
missingPerm = componentPerm;
}
}
// track if unprotected write is allowed; any denied
// <path-permission> below removes this ability
boolean allowDefaultWrite = (componentPerm == null);
final PathPermission[] pps = getPathPermissions();
if (pps != null) {
final String path = uri.getPath();
for (PathPermission pp : pps) {
final String pathPerm = pp.getWritePermission();
if (pathPerm != null && pp.match(path)) {
if (context.checkPermission(pathPerm, pid, uid, callerToken)
== PERMISSION_GRANTED) {
return;
} else {
// any denied <path-permission> means we lose
// default <provider> access.
allowDefaultWrite = false;
missingPerm = pathPerm;
}
}
}
}
// if we passed <path-permission> checks above, and no default
// <provider> permission, then allow access.
if (allowDefaultWrite) return;
}
// last chance, check against any uri grants
if (context.checkUriPermission(uri, pid, uid, Intent.FLAG_GRANT_WRITE_URI_PERMISSION,
callerToken) == PERMISSION_GRANTED) {
return;
}
final String failReason = mExported
? " requires " + missingPerm + ", or grantUriPermission()"
: " requires the provider be exported, or grantUriPermission()";
throw new SecurityException("Permission Denial: writing "
+ ContentProvider.this.getClass().getName() + " uri " + uri + " from pid=" + pid
+ ", uid=" + uid + failReason);
| | public android.app.AppOpsManager | getAppOpsManager()
return mTransport.mAppOpsManager;
| | public static java.lang.String | getAuthorityWithoutUserId(java.lang.String auth)Removes userId part from authority string. Expects format:
userId@some.authority
If there is no userId in the authority, it symply returns the argument
if (auth == null) return null;
int end = auth.lastIndexOf('@");
return auth.substring(end+1);
| | public final java.lang.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 {@code null} if not
currently processing a request.
This will always return {@code null} when processing
{@link #getType(Uri)} or {@link #getStreamTypes(Uri, String)} requests.
final String pkg = mCallingPackage.get();
if (pkg != null) {
mTransport.mAppOpsManager.checkPackage(Binder.getCallingUid(), pkg);
}
return pkg;
| | public final Context | getContext()Retrieves the Context this provider is running in. Only available once
{@link #onCreate} has been called -- this will return {@code null} in the
constructor.
return mContext;
| | public IContentProvider | getIContentProvider()Returns the Binder object for this provider.
return mTransport;
| | public final android.content.pm.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.
return mPathPermissions;
| | public final java.lang.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.
return mReadPermission;
| | public java.lang.String[] | getStreamTypes(android.net.Uri uri, java.lang.String mimeTypeFilter)Called by a client to determine the types of data streams that this
content provider supports for the given URI. The default implementation
returns {@code null}, meaning no types. If your content provider stores data
of a particular type, return that MIME type if it matches the given
mimeTypeFilter. If it can perform type conversions, return an array
of all supported MIME types that match mimeTypeFilter.
return null;
| | public abstract java.lang.String | getType(android.net.Uri uri)Implement this to handle requests for the MIME type of the data at the
given URI. The returned MIME type should start with
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.
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.
| | public static android.net.Uri | getUriWithoutUserId(android.net.Uri uri)
if (uri == null) return null;
Uri.Builder builder = uri.buildUpon();
builder.authority(getAuthorityWithoutUserId(uri.getAuthority()));
return builder.build();
| | public static int | getUserIdFromAuthority(java.lang.String auth, int defaultUserId)
if (auth == null) return defaultUserId;
int end = auth.lastIndexOf('@");
if (end == -1) return defaultUserId;
String userIdString = auth.substring(0, end);
try {
return Integer.parseInt(userIdString);
} catch (NumberFormatException e) {
Log.w(TAG, "Error parsing userId.", e);
return UserHandle.USER_NULL;
}
| | public static int | getUserIdFromAuthority(java.lang.String auth)
return getUserIdFromAuthority(auth, UserHandle.USER_CURRENT);
| | public static int | getUserIdFromUri(android.net.Uri uri, int defaultUserId)
if (uri == null) return defaultUserId;
return getUserIdFromAuthority(uri.getAuthority(), defaultUserId);
| | public static int | getUserIdFromUri(android.net.Uri uri)
return getUserIdFromUri(uri, UserHandle.USER_CURRENT);
| | public final java.lang.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.
return mWritePermission;
| | public abstract android.net.Uri | insert(android.net.Uri uri, ContentValues values)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.
| | protected boolean | isTemporary()Returns true if this instance is a temporary content provider.
return false;
| | protected final boolean | matchesOurAuthorities(java.lang.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;
| | public static android.net.Uri | maybeAddUserId(android.net.Uri uri, int userId)
if (uri == null) return null;
if (userId != UserHandle.USER_CURRENT
&& ContentResolver.SCHEME_CONTENT.equals(uri.getScheme())) {
if (!uriHasUserId(uri)) {
//We don't add the user Id if there's already one
Uri.Builder builder = uri.buildUpon();
builder.encodedAuthority("" + userId + "@" + uri.getEncodedAuthority());
return builder.build();
}
}
return uri;
| | public void | onConfigurationChanged(android.content.res.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.
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 abstract 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 {@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.)
| | public void | onLowMemory(){@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 | onTrimMemory(int level)
| | public android.content.res.AssetFileDescriptor | openAssetFile(android.net.Uri uri, java.lang.String mode)This is like {@link #openFile}, but can be implemented by providers
that need to be able to return sub-sections of files, often assets
inside of their .apk.
This method can be called from multiple threads, as described in
Processes
and Threads.
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}.
ParcelFileDescriptor fd = openFile(uri, mode);
return fd != null ? new AssetFileDescriptor(fd, 0, -1) : null;
| | public android.content.res.AssetFileDescriptor | openAssetFile(android.net.Uri uri, java.lang.String mode, android.os.CancellationSignal signal)This is like {@link #openFile}, but can be implemented by providers
that need to be able to return sub-sections of files, often assets
inside of their .apk.
This method can be called from multiple threads, as described in
Processes
and Threads.
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}.
return openAssetFile(uri, mode);
| | public android.os.ParcelFileDescriptor | openFile(android.net.Uri uri, java.lang.String mode)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.
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}.
throw new FileNotFoundException("No files supported by provider at "
+ uri);
| | public android.os.ParcelFileDescriptor | openFile(android.net.Uri uri, java.lang.String mode, android.os.CancellationSignal signal)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.
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}.
return openFile(uri, mode);
| | protected final android.os.ParcelFileDescriptor | openFileHelper(android.net.Uri uri, java.lang.String mode)Convenience for subclasses that wish to implement {@link #openFile}
by looking up a column named "_data" at the given URI.
Cursor c = query(uri, new String[]{"_data"}, null, null, null);
int count = (c != null) ? c.getCount() : 0;
if (count != 1) {
// If there is not exactly one result, throw an appropriate
// exception.
if (c != null) {
c.close();
}
if (count == 0) {
throw new FileNotFoundException("No entry for " + uri);
}
throw new FileNotFoundException("Multiple items at " + uri);
}
c.moveToFirst();
int i = c.getColumnIndex("_data");
String path = (i >= 0 ? c.getString(i) : null);
c.close();
if (path == null) {
throw new FileNotFoundException("Column _data not found.");
}
int modeBits = ParcelFileDescriptor.parseMode(mode);
return ParcelFileDescriptor.open(new File(path), modeBits);
| | public android.os.ParcelFileDescriptor | openPipeHelper(android.net.Uri uri, java.lang.String mimeType, android.os.Bundle opts, T args, android.content.ContentProvider$PipeDataWriter func)A helper function for implementing {@link #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).
try {
final ParcelFileDescriptor[] fds = ParcelFileDescriptor.createPipe();
AsyncTask<Object, Object, Object> task = new AsyncTask<Object, Object, Object>() {
@Override
protected Object doInBackground(Object... params) {
func.writeDataToPipe(fds[1], uri, mimeType, opts, args);
try {
fds[1].close();
} catch (IOException e) {
Log.w(TAG, "Failure closing pipe", e);
}
return null;
}
};
task.executeOnExecutor(AsyncTask.THREAD_POOL_EXECUTOR, (Object[])null);
return fds[0];
} catch (IOException e) {
throw new FileNotFoundException("failure making pipe");
}
| | public android.content.res.AssetFileDescriptor | openTypedAssetFile(android.net.Uri uri, java.lang.String mimeTypeFilter, android.os.Bundle opts)Called by a client to open a read-only stream containing data of a
particular MIME type. This is like {@link #openAssetFile(Uri, String)},
except the file can only be read-only and the content provider may
perform data conversions to generate data of the desired type.
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}.
if ("*/*".equals(mimeTypeFilter)) {
// If they can take anything, the untyped open call is good enough.
return openAssetFile(uri, "r");
}
String baseType = getType(uri);
if (baseType != null && ClipDescription.compareMimeTypes(baseType, mimeTypeFilter)) {
// Use old untyped open call if this provider has a type for this
// URI and it matches the request.
return openAssetFile(uri, "r");
}
throw new FileNotFoundException("Can't open " + uri + " as type " + mimeTypeFilter);
| | public android.content.res.AssetFileDescriptor | openTypedAssetFile(android.net.Uri uri, java.lang.String mimeTypeFilter, android.os.Bundle opts, android.os.CancellationSignal signal)Called by a client to open a read-only stream containing data of a
particular MIME type. This is like {@link #openAssetFile(Uri, String)},
except the file can only be read-only and the content provider may
perform data conversions to generate data of the desired type.
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}.
return openTypedAssetFile(uri, mimeTypeFilter, opts);
| | public abstract android.database.Cursor | query(android.net.Uri uri, java.lang.String[] projection, java.lang.String selection, java.lang.String[] selectionArgs, java.lang.String sortOrder)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:
// 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;
| | public android.database.Cursor | query(android.net.Uri uri, java.lang.String[] projection, java.lang.String selection, java.lang.String[] selectionArgs, java.lang.String sortOrder, android.os.CancellationSignal cancellationSignal)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.
Example client call:
// 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;
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.
return query(uri, projection, selection, selectionArgs, sortOrder);
| | public android.net.Uri | rejectInsert(android.net.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();
| | public android.database.Cursor | rejectQuery(android.net.Uri uri, java.lang.String[] projection, java.lang.String selection, java.lang.String[] selectionArgs, java.lang.String sortOrder, android.os.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);
| | public final void | setAppOps(int readOp, int writeOp)
if (!mNoPerms) {
mTransport.mReadOp = readOp;
mTransport.mWriteOp = writeOp;
}
| | protected final void | setAuthorities(java.lang.String authorities)Change the authorities of the ContentProvider.
This is normally set for you from its manifest information when the provider is first
created.
if (authorities != null) {
if (authorities.indexOf(';") == -1) {
mAuthority = authorities;
mAuthorities = null;
} else {
mAuthority = null;
mAuthorities = authorities.split(";");
}
}
| | private java.lang.String | setCallingPackage(java.lang.String callingPackage)Set the calling package, returning the current value (or {@code null})
which can be used later to restore the previous state.
final String original = mCallingPackage.get();
mCallingPackage.set(callingPackage);
return original;
| | protected final void | setPathPermissions(android.content.pm.PathPermission[] permissions)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.
mPathPermissions = permissions;
| | protected final void | setReadPermission(java.lang.String permission)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.
mReadPermission = permission;
| | protected final void | setWritePermission(java.lang.String permission)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.
mWritePermission = permission;
| | public void | 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.
Log.w(TAG, "implement ContentProvider shutdown() to make sure all database " +
"connections are gracefully shutdown");
| | public android.net.Uri | uncanonicalize(android.net.Uri url)Remove canonicalization from canonical URIs previously returned by
{@link #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.
return url;
| | public abstract int | update(android.net.Uri uri, ContentValues values, java.lang.String selection, java.lang.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.
| | public static boolean | uriHasUserId(android.net.Uri uri)
if (uri == null) return false;
return !TextUtils.isEmpty(uri.getUserInfo());
| | private void | validateIncomingUri(android.net.Uri uri)
String auth = uri.getAuthority();
int userId = getUserIdFromAuthority(auth, UserHandle.USER_CURRENT);
if (userId != UserHandle.USER_CURRENT && userId != mContext.getUserId()) {
throw new SecurityException("trying to query a ContentProvider in user "
+ mContext.getUserId() + " with a uri belonging to user " + userId);
}
if (!matchesOurAuthorities(getAuthorityWithoutUserId(auth))) {
String message = "The authority of the uri " + uri + " does not match the one of the "
+ "contentProvider: ";
if (mAuthority != null) {
message += mAuthority;
} else {
message += mAuthorities;
}
throw new SecurityException(message);
}
|
|
