Merge "Converge documentation around media session key" into main
diff --git a/core/java/android/view/KeyEvent.java b/core/java/android/view/KeyEvent.java
index bb4cc8f..b17d2d1 100644
--- a/core/java/android/view/KeyEvent.java
+++ b/core/java/android/view/KeyEvent.java
@@ -1990,8 +1990,23 @@
}
/**
- * Returns whether this key will be sent to the
- * {@link android.media.session.MediaSession.Callback} if not handled.
+ * Returns whether this key will be sent to the {@link
+ * android.media.session.MediaSession.Callback} if not handled.
+ *
+ * <p>The following key codes are considered {@link android.media.session.MediaSession} keys:
+ *
+ * <ul>
+ * <li>{@link #KEYCODE_MEDIA_PLAY}
+ * <li>{@link #KEYCODE_MEDIA_PAUSE}
+ * <li>{@link #KEYCODE_MEDIA_PLAY_PAUSE}
+ * <li>{@link #KEYCODE_HEADSETHOOK}
+ * <li>{@link #KEYCODE_MEDIA_STOP}
+ * <li>{@link #KEYCODE_MEDIA_NEXT}
+ * <li>{@link #KEYCODE_MEDIA_PREVIOUS}
+ * <li>{@link #KEYCODE_MEDIA_REWIND}
+ * <li>{@link #KEYCODE_MEDIA_RECORD}
+ * <li>{@link #KEYCODE_MEDIA_FAST_FORWARD}
+ * </ul>
*/
public static final boolean isMediaSessionKey(int keyCode) {
switch (keyCode) {
diff --git a/media/java/android/media/AudioManager.java b/media/java/android/media/AudioManager.java
index 842542f..adc0e16 100644
--- a/media/java/android/media/AudioManager.java
+++ b/media/java/android/media/AudioManager.java
@@ -941,27 +941,15 @@
}
/**
- * Sends a simulated key event for a media button.
- * To simulate a key press, you must first send a KeyEvent built with a
- * {@link KeyEvent#ACTION_DOWN} action, then another event with the {@link KeyEvent#ACTION_UP}
- * action.
+ * Sends a simulated key event for a media button. To simulate a key press, you must first send
+ * a KeyEvent built with a {@link KeyEvent#ACTION_DOWN} action, then another event with the
+ * {@link KeyEvent#ACTION_UP} action.
+ *
* <p>The key event will be sent to the current media key event consumer which registered with
* {@link AudioManager#registerMediaButtonEventReceiver(PendingIntent)}.
- * @param keyEvent a {@link KeyEvent} instance whose key code is one of
- * {@link KeyEvent#KEYCODE_MUTE},
- * {@link KeyEvent#KEYCODE_HEADSETHOOK},
- * {@link KeyEvent#KEYCODE_MEDIA_PLAY},
- * {@link KeyEvent#KEYCODE_MEDIA_PAUSE},
- * {@link KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE},
- * {@link KeyEvent#KEYCODE_MEDIA_STOP},
- * {@link KeyEvent#KEYCODE_MEDIA_NEXT},
- * {@link KeyEvent#KEYCODE_MEDIA_PREVIOUS},
- * {@link KeyEvent#KEYCODE_MEDIA_REWIND},
- * {@link KeyEvent#KEYCODE_MEDIA_RECORD},
- * {@link KeyEvent#KEYCODE_MEDIA_FAST_FORWARD},
- * {@link KeyEvent#KEYCODE_MEDIA_CLOSE},
- * {@link KeyEvent#KEYCODE_MEDIA_EJECT},
- * or {@link KeyEvent#KEYCODE_MEDIA_AUDIO_TRACK}.
+ *
+ * @param keyEvent a media session {@link KeyEvent}, as defined by {@link
+ * KeyEvent#isMediaSessionKey}.
*/
public void dispatchMediaKeyEvent(KeyEvent keyEvent) {
MediaSessionLegacyHelper helper = MediaSessionLegacyHelper.getHelper(getContext());
diff --git a/media/java/android/media/RemoteController.java b/media/java/android/media/RemoteController.java
index a6e8fa0..aaaf25f 100644
--- a/media/java/android/media/RemoteController.java
+++ b/media/java/android/media/RemoteController.java
@@ -220,33 +220,21 @@
return -1;
}
-
/**
- * Send a simulated key event for a media button to be received by the current client.
- * To simulate a key press, you must first send a KeyEvent built with
- * a {@link KeyEvent#ACTION_DOWN} action, then another event with the {@link KeyEvent#ACTION_UP}
- * action.
- * <p>The key event will be sent to the registered receiver
- * (see {@link AudioManager#registerMediaButtonEventReceiver(PendingIntent)}) whose associated
- * {@link RemoteControlClient}'s metadata and playback state is published (there may be
- * none under some circumstances).
- * @param keyEvent a {@link KeyEvent} instance whose key code is one of
- * {@link KeyEvent#KEYCODE_MUTE},
- * {@link KeyEvent#KEYCODE_HEADSETHOOK},
- * {@link KeyEvent#KEYCODE_MEDIA_PLAY},
- * {@link KeyEvent#KEYCODE_MEDIA_PAUSE},
- * {@link KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE},
- * {@link KeyEvent#KEYCODE_MEDIA_STOP},
- * {@link KeyEvent#KEYCODE_MEDIA_NEXT},
- * {@link KeyEvent#KEYCODE_MEDIA_PREVIOUS},
- * {@link KeyEvent#KEYCODE_MEDIA_REWIND},
- * {@link KeyEvent#KEYCODE_MEDIA_RECORD},
- * {@link KeyEvent#KEYCODE_MEDIA_FAST_FORWARD},
- * {@link KeyEvent#KEYCODE_MEDIA_CLOSE},
- * {@link KeyEvent#KEYCODE_MEDIA_EJECT},
- * or {@link KeyEvent#KEYCODE_MEDIA_AUDIO_TRACK}.
+ * Send a simulated key event for a media button to be received by the current client. To
+ * simulate a key press, you must first send a KeyEvent built with a {@link
+ * KeyEvent#ACTION_DOWN} action, then another event with the {@link KeyEvent#ACTION_UP} action.
+ *
+ * <p>The key event will be sent to the registered receiver (see {@link
+ * AudioManager#registerMediaButtonEventReceiver(PendingIntent)}) whose associated {@link
+ * RemoteControlClient}'s metadata and playback state is published (there may be none under some
+ * circumstances).
+ *
+ * @param keyEvent a media session {@link KeyEvent}, as defined by {@link
+ * KeyEvent#isMediaSessionKey}.
* @return true if the event was successfully sent, false otherwise.
- * @throws IllegalArgumentException
+ * @throws IllegalArgumentException If the provided {@link KeyEvent} is not a media session key,
+ * as defined by {@link KeyEvent#isMediaSessionKey}.
*/
public boolean sendMediaKeyEvent(KeyEvent keyEvent) throws IllegalArgumentException {
if (!KeyEvent.isMediaSessionKey(keyEvent.getKeyCode())) {
diff --git a/services/core/java/com/android/server/media/MediaKeyDispatcher.java b/services/core/java/com/android/server/media/MediaKeyDispatcher.java
index 55511ad..66cafab 100644
--- a/services/core/java/com/android/server/media/MediaKeyDispatcher.java
+++ b/services/core/java/com/android/server/media/MediaKeyDispatcher.java
@@ -117,24 +117,11 @@
/**
* Gets the map of key code -> {@link KeyEventType} that have been overridden.
- * <p>
- * The list of valid key codes are the following:
- * <ul>
- * <li> {@link KeyEvent#KEYCODE_MEDIA_PLAY}
- * <li> {@link KeyEvent#KEYCODE_MEDIA_PAUSE}
- * <li> {@link KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE}
- * <li> {@link KeyEvent#KEYCODE_MUTE}
- * <li> {@link KeyEvent#KEYCODE_HEADSETHOOK}
- * <li> {@link KeyEvent#KEYCODE_MEDIA_STOP}
- * <li> {@link KeyEvent#KEYCODE_MEDIA_NEXT}
- * <li> {@link KeyEvent#KEYCODE_MEDIA_PREVIOUS}
- * <li> {@link KeyEvent#KEYCODE_VOLUME_UP}
- * <li> {@link KeyEvent#KEYCODE_VOLUME_DOWN}
- * <li> {@link KeyEvent#KEYCODE_VOLUME_MUTE}
- * </ul>
- * @see {@link KeyEvent#isMediaSessionKey(int)}
+ *
+ * <p>For the list of relevant key codes, see {@link KeyEvent#isMediaSessionKey(int)}.
*/
- @KeyEventType Map<Integer, Integer> getOverriddenKeyEvents() {
+ @KeyEventType
+ Map<Integer, Integer> getOverriddenKeyEvents() {
return mOverriddenKeyEvents;
}