RingtoneManager
open class RingtoneManager
kotlin.Any | |
↳ | 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 | |
---|---|
static String |
Activity Action: Shows a ringtone picker. |
static String |
Given to the ringtone picker as a |
static String |
Given to the ringtone picker as a |
static String |
Given to the ringtone picker as a boolean. |
static String |
Returned from the ringtone picker as a |
static String |
Given to the ringtone picker as a boolean. |
static String |
Given to the ringtone picker as a boolean. |
static String |
Given to the ringtone picker as a |
static String |
Given to the ringtone picker as an int. |
static Int |
The column index (in the cursor returned by |
static Int |
The column index (in the cursor returned by |
static Int |
Type that refers to sounds that are used for the alarm. |
static Int |
All types of sounds. |
static Int |
Type that refers to sounds that are used for notifications. |
static Int |
Type that refers to sounds that are used for the phone ringer. |
static Int |
The column index (in the cursor returned by |
Public constructors | |
---|---|
RingtoneManager(activity: Activity!) Constructs a RingtoneManager. |
|
RingtoneManager(context: Context!) Constructs a RingtoneManager. |
Public methods | |
---|---|
open static Uri! |
getActualDefaultRingtoneUri(context: Context!, type: Int) Gets the current default sound's |
open Cursor! |
Returns a |
open static Int |
getDefaultType(defaultRingtoneUri: Uri!) Returns the type of a default |
open static Uri! |
getDefaultUri(type: Int) Returns the |
open Boolean |
Returns whether DRM ringtones will be included. |
open Ringtone! |
getRingtone(position: Int) Gets a |
open static Ringtone! |
getRingtone(context: Context!, ringtoneUri: Uri!) Returns a |
open Int |
getRingtonePosition(ringtoneUri: Uri!) Gets the position of a |
open Uri! |
getRingtoneUri(position: Int) Gets a |
open Boolean | |
open static Uri! |
getValidRingtoneUri(context: Context!) Returns a valid ringtone URI. |
open Boolean |
hasHapticChannels(position: Int) Returns if the |
open static Boolean |
hasHapticChannels(ringtoneUri: Uri) Returns if the |
open static Boolean |
hasHapticChannels(context: Context, ringtoneUri: Uri) Returns if the |
open Int |
Infers the volume stream type based on what type of ringtones this manager is returning. |
open static Boolean |
Returns whether the given |
open static AssetFileDescriptor? |
openDefaultRingtoneUri(context: Context, uri: Uri) Opens a raw file descriptor to read the data under the given default URI. |
open static Unit |
setActualDefaultRingtoneUri(context: Context!, type: Int, ringtoneUri: Uri!) Sets the |
open Unit |
setIncludeDrm(includeDrm: Boolean) Sets whether to include DRM ringtones. |
open Unit |
setStopPreviousRingtone(stopPreviousRingtone: Boolean) Whether retrieving another |
open Unit |
Sets which type(s) of ringtones will be listed by this. |
open Unit |
Stops playing the last |
Constants
ACTION_RINGTONE_PICKER
static val ACTION_RINGTONE_PICKER: String
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
.
Value: "android.intent.action.RINGTONE_PICKER"
EXTRA_RINGTONE_DEFAULT_URI
static val EXTRA_RINGTONE_DEFAULT_URI: String
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.
Value: "android.intent.extra.ringtone.DEFAULT_URI"
EXTRA_RINGTONE_EXISTING_URI
static val EXTRA_RINGTONE_EXISTING_URI: String
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.
Value: "android.intent.extra.ringtone.EXISTING_URI"
See Also
EXTRA_RINGTONE_INCLUDE_DRM
static valEXTRA_RINGTONE_INCLUDE_DRM: String
Deprecated: DRM ringtones are no longer supported
Given to the ringtone picker as a boolean. Whether to include DRM ringtones.
Value: "android.intent.extra.ringtone.INCLUDE_DRM"
EXTRA_RINGTONE_PICKED_URI
static val EXTRA_RINGTONE_PICKED_URI: String
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, Value: "android.intent.extra.ringtone.PICKED_URI"
See Also
EXTRA_RINGTONE_SHOW_DEFAULT
static val EXTRA_RINGTONE_SHOW_DEFAULT: String
Given to the ringtone picker as a boolean. Whether to show an item for "Default".
Value: "android.intent.extra.ringtone.SHOW_DEFAULT"
See Also
EXTRA_RINGTONE_SHOW_SILENT
static val EXTRA_RINGTONE_SHOW_SILENT: String
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.
Value: "android.intent.extra.ringtone.SHOW_SILENT"
See Also
EXTRA_RINGTONE_TITLE
static val EXTRA_RINGTONE_TITLE: String
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.
Value: "android.intent.extra.ringtone.TITLE"
EXTRA_RINGTONE_TYPE
static val EXTRA_RINGTONE_TYPE: String
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).
Value: "android.intent.extra.ringtone.TYPE"
ID_COLUMN_INDEX
static val ID_COLUMN_INDEX: Int
The column index (in the cursor returned by getCursor()
for the row ID.
Value: 0
TITLE_COLUMN_INDEX
static val TITLE_COLUMN_INDEX: Int
The column index (in the cursor returned by getCursor()
for the title.
Value: 1
TYPE_ALARM
static val TYPE_ALARM: Int
Type that refers to sounds that are used for the alarm.
Value: 4
TYPE_NOTIFICATION
static val TYPE_NOTIFICATION: Int
Type that refers to sounds that are used for notifications.
Value: 2
TYPE_RINGTONE
static val TYPE_RINGTONE: Int
Type that refers to sounds that are used for the phone ringer.
Value: 1
URI_COLUMN_INDEX
static val URI_COLUMN_INDEX: Int
The column index (in the cursor returned by getCursor()
for the media provider's URI.
Value: 2
Public constructors
RingtoneManager
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
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
open static fun getActualDefaultRingtoneUri(
context: Context!,
type: Int
): Uri!
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 . |
Return | |
---|---|
Uri! |
A Uri pointing to the default sound for the sound type. |
getCursor
open fun getCursor(): Cursor!
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 android.database.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 android.Manifest.permission#READ_EXTERNAL_STORAGE
permission.
Return | |
---|---|
Cursor! |
A Cursor of all the ringtones available. |
getDefaultType
open static fun getDefaultType(defaultRingtoneUri: Uri!): Int
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 . |
Return | |
---|---|
Int |
The type of the defaultRingtoneUri, or -1. |
getDefaultUri
open static fun getDefaultUri(type: Int): Uri!
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. |
Return | |
---|---|
Uri! |
The Uri of the default ringtone for the given type. |
getIncludeDrm
open fungetIncludeDrm(): Boolean
Deprecated: DRM ringtones are no longer supported
Returns whether DRM ringtones will be included.
Return | |
---|---|
Boolean |
Whether DRM ringtones will be included. |
See Also
getRingtone
open fun getRingtone(position: Int): Ringtone!
Gets a Ringtone
for the ringtone at the given position in the Cursor
.
Parameters | |
---|---|
position |
Int: The position (in the Cursor ) of the ringtone. |
Return | |
---|---|
Ringtone! |
A Ringtone pointing to the ringtone. |
getRingtone
open static fun getRingtone(
context: Context!,
ringtoneUri: Uri!
): Ringtone!
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. |
Return | |
---|---|
Ringtone! |
A Ringtone for the given URI, or null. |
getRingtonePosition
open fun getRingtonePosition(ringtoneUri: Uri!): Int
Gets the position of a Uri
within this RingtoneManager
.
Parameters | |
---|---|
ringtoneUri |
Uri!: The Uri to retreive the position of. |
Return | |
---|---|
Int |
The position of the Uri , or -1 if it cannot be found. |
getRingtoneUri
open fun getRingtoneUri(position: Int): Uri!
Gets a Uri
for the ringtone at the given position in the Cursor
.
Parameters | |
---|---|
position |
Int: The position (in the Cursor ) of the ringtone. |
Return | |
---|---|
Uri! |
A Uri pointing to the ringtone. |
getValidRingtoneUri
open static fun getValidRingtoneUri(context: Context!): Uri!
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 android.Manifest.permission#READ_EXTERNAL_STORAGE
permission, returns null.
Parameters | |
---|---|
context |
Context!: The context to use for querying. |
Return | |
---|---|
Uri! |
A ringtone URI, or null if one cannot be found. |
hasHapticChannels
open fun hasHapticChannels(position: Int): Boolean
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. |
Return | |
---|---|
Boolean |
true if the ringtone contains haptic channels. |
hasHapticChannels
open static fun hasHapticChannels(ringtoneUri: Uri): Boolean
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 . |
Return | |
---|---|
Boolean |
true if the ringtone contains haptic channels. |
hasHapticChannels
open static fun hasHapticChannels(
context: Context,
ringtoneUri: Uri
): Boolean
Returns if the Ringtone
from a given sound URI contains haptics channels or not.
Parameters | |
---|---|
context |
Context: the android.content.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 . |
Return | |
---|---|
Boolean |
true if the ringtone contains haptic channels. |
inferStreamType
open fun inferStreamType(): Int
Infers the volume stream type based on what type of ringtones this manager is returning.
Return | |
---|---|
Int |
The stream type. |
isDefault
open static fun isDefault(ringtoneUri: Uri!): Boolean
Returns whether the given Uri
is one of the default ringtones.
Parameters | |
---|---|
ringtoneUri |
Uri!: The ringtone Uri to be checked. |
Return | |
---|---|
Boolean |
Whether the Uri is a default. |
openDefaultRingtoneUri
open static fun openDefaultRingtoneUri(
context: Context,
uri: Uri
): AssetFileDescriptor?
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 . |
Return | |
---|---|
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 . |
Exceptions | |
---|---|
java.io.FileNotFoundException |
if the provided URI could not be opened. |
See Also
setActualDefaultRingtoneUri
open static fun setActualDefaultRingtoneUri(
context: Context!,
type: Int,
ringtoneUri: Uri!
): Unit
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
open funsetIncludeDrm(includeDrm: Boolean): Unit
Deprecated: 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
open fun setStopPreviousRingtone(stopPreviousRingtone: Boolean): Unit
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
open fun setType(type: Int): Unit
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
open fun stopPreviousRingtone(): Unit
Stops playing the last Ringtone
retrieved from this.