/* * Copyright (C) 2006 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.content; import static android.content.pm.PackageManager.PERMISSION_GRANTED; import android.content.pm.PackageManager; import android.content.pm.PathPermission; import android.content.pm.ProviderInfo; import android.content.res.AssetFileDescriptor; import android.content.res.Configuration; import android.database.Cursor; import android.database.SQLException; import android.net.Uri; import android.os.AsyncTask; import android.os.Binder; import android.os.Bundle; import android.os.CancellationSignal; import android.os.ICancellationSignal; import android.os.OperationCanceledException; import android.os.ParcelFileDescriptor; import android.os.Process; import android.os.RemoteException; import android.os.UserId; import android.util.Log; import java.io.File; import java.io.FileDescriptor; import java.io.FileNotFoundException; import java.io.IOException; import java.io.PrintWriter; import java.util.ArrayList; /** * 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: *

* *

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.

*/ 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 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-null and local, returns its actual * ContentProvider instance. Otherwise returns 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 { ContentProvider getContentProvider() { return ContentProvider.this; } @Override public String getProviderName() { return getContentProvider().getClass().getName(); } @Override public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder, ICancellationSignal cancellationSignal) { enforceReadPermission(uri); 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(Uri uri, ContentValues initialValues) { enforceWritePermission(uri); return ContentProvider.this.insert(uri, initialValues); } @Override public int bulkInsert(Uri uri, ContentValues[] initialValues) { enforceWritePermission(uri); return ContentProvider.this.bulkInsert(uri, initialValues); } @Override public ContentProviderResult[] applyBatch(ArrayList operations) throws OperationApplicationException { for (ContentProviderOperation operation : operations) { if (operation.isReadOperation()) { enforceReadPermission(operation.getUri()); } if (operation.isWriteOperation()) { enforceWritePermission(operation.getUri()); } } return ContentProvider.this.applyBatch(operations); } @Override public int delete(Uri uri, String selection, String[] selectionArgs) { enforceWritePermission(uri); return ContentProvider.this.delete(uri, selection, selectionArgs); } @Override public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) { enforceWritePermission(uri); return ContentProvider.this.update(uri, values, selection, selectionArgs); } @Override public ParcelFileDescriptor openFile(Uri uri, String mode) throws FileNotFoundException { if (mode != null && mode.startsWith("rw")) enforceWritePermission(uri); else enforceReadPermission(uri); return ContentProvider.this.openFile(uri, mode); } @Override public AssetFileDescriptor openAssetFile(Uri uri, String mode) throws FileNotFoundException { if (mode != null && mode.startsWith("rw")) enforceWritePermission(uri); else enforceReadPermission(uri); return ContentProvider.this.openAssetFile(uri, mode); } @Override public Bundle call(String method, String arg, Bundle extras) { return ContentProvider.this.call(method, arg, extras); } @Override public String[] getStreamTypes(Uri uri, String mimeTypeFilter) { return ContentProvider.this.getStreamTypes(uri, mimeTypeFilter); } @Override public AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeType, Bundle opts) throws FileNotFoundException { enforceReadPermission(uri); return ContentProvider.this.openTypedAssetFile(uri, mimeType, opts); } @Override public ICancellationSignal createCancellationSignal() throws RemoteException { return CancellationSignal.createTransport(); } private void enforceReadPermission(Uri uri) throws SecurityException { final Context context = getContext(); final int pid = Binder.getCallingPid(); final int uid = Binder.getCallingUid(); String missingPerm = null; if (uid == mMyUid) { return; } if (mExported) { final String componentPerm = getReadPermission(); if (componentPerm != null) { if (context.checkPermission(componentPerm, pid, uid) == PERMISSION_GRANTED) { return; } else { missingPerm = componentPerm; } } // track if unprotected read is allowed; any denied // 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) == PERMISSION_GRANTED) { return; } else { // any denied means we lose // default access. allowDefaultRead = false; missingPerm = pathPerm; } } } } // if we passed checks above, and no default // permission, then allow access. if (allowDefaultRead) return; } // last chance, check against any uri grants if (context.checkUriPermission(uri, pid, uid, Intent.FLAG_GRANT_READ_URI_PERMISSION) == 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); } private void enforceWritePermission(Uri uri) throws SecurityException { final Context context = getContext(); final int pid = Binder.getCallingPid(); final int uid = Binder.getCallingUid(); String missingPerm = null; if (uid == mMyUid) { return; } if (mExported) { final String componentPerm = getWritePermission(); if (componentPerm != null) { if (context.checkPermission(componentPerm, pid, uid) == PERMISSION_GRANTED) { return; } else { missingPerm = componentPerm; } } // track if unprotected write is allowed; any denied // 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) == PERMISSION_GRANTED) { return; } else { // any denied means we lose // default access. allowDefaultWrite = false; missingPerm = pathPerm; } } } } // if we passed checks above, and no default // 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) == 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); } } /** * Retrieves the Context this provider is running in. Only available once * {@link #onCreate} has been called -- this will return null in the * constructor. */ public final Context getContext() { return mContext; } /** * Change the permission required to read data from the content * provider. This is normally set for you from its manifest information * when the provider is first created. * * @param permission Name of the permission required for read-only access. */ protected final void setReadPermission(String permission) { mReadPermission = permission; } /** * Return the name of the permission required for read-only access to * this content provider. This method can be called from multiple * threads, as described in * Processes * and Threads. */ public final String getReadPermission() { return mReadPermission; } /** * Change the permission required to read and write data in the content * provider. This is normally set for you from its manifest information * when the provider is first created. * * @param permission Name of the permission required for read/write access. */ protected final void setWritePermission(String permission) { mWritePermission = permission; } /** * Return the name of the permission required for read/write access to * this content provider. This method can be called from multiple * threads, as described in * Processes * and Threads. */ public final String getWritePermission() { return mWritePermission; } /** * Change the path-based permission required to read and/or write data in * the content provider. This is normally set for you from its manifest * information when the provider is first created. * * @param permissions Array of path permission descriptions. */ protected final void setPathPermissions(PathPermission[] permissions) { mPathPermissions = permissions; } /** * Return the path-based permissions required for read and/or write access to * this content provider. This method can be called from multiple * threads, as described in * Processes * and Threads. */ public final PathPermission[] getPathPermissions() { return mPathPermissions; } /** * Implement this to initialize your content provider on startup. * This method is called for all registered content providers on the * application main thread at application launch time. It must not perform * lengthy operations, or application startup will be delayed. * *

You should defer nontrivial initialization (such as opening, * upgrading, and scanning databases) until the content provider is used * (via {@link #query}, {@link #insert}, etc). Deferred initialization * keeps application startup fast, avoids unnecessary work if the provider * turns out not to be needed, and stops database errors (such as a full * disk) from halting application launch. * *

If you use SQLite, {@link android.database.sqlite.SQLiteOpenHelper} * is a helpful utility class that makes it easy to manage databases, * and will automatically defer opening until first use. If you do use * SQLiteOpenHelper, make sure to avoid calling * {@link android.database.sqlite.SQLiteOpenHelper#getReadableDatabase} or * {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase} * from this method. (Instead, override * {@link android.database.sqlite.SQLiteOpenHelper#onOpen} to initialize the * database when it is first opened.) * * @return true if the provider was successfully loaded, false otherwise */ public abstract boolean onCreate(); /** * {@inheritDoc} * This method is always called on the application main thread, and must * not perform lengthy operations. * *

The default content provider implementation does nothing. * Override this method to take appropriate action. * (Content providers do not usually care about things like screen * orientation, but may want to know about locale changes.) */ public void onConfigurationChanged(Configuration newConfig) { } /** * {@inheritDoc} * This method is always called on the application main thread, and must * not perform lengthy operations. * *

The default content provider implementation does nothing. * Subclasses may override this method to take appropriate action. */ public void onLowMemory() { } public void onTrimMemory(int level) { } /** * 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;
* * @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 * null all columns are included. * @param selection A selection criteria to apply when filtering rows. * If 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 null then the provider is free to define the sort order. * @return a Cursor or 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. *

* 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. * * @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 * null all columns are included. * @param selection A selection criteria to apply when filtering rows. * If 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 null then the provider is free to define the sort order. * @param cancellationSignal A signal to cancel the operation in progress, or null if none. * If the operation is canceled, then {@link OperationCanceledException} will be thrown * when the query is executed. * @return a Cursor or 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 * 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. * * @param uri the URI to query. * @return a MIME type string, or null if there is no type. */ public abstract String getType(Uri uri); /** * 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. * @param values A set of column_name/value pairs to add to the database. * @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. * @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 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 Bundle mapping from column names to new column values (NULL is a * valid value). * @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. * *

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. * * @param uri The URI whose file is to be opened. * @param mode Access mode for the file. May be "r" for read-only access, * "rw" for read and write access, or "rwt" for read and write access * that truncates any existing file. * * @return Returns a new ParcelFileDescriptor which you can use to access * the file. * * @throws FileNotFoundException Throws FileNotFoundException if there is * no file associated with the given URI or the mode is invalid. * @throws SecurityException Throws SecurityException if the caller does * not have permission to access the file. * * @see #openAssetFile(Uri, String) * @see #openFileHelper(Uri, String) */ public ParcelFileDescriptor openFile(Uri uri, String mode) throws FileNotFoundException { throw new FileNotFoundException("No files supported by provider at " + uri); } /** * 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. * *

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.

* * @param uri The URI whose file is to be opened. * @param mode Access mode for the file. May be "r" for read-only access, * "w" for write-only access (erasing whatever data is currently in * the file), "wa" for write-only access to append to any existing data, * "rw" for read and write access on any existing data, and "rwt" for read * and write access that truncates any existing file. * * @return Returns a new AssetFileDescriptor which you can use to access * the file. * * @throws FileNotFoundException Throws FileNotFoundException if there is * no file associated with the given URI or the mode is invalid. * @throws SecurityException Throws SecurityException if the caller does * not have permission to access the file. * * @see #openFile(Uri, String) * @see #openFileHelper(Uri, String) */ public AssetFileDescriptor openAssetFile(Uri uri, String mode) throws FileNotFoundException { ParcelFileDescriptor fd = openFile(uri, mode); return fd != null ? new AssetFileDescriptor(fd, 0, -1) : null; } /** * Convenience for subclasses that wish to implement {@link #openFile} * by looking up a column named "_data" at the given URI. * * @param uri The URI to be opened. * @param mode The file mode. May be "r" for read-only access, * "w" for write-only access (erasing whatever data is currently in * the file), "wa" for write-only access to append to any existing data, * "rw" for read and write access on any existing data, and "rwt" for read * and write access that truncates any existing file. * * @return Returns a new ParcelFileDescriptor that can be used by the * client to access the file. */ protected final ParcelFileDescriptor openFileHelper(Uri uri, String mode) throws FileNotFoundException { 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 = ContentResolver.modeToMode(uri, mode); return ParcelFileDescriptor.open(new File(path), modeBits); } /** * Called by a client to determine the types of data streams that this * content provider supports for the given URI. The default implementation * returns 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. * * @param uri The data in the content provider being queried. * @param mimeTypeFilter The type of data the client desires. May be * a pattern, such as *\/* to retrieve all possible data types. * @return Returns null if there are no possible data streams for the * given mimeTypeFilter. Otherwise returns an array of all available * concrete MIME types. * * @see #getType(Uri) * @see #openTypedAssetFile(Uri, String, Bundle) * @see ClipDescription#compareMimeTypes(String, String) */ public String[] getStreamTypes(Uri uri, String mimeTypeFilter) { return null; } /** * 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 the match, simple calls * {@link #openAssetFile(Uri, String)}. * *

See {@link ClipData} for examples of the use and implementation * of this method. * * @param uri The data in the content provider being queried. * @param mimeTypeFilter The type of data the client desires. May be * a pattern, such as *\/*, if the caller does not have specific type * requirements; in this case the content provider will pick its best * type matching the pattern. * @param opts Additional options from the client. The definitions of * these are specific to the content provider being called. * * @return Returns a new AssetFileDescriptor from which the client can * read data of the desired type. * * @throws FileNotFoundException Throws FileNotFoundException if there is * no file associated with the given URI or the mode is invalid. * @throws SecurityException Throws SecurityException if the caller does * not have permission to access the data. * @throws IllegalArgumentException Throws IllegalArgumentException if the * content provider does not support the requested MIME type. * * @see #getStreamTypes(Uri, String) * @see #openAssetFile(Uri, String) * @see ClipDescription#compareMimeTypes(String, String) */ public AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts) throws FileNotFoundException { 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); } /** * Interface to write a stream of data to a pipe. Use with * {@link ContentProvider#openPipeHelper}. */ public interface PipeDataWriter { /** * Called from a background thread to stream data out to a pipe. * Note that the pipe is blocking, so this thread can block on * writes for an arbitrary amount of time if the client is slow * at reading. * * @param output The pipe where data should be written. This will be * closed for you upon returning from this function. * @param uri The URI whose data is to be written. * @param mimeType The desired type of data to be written. * @param opts Options supplied by caller. * @param args Your own custom arguments. */ public void writeDataToPipe(ParcelFileDescriptor output, Uri uri, String mimeType, Bundle opts, T args); } /** * 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). * * @param uri The URI whose data is to be written. * @param mimeType The desired type of data to be written. * @param opts Options supplied by caller. * @param args Your own custom arguments. * @param func Interface implementing the function that will actually * stream the data. * @return Returns a new ParcelFileDescriptor holding the read side of * the pipe. This should be returned to the caller for reading; the caller * is responsible for closing it when done. */ public ParcelFileDescriptor openPipeHelper(final Uri uri, final String mimeType, final Bundle opts, final T args, final PipeDataWriter func) throws FileNotFoundException { try { final ParcelFileDescriptor[] fds = ParcelFileDescriptor.createPipe(); AsyncTask task = new AsyncTask() { @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"); } } /** * Returns true if this instance is a temporary content provider. * @return true if this instance is a temporary content provider */ protected boolean isTemporary() { return false; } /** * Returns the Binder object for this provider. * * @return the Binder object for this provider * @hide */ public IContentProvider getIContentProvider() { return mTransport; } /** * After being instantiated, this is called to tell the content provider * about itself. * * @param context The context this provider is running in * @param info Registered information about this content provider */ public void attachInfo(Context context, ProviderInfo info) { /* * We may be using AsyncTask from binder threads. Make it init here * so its static handler is on the main thread. */ AsyncTask.init(); /* * 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; mMyUid = Process.myUid(); if (info != null) { setReadPermission(info.readPermission); setWritePermission(info.writePermission); setPathPermissions(info.pathPermissions); mExported = info.exported; } ContentProvider.this.onCreate(); } } /** * 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. * * @param operations the operations to apply * @return the results of the applications * @throws OperationApplicationException thrown if any operation fails. * @see ContentProviderOperation#apply */ public ContentProviderResult[] applyBatch(ArrayList operations) throws OperationApplicationException { 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; } /** * Call a provider-defined method. This can be used to implement * interfaces that are cheaper and/or unnatural for a table-like * model. * * @param method method name to call. Opaque to framework, but should not be null. * @param arg provider-defined String argument. May be null. * @param extras provider-defined Bundle argument. May be null. * @return provider-defined return value. May be null. Null is also * the default for providers which don't implement any call methods. */ public Bundle call(String method, String arg, Bundle extras) { return null; } /** * 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. *

*/ public void shutdown() { Log.w(TAG, "implement ContentProvider shutdown() to make sure all database " + "connections are gracefully shutdown"); } /** * Print the Provider's state into the given stream. This gets invoked if * you run "adb shell dumpsys activity provider <provider_component_name>". * * @param prefix Desired prefix to prepend at each line of output. * @param fd The raw file descriptor that the dump is being sent to. * @param writer The PrintWriter to which you should dump your state. This will be * closed for you after you return. * @param args additional arguments to the dump request. * @hide */ public void dump(FileDescriptor fd, PrintWriter writer, String[] args) { writer.println("nothing to dump"); } }