public abstract class ContentResolver extends Object
For more information about using a ContentResolver with content providers, read the Content Providers developer guide.
Modifier and Type | Class and Description |
---|---|
static interface |
ContentResolver.NotifyFlags |
class |
ContentResolver.OpenResourceIdResult
A resource identified by the
Resources that contains it, and a resource id. |
Modifier and Type | Field and Description |
---|---|
static Intent |
ACTION_SYNC_CONN_STATUS_CHANGED |
static String |
ANY_CURSOR_ITEM_TYPE
This is the Android platform's generic MIME type to match any MIME
type of the form "
CURSOR_ITEM_BASE_TYPE /SUB_TYPE ". |
static String |
CONTENT_SERVICE_NAME |
static String |
CURSOR_DIR_BASE_TYPE
This is the Android platform's base MIME type for a content: URI
containing a Cursor of zero or more items.
|
static String |
CURSOR_ITEM_BASE_TYPE
This is the Android platform's base MIME type for a content: URI
containing a Cursor of a single item.
|
static String |
EXTRA_SIZE
An extra
Point describing the optimal size for a requested image
resource, in pixels. |
static int |
NOTIFY_SKIP_NOTIFY_FOR_DESCENDANTS
Flag for
notifyChange(Uri, ContentObserver, int) : if set, this notification
will be skipped if it is being delivered to the root URI of a ContentObserver that is
using "notify for descendants." |
static int |
NOTIFY_SYNC_TO_NETWORK
Flag for
notifyChange(Uri, ContentObserver, int) : attempt to sync the change
to the network. |
static String |
SCHEME_ANDROID_RESOURCE |
static String |
SCHEME_CONTENT |
static String |
SCHEME_FILE |
static int |
SYNC_ERROR_AUTHENTICATION |
static int |
SYNC_ERROR_CONFLICT |
static int |
SYNC_ERROR_INTERNAL |
static int |
SYNC_ERROR_IO |
static int |
SYNC_ERROR_PARSE |
static int |
SYNC_ERROR_SYNC_ALREADY_IN_PROGRESS |
static int |
SYNC_ERROR_TOO_MANY_DELETIONS |
static int |
SYNC_ERROR_TOO_MANY_RETRIES |
static String |
SYNC_EXTRAS_ACCOUNT
Deprecated.
instead use
#requestSync(android.accounts.Account, String, android.os.Bundle) |
static String |
SYNC_EXTRAS_DISALLOW_METERED
Flag to allow sync to occur on metered network.
|
static String |
SYNC_EXTRAS_DISCARD_LOCAL_DELETIONS
Indicates that the sync adapter should not proceed with the delete operations,
if it determines that there are too many.
|
static String |
SYNC_EXTRAS_DO_NOT_RETRY
If this extra is set to true then the request will not be retried if it fails.
|
static String |
SYNC_EXTRAS_EXPECTED_DOWNLOAD
User-specified flag for expected download size.
|
static String |
SYNC_EXTRAS_EXPECTED_UPLOAD
User-specified flag for expected upload size.
|
static String |
SYNC_EXTRAS_EXPEDITED
If this extra is set to true, the sync request will be scheduled
at the front of the sync request queue and without any delay
|
static String |
SYNC_EXTRAS_FORCE
Deprecated.
instead use
SYNC_EXTRAS_MANUAL |
static String |
SYNC_EXTRAS_IGNORE_BACKOFF
If this extra is set to true then any backoffs for the initial attempt (e.g. due to retries)
are ignored by the sync scheduler.
|
static String |
SYNC_EXTRAS_IGNORE_SETTINGS
If this extra is set to true then the sync settings (like getSyncAutomatically())
are ignored by the sync scheduler.
|
static String |
SYNC_EXTRAS_INITIALIZE
Set by the SyncManager to request that the SyncAdapter initialize itself for
the given account/authority pair.
|
static String |
SYNC_EXTRAS_MANUAL
Setting this extra is the equivalent of setting both
SYNC_EXTRAS_IGNORE_SETTINGS
and SYNC_EXTRAS_IGNORE_BACKOFF |
static String |
SYNC_EXTRAS_OVERRIDE_TOO_MANY_DELETIONS
Indicates that the sync adapter should proceed with the delete operations,
even if it determines that there are too many.
|
static String |
SYNC_EXTRAS_PRIORITY
Priority of this sync with respect to other syncs scheduled for this application.
|
static String |
SYNC_EXTRAS_REQUIRE_CHARGING
If this extra is set to true, the sync request will be scheduled
only when the device is plugged in.
|
static String |
SYNC_EXTRAS_UPLOAD
Indicates that this sync is intended to only upload local changes to the server.
|
static int |
SYNC_OBSERVER_TYPE_ACTIVE |
static int |
SYNC_OBSERVER_TYPE_ALL |
static int |
SYNC_OBSERVER_TYPE_PENDING |
static int |
SYNC_OBSERVER_TYPE_SETTINGS |
static int |
SYNC_OBSERVER_TYPE_STATUS |
Constructor and Description |
---|
ContentResolver(Context context) |
Modifier and Type | Method and Description |
---|---|
ContentProviderClient |
acquireContentProviderClient(String name)
Returns a
ContentProviderClient that is associated with the ContentProvider
with the authority of name, starting the provider if necessary. |
ContentProviderClient |
acquireContentProviderClient(Uri uri)
Returns a
ContentProviderClient that is associated with the ContentProvider
that services the content at uri, starting the provider if necessary. |
protected IContentProvider |
acquireExistingProvider(Context c,
String name)
Providing a default implementation of this, to avoid having to change a
lot of other things, but implementations of ContentResolver should
implement it.
|
IContentProvider |
acquireExistingProvider(Uri uri)
Returns the content provider for the given content URI if the process
already has a reference on it.
|
protected abstract IContentProvider |
acquireProvider(Context c,
String name) |
IContentProvider |
acquireProvider(String name) |
IContentProvider |
acquireProvider(Uri uri)
Returns the content provider for the given content URI.
|
ContentProviderClient |
acquireUnstableContentProviderClient(String name)
Like
acquireContentProviderClient(String) , but for use when you do
not trust the stability of the target content provider. |
ContentProviderClient |
acquireUnstableContentProviderClient(Uri uri)
Like
acquireContentProviderClient(Uri) , but for use when you do
not trust the stability of the target content provider. |
protected abstract IContentProvider |
acquireUnstableProvider(Context c,
String name) |
IContentProvider |
acquireUnstableProvider(String name) |
IContentProvider |
acquireUnstableProvider(Uri uri)
Returns the content provider for the given content URI.
|
static void |
addPeriodicSync(Account account,
String authority,
Bundle extras,
long pollFrequency)
Specifies that a sync should be requested with the specified the account, authority,
and extras at the given frequency.
|
static Object |
addStatusChangeListener(int mask,
SyncStatusObserver callback)
Request notifications when the different aspects of the SyncManager change.
|
ContentProviderResult[] |
applyBatch(String authority,
ArrayList<ContentProviderOperation> operations)
Applies each of the
ContentProviderOperation objects and returns an array
of their results. |
void |
appNotRespondingViaProvider(IContentProvider icp) |
int |
bulkInsert(Uri url,
ContentValues[] values)
Inserts multiple rows into a table at the given URL.
|
Bundle |
call(Uri uri,
String method,
String arg,
Bundle extras)
Call a provider-defined method.
|
static void |
cancelSync(Account account,
String authority)
Cancel any active or pending syncs that match account and authority.
|
static void |
cancelSync(SyncRequest request)
Remove the specified sync.
|
void |
cancelSync(Uri uri)
Deprecated.
instead use
#cancelSync(android.accounts.Account, String) |
static void |
cancelSyncAsUser(Account account,
String authority,
int userId) |
Uri |
canonicalize(Uri url)
Transform the given url to a canonical representation of
its referenced resource, which can be used across devices, persisted,
backed up and restored, etc.
|
int |
delete(Uri url,
String where,
String[] selectionArgs)
Deletes row(s) specified by a content URI.
|
Bundle |
getCache(Uri key) |
static IContentService |
getContentService() |
static SyncInfo |
getCurrentSync()
Deprecated.
Since multiple concurrent syncs are now supported you should use
getCurrentSyncs() to get the accurate list of current syncs.
This method returns the first item from the list of current syncs
or null if there are none. |
static List<SyncInfo> |
getCurrentSyncs()
Returns a list with information about all the active syncs.
|
static List<SyncInfo> |
getCurrentSyncsAsUser(int userId) |
static int |
getIsSyncable(Account account,
String authority)
Check if this account/provider is syncable.
|
static int |
getIsSyncableAsUser(Account account,
String authority,
int userId) |
static boolean |
getMasterSyncAutomatically()
Gets the master auto-sync setting that applies to all the providers and accounts.
|
static boolean |
getMasterSyncAutomaticallyAsUser(int userId) |
List<UriPermission> |
getOutgoingPersistedUriPermissions()
Return list of all persisted URI permission grants that are hosted by the
calling app.
|
String |
getPackageName() |
static List<PeriodicSync> |
getPeriodicSyncs(Account account,
String authority)
Get the list of information about the periodic syncs for the given account and authority.
|
List<UriPermission> |
getPersistedUriPermissions()
Return list of all URI permission grants that have been persisted by the
calling app.
|
ContentResolver.OpenResourceIdResult |
getResourceId(Uri uri)
Resolves an android.resource URI to a
Resources and a resource id. |
String[] |
getStreamTypes(Uri url,
String mimeTypeFilter)
Query for the possible MIME types for the representations the given
content URL can be returned when opened as as stream with
openTypedAssetFileDescriptor(android.net.Uri, java.lang.String, android.os.Bundle) . |
static String[] |
getSyncAdapterPackagesForAuthorityAsUser(String authority,
int userId) |
static SyncAdapterType[] |
getSyncAdapterTypes()
Get information about the SyncAdapters that are known to the system.
|
static SyncAdapterType[] |
getSyncAdapterTypesAsUser(int userId) |
static boolean |
getSyncAutomatically(Account account,
String authority)
Check if the provider should be synced when a network tickle is received
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_SETTINGS . |
static boolean |
getSyncAutomaticallyAsUser(Account account,
String authority,
int userId) |
static SyncStatusInfo |
getSyncStatus(Account account,
String authority)
Returns the status that matches the authority.
|
static SyncStatusInfo |
getSyncStatusAsUser(Account account,
String authority,
int userId) |
String |
getType(Uri url)
Return the MIME type of the given content URL.
|
Drawable |
getTypeDrawable(String mimeType) |
Uri |
insert(Uri url,
ContentValues values)
Inserts a row into a table at the given URL.
|
static boolean |
invalidPeriodicExtras(Bundle extras)
Helper function to throw an
IllegalArgumentException if any illegal
extras were set for a periodic sync. |
static boolean |
isSyncActive(Account account,
String authority)
Returns true if there is currently a sync operation for the given account or authority
actively being processed.
|
static boolean |
isSyncPending(Account account,
String authority)
Return true if the pending status is true of any matching authorities.
|
static boolean |
isSyncPendingAsUser(Account account,
String authority,
int userId) |
void |
notifyChange(Uri uri,
ContentObserver observer)
Notify registered observers that a row was updated and attempt to sync changes
to the network.
|
void |
notifyChange(Uri uri,
ContentObserver observer,
boolean syncToNetwork)
Notify registered observers that a row was updated.
|
void |
notifyChange(Uri uri,
ContentObserver observer,
boolean syncToNetwork,
int userHandle)
Notify registered observers within the designated user(s) that a row was updated.
|
void |
notifyChange(Uri uri,
ContentObserver observer,
int flags)
Notify registered observers that a row was updated.
|
void |
notifyChange(Uri uri,
ContentObserver observer,
int flags,
int userHandle)
Notify registered observers within the designated user(s) that a row was updated.
|
AssetFileDescriptor |
openAssetFileDescriptor(Uri uri,
String mode)
Open a raw file descriptor to access data under a URI.
|
AssetFileDescriptor |
openAssetFileDescriptor(Uri uri,
String mode,
CancellationSignal cancellationSignal)
Open a raw file descriptor to access data under a URI.
|
ParcelFileDescriptor |
openFileDescriptor(Uri uri,
String mode)
Open a raw file descriptor to access data under a URI.
|
ParcelFileDescriptor |
openFileDescriptor(Uri uri,
String mode,
CancellationSignal cancellationSignal)
Open a raw file descriptor to access data under a URI.
|
InputStream |
openInputStream(Uri uri)
Open a stream on to the content associated with a content URI.
|
OutputStream |
openOutputStream(Uri uri)
Synonym for
openOutputStream(uri, "w") . |
OutputStream |
openOutputStream(Uri uri,
String mode)
Open a stream on to the content associated with a content URI.
|
AssetFileDescriptor |
openTypedAssetFileDescriptor(Uri uri,
String mimeType,
Bundle opts)
Open a raw file descriptor to access (potentially type transformed)
data from a "content:" URI.
|
AssetFileDescriptor |
openTypedAssetFileDescriptor(Uri uri,
String mimeType,
Bundle opts,
CancellationSignal cancellationSignal)
Open a raw file descriptor to access (potentially type transformed)
data from a "content:" URI.
|
void |
putCache(Uri key,
Bundle value) |
Cursor |
query(Uri uri,
String[] projection,
String selection,
String[] selectionArgs,
String sortOrder)
Query the given URI, returning a
Cursor over the result set. |
Cursor |
query(Uri uri,
String[] projection,
String selection,
String[] selectionArgs,
String sortOrder,
CancellationSignal cancellationSignal)
Query the given URI, returning a
Cursor over the result set
with optional support for cancellation. |
void |
registerContentObserver(Uri uri,
boolean notifyForDescendants,
ContentObserver observer)
Register an observer class that gets callbacks when data identified by a
given content URI changes.
|
void |
registerContentObserver(Uri uri,
boolean notifyForDescendents,
ContentObserver observer,
int userHandle) |
void |
releasePersistableUriPermission(Uri uri,
int modeFlags)
Relinquish a persisted URI permission grant.
|
abstract boolean |
releaseProvider(IContentProvider icp) |
abstract boolean |
releaseUnstableProvider(IContentProvider icp) |
static void |
removePeriodicSync(Account account,
String authority,
Bundle extras)
Remove a periodic sync.
|
static void |
removeStatusChangeListener(Object handle)
Remove a previously registered status change listener.
|
static void |
requestSync(Account account,
String authority,
Bundle extras)
Start an asynchronous sync operation.
|
static void |
requestSync(SyncRequest request)
Register a sync with the SyncManager.
|
static void |
requestSyncAsUser(Account account,
String authority,
int userId,
Bundle extras) |
int |
resolveUserId(Uri uri) |
static void |
setIsSyncable(Account account,
String authority,
int syncable)
Set whether this account/provider is syncable.
|
static void |
setMasterSyncAutomatically(boolean sync)
Sets the master auto-sync setting that applies to all the providers and accounts.
|
static void |
setMasterSyncAutomaticallyAsUser(boolean sync,
int userId) |
static void |
setSyncAutomatically(Account account,
String authority,
boolean sync)
Set whether or not the provider is synced when it receives a network tickle.
|
static void |
setSyncAutomaticallyAsUser(Account account,
String authority,
boolean sync,
int userId) |
void |
startSync(Uri uri,
Bundle extras)
Deprecated.
instead use
#requestSync(android.accounts.Account, String, android.os.Bundle) |
static int |
syncErrorStringToInt(String error) |
static String |
syncErrorToString(int error) |
void |
takePersistableUriPermission(Uri uri,
int modeFlags)
Take a persistable URI permission grant that has been offered.
|
Uri |
uncanonicalize(Uri url)
Given a canonical Uri previously generated by
canonicalize(android.net.Uri) , convert
it to its local non-canonical form. |
void |
unregisterContentObserver(ContentObserver observer)
Unregisters a change observer.
|
abstract void |
unstableProviderDied(IContentProvider icp) |
int |
update(Uri uri,
ContentValues values,
String where,
String[] selectionArgs)
Update row(s) in a content URI.
|
static void |
validateSyncExtrasBundle(Bundle extras)
Check that only values of the following types are in the Bundle:
Integer
Long
Boolean
Float
Double
String
Account
null
|
@Deprecated public static final String SYNC_EXTRAS_ACCOUNT
#requestSync(android.accounts.Account, String, android.os.Bundle)
public static final String SYNC_EXTRAS_EXPEDITED
public static final String SYNC_EXTRAS_REQUIRE_CHARGING
SyncRequest
.@Deprecated public static final String SYNC_EXTRAS_FORCE
SYNC_EXTRAS_MANUAL
public static final String SYNC_EXTRAS_IGNORE_SETTINGS
public static final String SYNC_EXTRAS_IGNORE_BACKOFF
public static final String SYNC_EXTRAS_DO_NOT_RETRY
public static final String SYNC_EXTRAS_MANUAL
SYNC_EXTRAS_IGNORE_SETTINGS
and SYNC_EXTRAS_IGNORE_BACKOFF
public static final String SYNC_EXTRAS_UPLOAD
notifyChange(android.net.Uri, android.database.ContentObserver, boolean)
public static final String SYNC_EXTRAS_OVERRIDE_TOO_MANY_DELETIONS
SyncResult.tooManyDeletions
public static final String SYNC_EXTRAS_DISCARD_LOCAL_DELETIONS
SyncResult.tooManyDeletions
public static final String SYNC_EXTRAS_EXPECTED_UPLOAD
public static final String SYNC_EXTRAS_EXPECTED_DOWNLOAD
public static final String SYNC_EXTRAS_PRIORITY
public static final String SYNC_EXTRAS_DISALLOW_METERED
public static final String SYNC_EXTRAS_INITIALIZE
#setIsSyncable(android.accounts.Account, String, int)
has been
called with a >= 0 value. When this flag is set the SyncAdapter does not need to
do a full sync, though it is allowed to do so.public static final Intent ACTION_SYNC_CONN_STATUS_CHANGED
public static final String SCHEME_CONTENT
public static final String SCHEME_ANDROID_RESOURCE
public static final String SCHEME_FILE
public static final String EXTRA_SIZE
Point
describing the optimal size for a requested image
resource, in pixels. If a provider has multiple sizes of the image, it
should return the image closest to this size.public static final String CURSOR_ITEM_BASE_TYPE
content://com.company.provider.imap/inbox/1
for a particular
message in the inbox, whose MIME type would be reported as
CURSOR_ITEM_BASE_TYPE + "/vnd.company.imap-msg"
Compare with CURSOR_DIR_BASE_TYPE
.
public static final String CURSOR_DIR_BASE_TYPE
content://com.company.provider.imap/inbox
for all of the
messages in its inbox, whose MIME type would be reported as
CURSOR_DIR_BASE_TYPE + "/vnd.company.imap-msg"
Note how the base MIME type varies between this and
CURSOR_ITEM_BASE_TYPE
depending on whether there is
one single item or multiple items in the data set, while the sub-type
remains the same because in either case the data structure contained
in the cursor is the same.
public static final String ANY_CURSOR_ITEM_TYPE
CURSOR_ITEM_BASE_TYPE
/SUB_TYPE
".
SUB_TYPE
is the sub-type of the application-dependent
content, e.g., "audio", "video", "playlist".public static final int SYNC_ERROR_SYNC_ALREADY_IN_PROGRESS
public static final int SYNC_ERROR_AUTHENTICATION
public static final int SYNC_ERROR_IO
public static final int SYNC_ERROR_PARSE
public static final int SYNC_ERROR_CONFLICT
public static final int SYNC_ERROR_TOO_MANY_DELETIONS
public static final int SYNC_ERROR_TOO_MANY_RETRIES
public static final int SYNC_ERROR_INTERNAL
public static final int SYNC_OBSERVER_TYPE_SETTINGS
public static final int SYNC_OBSERVER_TYPE_PENDING
public static final int SYNC_OBSERVER_TYPE_ACTIVE
public static final int SYNC_OBSERVER_TYPE_STATUS
public static final int SYNC_OBSERVER_TYPE_ALL
public static final int NOTIFY_SYNC_TO_NETWORK
notifyChange(Uri, ContentObserver, int)
: attempt to sync the change
to the network.public static final int NOTIFY_SKIP_NOTIFY_FOR_DESCENDANTS
notifyChange(Uri, ContentObserver, int)
: if set, this notification
will be skipped if it is being delivered to the root URI of a ContentObserver that is
using "notify for descendants." The purpose of this is to allow the provide to send
a general notification of "something under X" changed that observers of that specific
URI can receive, while also sending a specific URI under X. It would use this flag
when sending the former, so that observers of "X and descendants" only see the latter.public static final String CONTENT_SERVICE_NAME
public ContentResolver(Context context)
public static String syncErrorToString(int error)
public static int syncErrorStringToInt(String error)
protected abstract IContentProvider acquireProvider(Context c, String name)
protected IContentProvider acquireExistingProvider(Context c, String name)
public abstract boolean releaseProvider(IContentProvider icp)
protected abstract IContentProvider acquireUnstableProvider(Context c, String name)
public abstract boolean releaseUnstableProvider(IContentProvider icp)
public abstract void unstableProviderDied(IContentProvider icp)
public void appNotRespondingViaProvider(IContentProvider icp)
public final String getType(Uri url)
url
- A Uri identifying content (either a list or specific type),
using the content:// scheme.public String[] getStreamTypes(Uri url, String mimeTypeFilter)
openTypedAssetFileDescriptor(android.net.Uri, java.lang.String, android.os.Bundle)
. Note that the types here are
not necessarily a superset of the type returned by getType(android.net.Uri)
--
many content providers cannot return a raw stream for the structured
data that they contain.url
- A Uri identifying content (either a list or specific type),
using the content:// scheme.mimeTypeFilter
- The desired MIME type. This may be a pattern,
such as */*, to query for all available MIME types that match the
pattern.public final Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)
Cursor
over the result set.
For best performance, the caller should follow these guidelines:
selection
parameter, so that queries
that differ only by those values will be recognized as the same
for caching purposes.uri
- The URI, using the content:// scheme, for the content to
retrieve.projection
- A list of which columns to return. Passing null will
return all columns, which is inefficient.selection
- A filter declaring which rows to return, formatted as an
SQL WHERE clause (excluding the WHERE itself). Passing null will
return all rows for the given URI.selectionArgs
- You may include ?s in selection, which will be
replaced by the values from selectionArgs, in the order that they
appear in the selection. The values will be bound as Strings.sortOrder
- How to order the rows, formatted as an SQL ORDER BY
clause (excluding the ORDER BY itself). Passing null will use the
default sort order, which may be unordered.Cursor
public final Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal)
Cursor
over the result set
with optional support for cancellation.
For best performance, the caller should follow these guidelines:
selection
parameter, so that queries
that differ only by those values will be recognized as the same
for caching purposes.uri
- The URI, using the content:// scheme, for the content to
retrieve.projection
- A list of which columns to return. Passing null will
return all columns, which is inefficient.selection
- A filter declaring which rows to return, formatted as an
SQL WHERE clause (excluding the WHERE itself). Passing null will
return all rows for the given URI.selectionArgs
- You may include ?s in selection, which will be
replaced by the values from selectionArgs, in the order that they
appear in the selection. The values will be bound as Strings.sortOrder
- How to order the rows, formatted as an SQL ORDER BY
clause (excluding the ORDER BY itself). Passing null will use the
default sort order, which may be unordered.cancellationSignal
- A signal to cancel the operation in progress, or null if none.
If the operation is canceled, then OperationCanceledException
will be thrown
when the query is executed.Cursor
public final Uri canonicalize(Uri url)
query(android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String)
, openInputStream(android.net.Uri)
, etc. The
only difference in behavior between the original and new Uris is that
the content provider may need to do some additional work at each call
using it to resolve it to the correct resource, especially if the
canonical Uri has been moved to a different environment.
If you are moving a canonical Uri between environments, you should
perform another call to canonicalize(android.net.Uri)
with that original Uri to
re-canonicalize it for the current environment. Alternatively, you may
want to use uncanonicalize(android.net.Uri)
to transform it to a non-canonical
Uri that works only in the current environment but potentially more
efficiently than the canonical representation.
url
- The Uri
that is to be transformed to a canonical
representation. Like all resolver calls, the input can be either
a non-canonical or canonical Uri.uncanonicalize(android.net.Uri)
public final Uri uncanonicalize(Uri url)
canonicalize(android.net.Uri)
, convert
it to its local non-canonical form. This can be useful in some cases where
you know that you will only be using the Uri in the current environment and
want to avoid any possible overhead when using it with the content
provider or want to verify that the referenced data exists at all in the
new environment.url
- The canonical Uri
that is to be convered back to its
non-canonical form.canonicalize(android.net.Uri)
public final InputStream openInputStream(Uri uri) throws FileNotFoundException
SCHEME_CONTENT
)SCHEME_ANDROID_RESOURCE
)SCHEME_FILE
)See openAssetFileDescriptor(Uri, String)
for more information
on these schemes.
uri
- The desired URI.FileNotFoundException
- if the provided URI could not be opened.openAssetFileDescriptor(Uri, String)
public final OutputStream openOutputStream(Uri uri) throws FileNotFoundException
openOutputStream(uri, "w")
.FileNotFoundException
- if the provided URI could not be opened.public final OutputStream openOutputStream(Uri uri, String mode) throws FileNotFoundException
SCHEME_CONTENT
)SCHEME_FILE
)See openAssetFileDescriptor(Uri, String)
for more information
on these schemes.
uri
- The desired URI.mode
- May be "w", "wa", "rw", or "rwt".FileNotFoundException
- if the provided URI could not be opened.openAssetFileDescriptor(Uri, String)
public final ParcelFileDescriptor openFileDescriptor(Uri uri, String mode) throws FileNotFoundException
openAssetFileDescriptor(Uri, String)
, but uses the
underlying ContentProvider.openFile(android.net.Uri, java.lang.String)
ContentProvider.openFile()} method, so will not work with
providers that return sub-sections of files. If at all possible,
you should use openAssetFileDescriptor(Uri, String)
. You
will receive a FileNotFoundException exception if the provider returns a
sub-section of a file.
SCHEME_CONTENT
)SCHEME_FILE
)See openAssetFileDescriptor(Uri, String)
for more information
on these schemes.
If opening with the exclusive "r" or "w" modes, the returned
ParcelFileDescriptor could be a pipe or socket pair to enable streaming
of data. Opening with the "rw" mode implies a file on disk that supports
seeking. If possible, always use an exclusive mode to give the underlying
ContentProvider
the most flexibility.
If you are writing a file, and need to communicate an error to the
provider, use ParcelFileDescriptor.closeWithError(String)
.
uri
- The desired URI to open.mode
- The file mode to use, as per ContentProvider.openFile
.FileNotFoundException
- Throws FileNotFoundException if no
file exists under the URI or the mode is invalid.openAssetFileDescriptor(Uri, String)
public final ParcelFileDescriptor openFileDescriptor(Uri uri, String mode, CancellationSignal cancellationSignal) throws FileNotFoundException
openAssetFileDescriptor(Uri, String)
, but uses the
underlying ContentProvider.openFile(android.net.Uri, java.lang.String)
ContentProvider.openFile()} method, so will not work with
providers that return sub-sections of files. If at all possible,
you should use openAssetFileDescriptor(Uri, String)
. You
will receive a FileNotFoundException exception if the provider returns a
sub-section of a file.
SCHEME_CONTENT
)SCHEME_FILE
)See openAssetFileDescriptor(Uri, String)
for more information
on these schemes.
If opening with the exclusive "r" or "w" modes, the returned
ParcelFileDescriptor could be a pipe or socket pair to enable streaming
of data. Opening with the "rw" mode implies a file on disk that supports
seeking. If possible, always use an exclusive mode to give the underlying
ContentProvider
the most flexibility.
If you are writing a file, and need to communicate an error to the
provider, use ParcelFileDescriptor.closeWithError(String)
.
uri
- The desired URI to open.mode
- The file mode to use, as per ContentProvider.openFile
.cancellationSignal
- A signal to cancel the operation in progress,
or null if none. If the operation is canceled, then
OperationCanceledException
will be thrown.FileNotFoundException
- Throws FileNotFoundException if no
file exists under the URI or the mode is invalid.openAssetFileDescriptor(Uri, String)
public final AssetFileDescriptor openAssetFileDescriptor(Uri uri, String mode) throws FileNotFoundException
ContentProvider.openAssetFile(android.net.Uri, java.lang.String)
method of the provider associated with the given URI, to retrieve any file stored there.
SCHEME_CONTENT
)SCHEME_ANDROID_RESOURCE
)SCHEME_FILE
)SCHEME_ANDROID_RESOURCE
) SchemeA Uri object can be used to reference a resource in an APK file. The Uri should be one of the following formats:
android.resource://package_name/id_number
package_name
is your package name as listed in your AndroidManifest.xml.
For example com.example.myapp
id_number
is the int form of the ID.Uri uri = Uri.parse("android.resource://com.example.myapp/" + R.raw.my_resource");
android.resource://package_name/type/name
package_name
is your package name as listed in your AndroidManifest.xml.
For example com.example.myapp
type
is the string form of the resource type. For example, raw
or drawable
.
name
is the string form of the resource name. That is, whatever the file
name was in your res directory, without the type extension.
The easiest way to construct this form is
Uri uri = Uri.parse("android.resource://com.example.myapp/raw/my_resource");
Note that if this function is called for read-only input (mode is "r")
on a content: URI, it will instead call openTypedAssetFileDescriptor(android.net.Uri, java.lang.String, android.os.Bundle)
for you with a MIME type of "*/*". This allows such callers to benefit
from any built-in data conversion that a provider implements.
uri
- The desired URI to open.mode
- The file mode to use, as per ContentProvider.openAssetFile
.FileNotFoundException
- Throws FileNotFoundException of no
file exists under the URI or the mode is invalid.public final AssetFileDescriptor openAssetFileDescriptor(Uri uri, String mode, CancellationSignal cancellationSignal) throws FileNotFoundException
ContentProvider.openAssetFile(android.net.Uri, java.lang.String)
method of the provider associated with the given URI, to retrieve any file stored there.
SCHEME_CONTENT
)SCHEME_ANDROID_RESOURCE
)SCHEME_FILE
)SCHEME_ANDROID_RESOURCE
) SchemeA Uri object can be used to reference a resource in an APK file. The Uri should be one of the following formats:
android.resource://package_name/id_number
package_name
is your package name as listed in your AndroidManifest.xml.
For example com.example.myapp
id_number
is the int form of the ID.Uri uri = Uri.parse("android.resource://com.example.myapp/" + R.raw.my_resource");
android.resource://package_name/type/name
package_name
is your package name as listed in your AndroidManifest.xml.
For example com.example.myapp
type
is the string form of the resource type. For example, raw
or drawable
.
name
is the string form of the resource name. That is, whatever the file
name was in your res directory, without the type extension.
The easiest way to construct this form is
Uri uri = Uri.parse("android.resource://com.example.myapp/raw/my_resource");
Note that if this function is called for read-only input (mode is "r")
on a content: URI, it will instead call openTypedAssetFileDescriptor(android.net.Uri, java.lang.String, android.os.Bundle)
for you with a MIME type of "*/*". This allows such callers to benefit
from any built-in data conversion that a provider implements.
uri
- The desired URI to open.mode
- The file mode to use, as per ContentProvider.openAssetFile
.cancellationSignal
- A signal to cancel the operation in progress, or null if
none. If the operation is canceled, then
OperationCanceledException
will be thrown.FileNotFoundException
- Throws FileNotFoundException of no
file exists under the URI or the mode is invalid.public final AssetFileDescriptor openTypedAssetFileDescriptor(Uri uri, String mimeType, Bundle opts) throws FileNotFoundException
ContentProvider.openTypedAssetFile(android.net.Uri, java.lang.String, android.os.Bundle)
method of the provider
associated with the given URI, to retrieve retrieve any appropriate
data stream for the data stored there.
Unlike openAssetFileDescriptor(android.net.Uri, java.lang.String)
, this function only works
with "content:" URIs, because content providers are the only facility
with an associated MIME type to ensure that the returned data stream
is of the desired type.
All text/* streams are encoded in UTF-8.
uri
- The desired URI to open.mimeType
- The desired MIME type of the returned data. This can
be a pattern such as */*, which will allow the content provider to
select a type, though there is no way for you to determine what type
it is returning.opts
- Additional provider-dependent options.FileNotFoundException
- Throws FileNotFoundException of no
data of the desired type exists under the URI.public final AssetFileDescriptor openTypedAssetFileDescriptor(Uri uri, String mimeType, Bundle opts, CancellationSignal cancellationSignal) throws FileNotFoundException
ContentProvider.openTypedAssetFile(android.net.Uri, java.lang.String, android.os.Bundle)
method of the provider
associated with the given URI, to retrieve retrieve any appropriate
data stream for the data stored there.
Unlike openAssetFileDescriptor(android.net.Uri, java.lang.String)
, this function only works
with "content:" URIs, because content providers are the only facility
with an associated MIME type to ensure that the returned data stream
is of the desired type.
All text/* streams are encoded in UTF-8.
uri
- The desired URI to open.mimeType
- The desired MIME type of the returned data. This can
be a pattern such as */*, which will allow the content provider to
select a type, though there is no way for you to determine what type
it is returning.opts
- Additional provider-dependent options.cancellationSignal
- A signal to cancel the operation in progress,
or null if none. If the operation is canceled, then
OperationCanceledException
will be thrown.FileNotFoundException
- Throws FileNotFoundException of no
data of the desired type exists under the URI.public ContentResolver.OpenResourceIdResult getResourceId(Uri uri) throws FileNotFoundException
Resources
and a resource id.FileNotFoundException
public final Uri insert(Uri url, ContentValues values)
url
- The URL of the table to insert into.values
- The initial values for the newly inserted row. The key is the column name for
the field. Passing an empty ContentValues will create an empty row.public ContentProviderResult[] applyBatch(String authority, ArrayList<ContentProviderOperation> operations) throws RemoteException, OperationApplicationException
ContentProviderOperation
objects and returns an array
of their results. Passes through OperationApplicationException, which may be thrown
by the call to ContentProviderOperation.apply(android.content.ContentProvider, android.content.ContentProviderResult[], int)
.
If all the applications succeed then a ContentProviderResult
array with the
same number of elements as the operations will be returned. It is implementation-specific
how many, if any, operations will have been successfully applied if a call to
apply results in a OperationApplicationException
.authority
- the authority of the ContentProvider to which this batch should be appliedoperations
- the operations to applyOperationApplicationException
- thrown if an application fails.
See ContentProviderOperation.apply(android.content.ContentProvider, android.content.ContentProviderResult[], int)
for more information.RemoteException
- thrown if a RemoteException is encountered while attempting
to communicate with a remote provider.public final int bulkInsert(Uri url, ContentValues[] values)
url
- The URL of the table to insert into.values
- The initial values for the newly inserted rows. The key is the column name for
the field. Passing null will create an empty row.public final int delete(Uri url, String where, String[] selectionArgs)
url
- The URL of the row to delete.where
- A filter to apply to rows before deleting, formatted as an SQL WHERE clause
(excluding the WHERE itself).public final int update(Uri uri, ContentValues values, String where, String[] selectionArgs)
uri
- The URI to modify.values
- The new field values. The key is the column name for the field.
A null value will remove an existing field value.where
- A filter to apply to rows before updating, formatted as an SQL WHERE clause
(excluding the WHERE itself).NullPointerException
- if uri or values are nullpublic final Bundle call(Uri uri, String method, String arg, Bundle extras)
method
- provider-defined method name to call. Opaque to
framework, but must be non-null.arg
- provider-defined String argument. May be null.extras
- provider-defined Bundle argument. May be null.NullPointerException
- if uri or method is nullIllegalArgumentException
- if uri is not knownpublic final IContentProvider acquireProvider(Uri uri)
uri
- The URI to a content providerpublic final IContentProvider acquireExistingProvider(Uri uri)
uri
- The URI to a content providerpublic final IContentProvider acquireProvider(String name)
public final IContentProvider acquireUnstableProvider(Uri uri)
uri
- The URI to a content providerpublic final IContentProvider acquireUnstableProvider(String name)
public final ContentProviderClient acquireContentProviderClient(Uri uri)
ContentProviderClient
that is associated with the ContentProvider
that services the content at uri, starting the provider if necessary. Returns
null if there is no provider associated wih the uri. The caller must indicate that they are
done with the provider by calling ContentProviderClient.release()
which will allow
the system to release the provider it it determines that there is no other reason for
keeping it active.uri
- specifies which provider should be acquiredContentProviderClient
that is associated with the ContentProvider
that services the content at uri or null if there isn't one.public final ContentProviderClient acquireContentProviderClient(String name)
ContentProviderClient
that is associated with the ContentProvider
with the authority of name, starting the provider if necessary. Returns
null if there is no provider associated wih the uri. The caller must indicate that they are
done with the provider by calling ContentProviderClient.release()
which will allow
the system to release the provider it it determines that there is no other reason for
keeping it active.name
- specifies which provider should be acquiredContentProviderClient
that is associated with the ContentProvider
with the authority of name or null if there isn't one.public final ContentProviderClient acquireUnstableContentProviderClient(Uri uri)
acquireContentProviderClient(Uri)
, but for use when you do
not trust the stability of the target content provider. This turns off
the mechanism in the platform clean up processes that are dependent on
a content provider if that content provider's process goes away. Normally
you can safely assume that once you have acquired a provider, you can freely
use it as needed and it won't disappear, even if your process is in the
background. If using this method, you need to take care to deal with any
failures when communicating with the provider, and be sure to close it
so that it can be re-opened later. In particular, catching a
DeadObjectException
from the calls there will let you
know that the content provider has gone away; at that point the current
ContentProviderClient object is invalid, and you should release it. You
can acquire a new one if you would like to try to restart the provider
and perform new operations on it.public final ContentProviderClient acquireUnstableContentProviderClient(String name)
acquireContentProviderClient(String)
, but for use when you do
not trust the stability of the target content provider. This turns off
the mechanism in the platform clean up processes that are dependent on
a content provider if that content provider's process goes away. Normally
you can safely assume that once you have acquired a provider, you can freely
use it as needed and it won't disappear, even if your process is in the
background. If using this method, you need to take care to deal with any
failures when communicating with the provider, and be sure to close it
so that it can be re-opened later. In particular, catching a
DeadObjectException
from the calls there will let you
know that the content provider has gone away; at that point the current
ContentProviderClient object is invalid, and you should release it. You
can acquire a new one if you would like to try to restart the provider
and perform new operations on it.public final void registerContentObserver(Uri uri, boolean notifyForDescendants, ContentObserver observer)
uri
- The URI to watch for changes. This can be a specific row URI, or a base URI
for a whole class of content.notifyForDescendants
- When false, the observer will be notified whenever a
change occurs to the exact URI specified by uri
or to one of the
URI's ancestors in the path hierarchy. When true, the observer will also be notified
whenever a change occurs to the URI's descendants in the path hierarchy.observer
- The object that receives callbacks when changes occur.unregisterContentObserver(android.database.ContentObserver)
public final void registerContentObserver(Uri uri, boolean notifyForDescendents, ContentObserver observer, int userHandle)
public final void unregisterContentObserver(ContentObserver observer)
observer
- The previously registered observer that is no longer needed.registerContentObserver(android.net.Uri, boolean, android.database.ContentObserver)
public void notifyChange(Uri uri, ContentObserver observer)
registerContentObserver()
.
By default, CursorAdapter objects will get this notification.uri
- The uri of the content that was changed.observer
- The observer that originated the change, may be null.
The observer that originated the change will only receive the notification if it
has requested to receive self-change notifications by implementing
ContentObserver.deliverSelfNotifications()
to return true.
public void notifyChange(Uri uri, ContentObserver observer, boolean syncToNetwork)
registerContentObserver()
.
By default, CursorAdapter objects will get this notification.
If syncToNetwork is true, this will attempt to schedule a local sync using the sync
adapter that's registered for the authority of the provided uri. No account will be
passed to the sync adapter, so all matching accounts will be synchronized.uri
- The uri of the content that was changed.observer
- The observer that originated the change, may be null.
The observer that originated the change will only receive the notification if it
has requested to receive self-change notifications by implementing
ContentObserver.deliverSelfNotifications()
to return true.
syncToNetwork
- If true, same as NOTIFY_SYNC_TO_NETWORK
.#requestSync(android.accounts.Account, String, android.os.Bundle)
public void notifyChange(Uri uri, ContentObserver observer, int flags)
registerContentObserver()
.
By default, CursorAdapter objects will get this notification.
If syncToNetwork is true, this will attempt to schedule a local sync using the sync
adapter that's registered for the authority of the provided uri. No account will be
passed to the sync adapter, so all matching accounts will be synchronized.uri
- The uri of the content that was changed.observer
- The observer that originated the change, may be null.
The observer that originated the change will only receive the notification if it
has requested to receive self-change notifications by implementing
ContentObserver.deliverSelfNotifications()
to return true.
flags
- Additional flags: NOTIFY_SYNC_TO_NETWORK
.#requestSync(android.accounts.Account, String, android.os.Bundle)
public void notifyChange(Uri uri, ContentObserver observer, boolean syncToNetwork, int userHandle)
public void notifyChange(Uri uri, ContentObserver observer, int flags, int userHandle)
public void takePersistableUriPermission(Uri uri, int modeFlags)
Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION
can be persisted. If
the grant has already been persisted, taking it again will touch
UriPermission.getPersistedTime()
.getPersistedUriPermissions()
public void releasePersistableUriPermission(Uri uri, int modeFlags)
takePersistableUriPermission(Uri, int)
. Any non-persistent
grants to the calling package will remain intact.getPersistedUriPermissions()
public List<UriPermission> getPersistedUriPermissions()
takePersistableUriPermission(Uri, int)
are returned.
Note: Some of the returned URIs may not be usable until after the user is unlocked.
public List<UriPermission> getOutgoingPersistedUriPermissions()
takePersistableUriPermission(Uri, int)
are returned.
Note: Some of the returned URIs may not be usable until after the user is unlocked.
@Deprecated public void startSync(Uri uri, Bundle extras)
#requestSync(android.accounts.Account, String, android.os.Bundle)
uri
- the uri of the provider to sync or null to sync all providers.extras
- any extras to pass to the SyncAdapter.public static void requestSync(Account account, String authority, Bundle extras)
account
- which account should be syncedauthority
- which authority should be syncedextras
- any extras to pass to the SyncAdapter.public static void requestSyncAsUser(Account account, String authority, int userId, Bundle extras)
requestSync(Account, String, Bundle)
public static void requestSync(SyncRequest request)
SyncRequest.Builder
.public static void validateSyncExtrasBundle(Bundle extras)
extras
- the Bundle to check@Deprecated public void cancelSync(Uri uri)
#cancelSync(android.accounts.Account, String)
uri
- the uri of the provider to sync or null to sync all providers.public static void cancelSync(Account account, String authority)
account
- filters the syncs that match by this accountauthority
- filters the syncs that match by this authoritypublic static void cancelSyncAsUser(Account account, String authority, int userId)
cancelSync(Account, String)
public static SyncAdapterType[] getSyncAdapterTypes()
public static SyncAdapterType[] getSyncAdapterTypesAsUser(int userId)
getSyncAdapterTypes()
public static String[] getSyncAdapterPackagesForAuthorityAsUser(String authority, int userId)
public static boolean getSyncAutomatically(Account account, String authority)
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_SETTINGS
.
account
- the account whose setting we are queryingauthority
- the provider whose setting we are queryingpublic static boolean getSyncAutomaticallyAsUser(Account account, String authority, int userId)
getSyncAutomatically(Account, String)
public static void setSyncAutomatically(Account account, String authority, boolean sync)
This method requires the caller to hold the permission
android.Manifest.permission#WRITE_SYNC_SETTINGS
.
account
- the account whose setting we are queryingauthority
- the provider whose behavior is being controlledsync
- true if the provider should be synced when tickles are received for itpublic static void setSyncAutomaticallyAsUser(Account account, String authority, boolean sync, int userId)
public static void addPeriodicSync(Account account, String authority, Bundle extras, long pollFrequency)
These periodic syncs honor the "syncAutomatically" and "masterSyncAutomatically" settings. Although these sync are scheduled at the specified frequency, it may take longer for it to actually be started if other syncs are ahead of it in the sync operation queue. This means that the actual start time may drift.
Periodic syncs are not allowed to have any of SYNC_EXTRAS_DO_NOT_RETRY
,
SYNC_EXTRAS_IGNORE_BACKOFF
, SYNC_EXTRAS_IGNORE_SETTINGS
,
SYNC_EXTRAS_INITIALIZE
, SYNC_EXTRAS_FORCE
,
SYNC_EXTRAS_EXPEDITED
, SYNC_EXTRAS_MANUAL
set to true.
If any are supplied then an IllegalArgumentException
will be thrown.
This method requires the caller to hold the permission
android.Manifest.permission#WRITE_SYNC_SETTINGS
.
The bundle for a periodic sync can be queried by applications with the correct
permissions using
getPeriodicSyncs(Account account, String provider)
, so no
sensitive data should be transferred here.
account
- the account to specify in the syncauthority
- the provider to specify in the sync requestextras
- extra parameters to go along with the sync requestpollFrequency
- how frequently the sync should be performed, in seconds. A minimum value
of 1 hour is enforced.IllegalArgumentException
- if an illegal extra was set or if any of the parameters
are null.public static boolean invalidPeriodicExtras(Bundle extras)
IllegalArgumentException
if any illegal
extras were set for a periodic sync.extras
- bundle to validate.public static void removePeriodicSync(Account account, String authority, Bundle extras)
This method requires the caller to hold the permission
android.Manifest.permission#WRITE_SYNC_SETTINGS
.
account
- the account of the periodic sync to removeauthority
- the provider of the periodic sync to removeextras
- the extras of the periodic sync to removepublic static void cancelSync(SyncRequest request)
If a periodic sync is specified, the caller must hold the permission
android.Manifest.permission#WRITE_SYNC_SETTINGS
.
request
- SyncRequest object containing information about sync to cancel.public static List<PeriodicSync> getPeriodicSyncs(Account account, String authority)
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_SETTINGS
.
account
- the account whose periodic syncs we are queryingauthority
- the provider whose periodic syncs we are queryingpublic static int getIsSyncable(Account account, String authority)
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_SETTINGS
.
public static int getIsSyncableAsUser(Account account, String authority, int userId)
getIsSyncable(Account, String)
public static void setIsSyncable(Account account, String authority, int syncable)
This method requires the caller to hold the permission
android.Manifest.permission#WRITE_SYNC_SETTINGS
.
syncable
- >0 denotes syncable, 0 means not syncable, <0 means unknownpublic static boolean getMasterSyncAutomatically()
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_SETTINGS
.
public static boolean getMasterSyncAutomaticallyAsUser(int userId)
getMasterSyncAutomatically()
public static void setMasterSyncAutomatically(boolean sync)
This method requires the caller to hold the permission
android.Manifest.permission#WRITE_SYNC_SETTINGS
.
sync
- the master auto-sync setting that applies to all the providers and accountspublic static void setMasterSyncAutomaticallyAsUser(boolean sync, int userId)
setMasterSyncAutomatically(boolean)
public static boolean isSyncActive(Account account, String authority)
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_STATS
.
account
- the account whose setting we are queryingauthority
- the provider whose behavior is being queried@Deprecated public static SyncInfo getCurrentSync()
getCurrentSyncs()
to get the accurate list of current syncs.
This method returns the first item from the list of current syncs
or null if there are none.
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_STATS
.
public static List<SyncInfo> getCurrentSyncs()
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_STATS
.
public static List<SyncInfo> getCurrentSyncsAsUser(int userId)
getCurrentSyncs()
public static SyncStatusInfo getSyncStatus(Account account, String authority)
account
- the account whose setting we are queryingauthority
- the provider whose behavior is being queriedpublic static SyncStatusInfo getSyncStatusAsUser(Account account, String authority, int userId)
getSyncStatus(Account, String)
public static boolean isSyncPending(Account account, String authority)
This method requires the caller to hold the permission
android.Manifest.permission#READ_SYNC_STATS
.
account
- the account whose setting we are queryingauthority
- the provider whose behavior is being queriedpublic static boolean isSyncPendingAsUser(Account account, String authority, int userId)
requestSync(Account, String, Bundle)
public static Object addStatusChangeListener(int mask, SyncStatusObserver callback)
mask
- the status change types that will cause the callback to be invokedcallback
- observer to be invoked when the status changespublic static void removeStatusChangeListener(Object handle)
handle
- the handle that was returned by addStatusChangeListener(int, android.content.SyncStatusObserver)
public static IContentService getContentService()
public String getPackageName()
public int resolveUserId(Uri uri)