android.media
public
class
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.
Summary
Constants
Public Constructors
Public Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Constants
public
static
final
String
ACTION_RINGTONE_PICKER
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
DEFAULT_RINGTONE_URI or
DEFAULT_NOTIFICATION_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"
public
static
final
String
EXTRA_RINGTONE_EXISTING_URI
public
static
final
String
EXTRA_RINGTONE_INCLUDE_DRM
Given to the ringtone picker as a boolean. Whether to include DRM ringtones.
Constant Value:
"android.intent.extra.ringtone.INCLUDE_DRM"
public
static
final
String
EXTRA_RINGTONE_PICKED_URI
Returned from the ringtone picker as a
Uri.
It will be one of:
the picked ringtone,
a Uri that equals DEFAULT_RINGTONE_URI or
DEFAULT_NOTIFICATION_URI if the default was chosen,
null if the "Silent" item was picked.
Constant Value:
"android.intent.extra.ringtone.PICKED_URI"
public
static
final
String
EXTRA_RINGTONE_SHOW_DEFAULT
Given to the ringtone picker as a boolean. Whether to show an item for
"Default".
Constant Value:
"android.intent.extra.ringtone.SHOW_DEFAULT"
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.
Constant Value:
"android.intent.extra.ringtone.SHOW_SILENT"
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"
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"
public
static
final
int
ID_COLUMN_INDEX
The column index (in the cursor returned by
getCursor() for the
row ID.
Constant Value:
0
(0x00000000)
public
static
final
int
TITLE_COLUMN_INDEX
The column index (in the cursor returned by
getCursor() for the
title.
Constant Value:
1
(0x00000001)
public
static
final
int
TYPE_ALARM
Type that refers to sounds that are used for the alarm.
Constant Value:
4
(0x00000004)
public
static
final
int
TYPE_ALL
All types of sounds.
Constant Value:
7
(0x00000007)
public
static
final
int
TYPE_NOTIFICATION
Type that refers to sounds that are used for notifications.
Constant Value:
2
(0x00000002)
public
static
final
int
TYPE_RINGTONE
Type that refers to sounds that are used for the phone ringer.
Constant Value:
1
(0x00000001)
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
public
RingtoneManager(Activity activity)
Constructs a RingtoneManager. This constructor is recommended as its
constructed instance manages cursor(s).
Parameters
activity
| The activity used to get a managed cursor.
|
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
| The context to used to get a cursor.
|
Public Methods
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
DEFAULT_RINGTONE_URI.
Returns
- A Uri pointing to the default sound for the sound type.
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
close() the cursor. The cursor can be
deactivate() safely.
If RingtoneManager(Activity) was not used, the
caller should manage the returned cursor through its activity's life
cycle to prevent leaking the cursor.
Returns
- A Cursor of all the ringtones available.
public
static
int
getDefaultType(Uri defaultRingtoneUri)
Returns the type of a default
Uri.
Returns
- The type of the defaultRingtoneUri, or -1.
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
| The ringtone type whose default should be returned. |
Returns
- The Uri of the default ringtone for the given type.
public
boolean
getIncludeDrm()
Returns whether DRM ringtones will be included.
Returns
- Whether DRM ringtones will be included.
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
| A context used to query. |
ringtoneUri
| The Uri of a sound or ringtone. |
public
Ringtone
getRingtone(int position)
Gets a
Ringtone for the ringtone at the given position in the
Cursor.
Parameters
position
| The position (in the Cursor) of the ringtone. |
public
int
getRingtonePosition(Uri ringtoneUri)
Gets the position of a
Uri within this
RingtoneManager.
Parameters
ringtoneUri
| The Uri to retreive the position of. |
Returns
- The position of the Uri, or -1 if it cannot be found.
public
Uri
getRingtoneUri(int position)
Gets a
Uri for the ringtone at the given position in the
Cursor.
Parameters
position
| The position (in the Cursor) of the ringtone. |
Returns
- A Uri pointing to the ringtone.
public
boolean
getStopPreviousRingtone()
public
static
Uri
getValidRingtoneUri(Context context)
Returns a valid ringtone URI. No guarantees on which it returns. If it
cannot find one, returns null.
Parameters
context
| The context to use for querying. |
Returns
- A ringtone URI, or null if one cannot be found.
public
static
boolean
isDefault(Uri ringtoneUri)
Returns whether the given
Uri is one of the default ringtones.
Parameters
ringtoneUri
| The ringtone Uri to be checked. |
Returns
- Whether the Uri is a default.
public
static
void
setActualDefaultRingtoneUri(Context context, int type, Uri ringtoneUri)
Sets the
Uri of the default sound for a given sound type.
Parameters
context
| A context used for querying. |
type
| The type whose default sound should be set. One of
TYPE_RINGTONE or TYPE_NOTIFICATION. |
ringtoneUri
| A Uri pointing to the default sound to set. |
public
void
setIncludeDrm(boolean includeDrm)
Sets whether to include DRM ringtones.
Parameters
includeDrm
| Whether to include DRM ringtones.
|
public
void
setStopPreviousRingtone(boolean stopPreviousRingtone)
Whether retrieving another
Ringtone will stop playing the
previously retrieved
Ringtone.
If this is false, make sure to stop() any previous
ringtones to free resources.
Parameters
stopPreviousRingtone
| If true, the previously retrieved
Ringtone will be stopped.
|
public
void
setType(int type)
Sets which type(s) of ringtones will be listed by this.
public
void
stopPreviousRingtone()
Stops playing the last
Ringtone retrieved from this.