| /* |
| * 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.UserHandle; |
| 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}. |
| * |
| * <p>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.</p> |
| * |
| * <p>The primary methods that need to be implemented are: |
| * <ul> |
| * <li>{@link #onCreate} which is called to initialize the provider</li> |
| * <li>{@link #query} which returns data to the caller</li> |
| * <li>{@link #insert} which inserts new data into the content provider</li> |
| * <li>{@link #update} which updates existing data in the content provider</li> |
| * <li>{@link #delete} which deletes data from the content provider</li> |
| * <li>{@link #getType} which returns the MIME type of data in the content provider</li> |
| * </ul></p> |
| * |
| * <p class="caution">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.</p> |
| * |
| * <p>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.</p> |
| * |
| * <div class="special reference"> |
| * <h3>Developer Guides</h3> |
| * <p>For more information about using content providers, read the |
| * <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> |
| * developer guide.</p> |
| */ |
| 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 |
| * <a href="{@docRoot}guide/topics/manifest/provider-element.html">declared |
| * in the manifest</a>, accessed with {@link ContentResolver}, and created |
| * automatically by the system, so applications usually do not create |
| * ContentProvider instances directly. |
| * |
| * <p>At construction time, the object is uninitialized, and most fields and |
| * methods are unavailable. Subclasses should initialize themselves in |
| * {@link #onCreate}, not the constructor. |
| * |
| * <p>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<ContentProviderOperation> 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.indexOf('w') != -1) 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.indexOf('w') != -1) 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 (UserHandle.isSameApp(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 |
| // <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) == 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 |
| 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 (UserHandle.isSameApp(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 |
| // <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) == 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) |
| == 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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| */ |
| 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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| */ |
| 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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| */ |
| 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. |
| * |
| * <p>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. |
| * |
| * <p>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. |
| * |
| * <p>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. |
| * |
| * <p>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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * <p> |
| * Example client call:<p> |
| * <pre>// 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.</pre> |
| * Example implementation:<p> |
| * <pre>// 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;</pre> |
| * |
| * @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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * <p> |
| * Example client call:<p> |
| * <pre>// 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.</pre> |
| * Example implementation:<p> |
| * <pre>// 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;</pre> |
| * <p> |
| * 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 |
| * <code>vnd.android.cursor.item</code> for a single record, |
| * or <code>vnd.android.cursor.dir/</code> for multiple items. |
| * This method can be called from multiple threads, as described in |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * |
| * <p>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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * @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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * |
| * @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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * |
| * <p>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 <code>content://contacts/people/22</code> 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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * |
| * @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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * |
| * <p>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. |
| * |
| * <p>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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * |
| * <p>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. |
| * |
| * <p class="note">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.</p> |
| * |
| * @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. |
| * |
| * <p>The default implementation compares the given mimeType against the |
| * result of {@link #getType(Uri)} and, if the match, simple calls |
| * {@link #openAssetFile(Uri, String)}. |
| * |
| * <p>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<T> { |
| /** |
| * 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 <T> ParcelFileDescriptor openPipeHelper(final Uri uri, final String mimeType, |
| final Bundle opts, final T args, final PipeDataWriter<T> func) |
| throws FileNotFoundException { |
| 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"); |
| } |
| } |
| |
| /** |
| * 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 |
| * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes |
| * and Threads</a>. |
| * |
| * @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<ContentProviderOperation> 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. |
| * |
| * <p> |
| * 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). |
| * </p> |
| * <p> |
| * 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. |
| * </p> |
| */ |
| 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"); |
| } |
| } |