RingtoneManager
public
class
RingtoneManager
extends Object
java.lang.Object | |
↳ | android.media.RingtoneManager |
RingtoneManager provides access to ringtones, notification, and other types
of sounds. It manages querying the different media providers and combines the
results into a single cursor. It also provides a Ringtone
for each
ringtone. We generically call these sounds ringtones, however the
TYPE_RINGTONE
refers to the type of sounds that are suitable for the
phone ringer.
To show a ringtone picker to the user, use the
ACTION_RINGTONE_PICKER
intent to launch the picker as a subactivity.
See also:
Summary
Constants | |
---|---|
String |
ACTION_RINGTONE_PICKER
Activity Action: Shows a ringtone picker. |
String |
EXTRA_RINGTONE_DEFAULT_URI
Given to the ringtone picker as a |
String |
EXTRA_RINGTONE_EXISTING_URI
Given to the ringtone picker as a |
String |
EXTRA_RINGTONE_INCLUDE_DRM
This constant was deprecated in API level 19. DRM ringtones are no longer supported |
String |
EXTRA_RINGTONE_PICKED_URI
Returned from the ringtone picker as a |
String |
EXTRA_RINGTONE_SHOW_DEFAULT
Given to the ringtone picker as a boolean. |
String |
EXTRA_RINGTONE_SHOW_SILENT
Given to the ringtone picker as a boolean. |
String |
EXTRA_RINGTONE_TITLE
Given to the ringtone picker as a |
String |
EXTRA_RINGTONE_TYPE
Given to the ringtone picker as an int. |
int |
ID_COLUMN_INDEX
The column index (in the cursor returned by |
int |
TITLE_COLUMN_INDEX
The column index (in the cursor returned by |
int |
TYPE_ALARM
Type that refers to sounds that are used for the alarm. |
int |
TYPE_ALL
All types of sounds. |
int |
TYPE_NOTIFICATION
Type that refers to sounds that are used for notifications. |
int |
TYPE_RINGTONE
Type that refers to sounds that are used for the phone ringer. |
int |
URI_COLUMN_INDEX
The column index (in the cursor returned by |
Public constructors | |
---|---|
RingtoneManager(Activity activity)
Constructs a RingtoneManager. |
|
RingtoneManager(Context context)
Constructs a RingtoneManager. |
Public methods | |
---|---|
static
Uri
|
getActualDefaultRingtoneUri(Context context, int type)
Gets the current default sound's |
Cursor
|
getCursor()
Returns a |
static
int
|
getDefaultType(Uri defaultRingtoneUri)
Returns the type of a default |
static
Uri
|
getDefaultUri(int type)
Returns the |
boolean
|
getIncludeDrm()
This method was deprecated in API level 19. DRM ringtones are no longer supported |
static
Ringtone
|
getRingtone(Context context, Uri ringtoneUri)
Returns a |
Ringtone
|
getRingtone(int position)
Gets a |
int
|
getRingtonePosition(Uri ringtoneUri)
Gets the position of a |
Uri
|
getRingtoneUri(int position)
Gets a |
boolean
|
getStopPreviousRingtone()
|
static
Uri
|
getValidRingtoneUri(Context context)
Returns a valid ringtone URI. |
boolean
|
hasHapticChannels(int position)
Returns if the |
static
boolean
|
hasHapticChannels(Uri ringtoneUri)
Returns if the |
static
boolean
|
hasHapticChannels(Context context, Uri ringtoneUri)
Returns if the |
int
|
inferStreamType()
Infers the volume stream type based on what type of ringtones this manager is returning. |
static
boolean
|
isDefault(Uri ringtoneUri)
Returns whether the given |
static
AssetFileDescriptor
|
openDefaultRingtoneUri(Context context, Uri uri)
Opens a raw file descriptor to read the data under the given default URI. |
static
void
|
setActualDefaultRingtoneUri(Context context, int type, Uri ringtoneUri)
Sets the |
void
|
setIncludeDrm(boolean includeDrm)
This method was deprecated in API level 19. DRM ringtones are no longer supported |
void
|
setStopPreviousRingtone(boolean stopPreviousRingtone)
Whether retrieving another |
void
|
setType(int type)
Sets which type(s) of ringtones will be listed by this. |
void
|
stopPreviousRingtone()
Stops playing the last |
Inherited methods | |
---|---|
Constants
ACTION_RINGTONE_PICKER
public static final String ACTION_RINGTONE_PICKER
Activity Action: Shows a ringtone picker.
Input: EXTRA_RINGTONE_EXISTING_URI
,
EXTRA_RINGTONE_SHOW_DEFAULT
,
EXTRA_RINGTONE_SHOW_SILENT
, EXTRA_RINGTONE_TYPE
,
EXTRA_RINGTONE_DEFAULT_URI
, EXTRA_RINGTONE_TITLE
,
Output: EXTRA_RINGTONE_PICKED_URI
.
Constant Value: "android.intent.action.RINGTONE_PICKER"
EXTRA_RINGTONE_DEFAULT_URI
public static final String EXTRA_RINGTONE_DEFAULT_URI
Given to the ringtone picker as a Uri
. The Uri
of the
ringtone to play when the user attempts to preview the "Default"
ringtone. This can be one of System.DEFAULT_RINGTONE_URI
,
System.DEFAULT_NOTIFICATION_URI
, or
System.DEFAULT_ALARM_ALERT_URI
to have the "Default" point to
the current sound for the given default sound type. If you are showing a
ringtone picker for some other type of sound, you are free to provide any
Uri
here.
Constant Value: "android.intent.extra.ringtone.DEFAULT_URI"
EXTRA_RINGTONE_EXISTING_URI
public static final String EXTRA_RINGTONE_EXISTING_URI
Given to the ringtone picker as a Uri
. The Uri
of the
current ringtone, which will be used to show a checkmark next to the item
for this Uri
. If showing an item for "Default" (@see
EXTRA_RINGTONE_SHOW_DEFAULT
), this can also be one of
System.DEFAULT_RINGTONE_URI
,
System.DEFAULT_NOTIFICATION_URI
, or
System.DEFAULT_ALARM_ALERT_URI
to have the "Default" item
checked.
See also:
Constant Value: "android.intent.extra.ringtone.EXISTING_URI"
EXTRA_RINGTONE_INCLUDE_DRM
public static final String EXTRA_RINGTONE_INCLUDE_DRM
This constant was deprecated
in API level 19.
DRM ringtones are no longer supported
Given to the ringtone picker as a boolean. Whether to include DRM ringtones.
Constant Value: "android.intent.extra.ringtone.INCLUDE_DRM"
EXTRA_RINGTONE_PICKED_URI
public static final String EXTRA_RINGTONE_PICKED_URI
Returned from the ringtone picker as a Uri
.
It will be one of:
Uri
that equals System.DEFAULT_RINGTONE_URI
,
System.DEFAULT_NOTIFICATION_URI
, or
System.DEFAULT_ALARM_ALERT_URI
if the default was chosen,
See also:
Constant Value: "android.intent.extra.ringtone.PICKED_URI"
EXTRA_RINGTONE_SHOW_DEFAULT
public static final String EXTRA_RINGTONE_SHOW_DEFAULT
Given to the ringtone picker as a boolean. Whether to show an item for "Default".
See also:
Constant Value: "android.intent.extra.ringtone.SHOW_DEFAULT"
EXTRA_RINGTONE_SHOW_SILENT
public static final String EXTRA_RINGTONE_SHOW_SILENT
Given to the ringtone picker as a boolean. Whether to show an item for
"Silent". If the "Silent" item is picked,
EXTRA_RINGTONE_PICKED_URI
will be null.
See also:
Constant Value: "android.intent.extra.ringtone.SHOW_SILENT"
EXTRA_RINGTONE_TITLE
public static final String EXTRA_RINGTONE_TITLE
Given to the ringtone picker as a CharSequence
. The title to
show for the ringtone picker. This has a default value that is suitable
in most cases.
Constant Value: "android.intent.extra.ringtone.TITLE"
EXTRA_RINGTONE_TYPE
public static final String EXTRA_RINGTONE_TYPE
Given to the ringtone picker as an int. Specifies which ringtone type(s) should be
shown in the picker. One or more of TYPE_RINGTONE
,
TYPE_NOTIFICATION
, TYPE_ALARM
, or TYPE_ALL
(bitwise-ored together).
Constant Value: "android.intent.extra.ringtone.TYPE"
ID_COLUMN_INDEX
public static final int ID_COLUMN_INDEX
The column index (in the cursor returned by getCursor()
for the
row ID.
Constant Value: 0 (0x00000000)
TITLE_COLUMN_INDEX
public static final int TITLE_COLUMN_INDEX
The column index (in the cursor returned by getCursor()
for the
title.
Constant Value: 1 (0x00000001)
TYPE_ALARM
public static final int TYPE_ALARM
Type that refers to sounds that are used for the alarm.
Constant Value: 4 (0x00000004)
TYPE_ALL
public static final int TYPE_ALL
All types of sounds.
Constant Value: 7 (0x00000007)
TYPE_NOTIFICATION
public static final int TYPE_NOTIFICATION
Type that refers to sounds that are used for notifications.
Constant Value: 2 (0x00000002)
TYPE_RINGTONE
public static final int TYPE_RINGTONE
Type that refers to sounds that are used for the phone ringer.
Constant Value: 1 (0x00000001)
URI_COLUMN_INDEX
public static final int URI_COLUMN_INDEX
The column index (in the cursor returned by getCursor()
for the
media provider's URI.
Constant Value: 2 (0x00000002)
Public constructors
RingtoneManager
public RingtoneManager (Activity activity)
Constructs a RingtoneManager. This constructor is recommended as its constructed instance manages cursor(s).
Parameters | |
---|---|
activity |
Activity : The activity used to get a managed cursor. |
RingtoneManager
public RingtoneManager (Context context)
Constructs a RingtoneManager. The instance constructed by this constructor will not manage the cursor(s), so the client should handle this itself.
Parameters | |
---|---|
context |
Context : The context to used to get a cursor. |
Public methods
getActualDefaultRingtoneUri
public static Uri getActualDefaultRingtoneUri (Context context, int type)
Gets the current default sound's Uri
. This will give the actual
sound Uri
, instead of using this, most clients can use
System.DEFAULT_RINGTONE_URI
.
Parameters | |
---|---|
context |
Context : A context used for querying. |
type |
int : The type whose default sound should be returned. One of
TYPE_RINGTONE , TYPE_NOTIFICATION , or
TYPE_ALARM . |
Returns | |
---|---|
Uri |
A Uri pointing to the default sound for the sound type. |
getCursor
public Cursor getCursor ()
Returns a Cursor
of all the ringtones available. The returned
cursor will be the same cursor returned each time this method is called,
so do not Cursor.close()
the cursor. The cursor can be
Cursor.deactivate()
safely.
If RingtoneManager.RingtoneManager(Activity)
was not used, the
caller should manage the returned cursor through its activity's life
cycle to prevent leaking the cursor.
Note that the list of ringtones available will differ depending on whether the caller
has the Manifest.permission.READ_EXTERNAL_STORAGE
permission.
Returns | |
---|---|
Cursor |
A Cursor of all the ringtones available. |
getDefaultType
public static int getDefaultType (Uri defaultRingtoneUri)
Returns the type of a default Uri
.
Parameters | |
---|---|
defaultRingtoneUri |
Uri : The default Uri . For example,
System.DEFAULT_RINGTONE_URI ,
System.DEFAULT_NOTIFICATION_URI , or
System.DEFAULT_ALARM_ALERT_URI . |
Returns | |
---|---|
int |
The type of the defaultRingtoneUri, or -1. |
getDefaultUri
public static Uri getDefaultUri (int type)
Returns the Uri
for the default ringtone of a particular type.
Rather than returning the actual ringtone's sound Uri
, this will
return the symbolic Uri
which will resolved to the actual sound
when played.
Parameters | |
---|---|
type |
int : The ringtone type whose default should be returned. |
Returns | |
---|---|
Uri |
The Uri of the default ringtone for the given type. |
getIncludeDrm
public boolean getIncludeDrm ()
This method was deprecated
in API level 19.
DRM ringtones are no longer supported
Returns whether DRM ringtones will be included.
Returns | |
---|---|
boolean |
Whether DRM ringtones will be included. |
See also:
getRingtone
public static Ringtone getRingtone (Context context, Uri ringtoneUri)
Returns a Ringtone
for a given sound URI.
If the given URI cannot be opened for any reason, this method will attempt to fallback on another sound. If it cannot find any, it will return null.
Parameters | |
---|---|
context |
Context : A context used to query. |
ringtoneUri |
Uri : The Uri of a sound or ringtone. |
Returns | |
---|---|
Ringtone |
A Ringtone for the given URI, or null. |
getRingtone
public Ringtone getRingtone (int position)
Gets a Ringtone
for the ringtone at the given position in the
Cursor
.
Parameters | |
---|---|
position |
int : The position (in the Cursor ) of the ringtone. |
Returns | |
---|---|
Ringtone |
A Ringtone pointing to the ringtone. |
getRingtonePosition
public int getRingtonePosition (Uri ringtoneUri)
Gets the position of a Uri
within this RingtoneManager
.
Parameters | |
---|---|
ringtoneUri |
Uri : The Uri to retreive the position of. |
Returns | |
---|---|
int |
The position of the Uri , or -1 if it cannot be found. |
getRingtoneUri
public Uri getRingtoneUri (int position)
Gets a Uri
for the ringtone at the given position in the Cursor
.
Parameters | |
---|---|
position |
int : The position (in the Cursor ) of the ringtone. |
Returns | |
---|---|
Uri |
A Uri pointing to the ringtone. |
getStopPreviousRingtone
public boolean getStopPreviousRingtone ()
Returns | |
---|---|
boolean |
See also:
getValidRingtoneUri
public static Uri getValidRingtoneUri (Context context)
Returns a valid ringtone URI. No guarantees on which it returns. If it
cannot find one, returns null. If it can only find one on external storage and the caller
doesn't have the Manifest.permission.READ_EXTERNAL_STORAGE
permission,
returns null.
Parameters | |
---|---|
context |
Context : The context to use for querying. |
Returns | |
---|---|
Uri |
A ringtone URI, or null if one cannot be found. |
hasHapticChannels
public boolean hasHapticChannels (int position)
Returns if the Ringtone
at the given position in the
Cursor
contains haptic channels.
Parameters | |
---|---|
position |
int : The position (in the Cursor ) of the ringtone. |
Returns | |
---|---|
boolean |
true if the ringtone contains haptic channels. |
hasHapticChannels
public static boolean hasHapticChannels (Uri ringtoneUri)
Returns if the Ringtone
from a given sound URI contains
haptic channels or not. As this function doesn't has a context
to resolve the uri, the result may be wrong if the uri cannot be
resolved correctly.
Use hasHapticChannels(int)
or hasHapticChannels(android.content.Context, android.net.Uri)
instead when possible.
Parameters | |
---|---|
ringtoneUri |
Uri : The Uri of a sound or ringtone.
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the ringtone contains haptic channels. |
hasHapticChannels
public static boolean hasHapticChannels (Context context, Uri ringtoneUri)
Returns if the Ringtone
from a given sound URI contains haptics channels or not.
Parameters | |
---|---|
context |
Context : the Context to use when resolving the Uri.
This value cannot be null . |
ringtoneUri |
Uri : the Uri of a sound or ringtone.
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the ringtone contains haptic channels. |
inferStreamType
public int inferStreamType ()
Infers the volume stream type based on what type of ringtones this manager is returning.
Returns | |
---|---|
int |
The stream type. |
isDefault
public static boolean isDefault (Uri ringtoneUri)
Returns whether the given Uri
is one of the default ringtones.
Parameters | |
---|---|
ringtoneUri |
Uri : The ringtone Uri to be checked. |
Returns | |
---|---|
boolean |
Whether the Uri is a default. |
openDefaultRingtoneUri
public static AssetFileDescriptor openDefaultRingtoneUri (Context context, Uri uri)
Opens a raw file descriptor to read the data under the given default URI.
Parameters | |
---|---|
context |
Context : the Context to use when resolving the Uri.
This value cannot be null . |
uri |
Uri : The desired default URI to open.
This value cannot be null . |
Returns | |
---|---|
AssetFileDescriptor |
a new AssetFileDescriptor pointing to the file. You own this descriptor
and are responsible for closing it when done. This value may be null . |
Throws | |
---|---|
FileNotFoundException |
if the provided URI could not be opened. |
See also:
setActualDefaultRingtoneUri
public static void setActualDefaultRingtoneUri (Context context, int type, Uri ringtoneUri)
Sets the Uri
of the default sound for a given sound type.
Parameters | |
---|---|
context |
Context : A context used for querying. |
type |
int : The type whose default sound should be set. One of
TYPE_RINGTONE , TYPE_NOTIFICATION , or
TYPE_ALARM . |
ringtoneUri |
Uri : A Uri pointing to the default sound to set. |
setIncludeDrm
public void setIncludeDrm (boolean includeDrm)
This method was deprecated
in API level 19.
DRM ringtones are no longer supported
Sets whether to include DRM ringtones.
Parameters | |
---|---|
includeDrm |
boolean : Whether to include DRM ringtones.
Obsolete - no longer has any effect |
setStopPreviousRingtone
public void setStopPreviousRingtone (boolean stopPreviousRingtone)
Whether retrieving another Ringtone
will stop playing the
previously retrieved Ringtone
.
If this is false, make sure to Ringtone.stop()
any previous
ringtones to free resources.
Parameters | |
---|---|
stopPreviousRingtone |
boolean : If true, the previously retrieved
Ringtone will be stopped. |
setType
public void setType (int type)
Sets which type(s) of ringtones will be listed by this.
Parameters | |
---|---|
type |
int : The type(s), one or more of TYPE_RINGTONE ,
TYPE_NOTIFICATION , TYPE_ALARM ,
TYPE_ALL . |
See also:
stopPreviousRingtone
public void stopPreviousRingtone ()
Stops playing the last Ringtone
retrieved from this.