From 687362e6fe6f4af7a2f6a0a6bdf7b9bb021559b2 Mon Sep 17 00:00:00 2001
From: tonihei <tonihei@google.com>
Date: Tue, 7 Mar 2023 16:00:41 +0000
Subject: [PATCH] Document that custom commands can only be sent if they are
 defined

Custom commands from controller to session are blocked if they are
not listed in the available session command list. This isn't well
documented in the Javadoc currently.

#minor-release

PiperOrigin-RevId: 514733568
(cherry picked from commit 20669fca275554698c9176250005055b230485b3)
---
 .../main/java/androidx/media3/session/MediaController.java   | 5 +++--
 .../src/main/java/androidx/media3/session/MediaSession.java  | 4 ++++
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/libraries/session/src/main/java/androidx/media3/session/MediaController.java b/libraries/session/src/main/java/androidx/media3/session/MediaController.java
index 529be85dcc..44acda8293 100644
--- a/libraries/session/src/main/java/androidx/media3/session/MediaController.java
+++ b/libraries/session/src/main/java/androidx/media3/session/MediaController.java
@@ -905,13 +905,14 @@ public class MediaController implements Player {
   /**
    * Sends a custom command to the session.
    *
+   * <p>A command is not accepted if it is not a custom command or the command is not in the list of
+   * {@linkplain #getAvailableSessionCommands() available session commands}.
+   *
    * <p>Interoperability: When connected to {@link
    * android.support.v4.media.session.MediaSessionCompat}, {@link SessionResult#resultCode} will
    * return the custom result code from the {@code android.os.ResultReceiver#onReceiveResult(int,
    * Bundle)} instead of the standard result codes defined in the {@link SessionResult}.
    *
-   * <p>A command is not accepted if it is not a custom command.
-   *
    * @param command The custom command.
    * @param args The additional arguments. May be empty.
    * @return A {@link ListenableFuture} of {@link SessionResult} representing the pending
diff --git a/libraries/session/src/main/java/androidx/media3/session/MediaSession.java b/libraries/session/src/main/java/androidx/media3/session/MediaSession.java
index 601920bbdc..3c82ec75d2 100644
--- a/libraries/session/src/main/java/androidx/media3/session/MediaSession.java
+++ b/libraries/session/src/main/java/androidx/media3/session/MediaSession.java
@@ -1042,6 +1042,10 @@ public class MediaSession {
      * Called when a controller sent a custom command through {@link
      * MediaController#sendCustomCommand(SessionCommand, Bundle)}.
      *
+     * <p>{@link MediaController} instances are only allowed to send a command if the command has
+     * been added to the {@link MediaSession.ConnectionResult#availableSessionCommands list of
+     * available session commands} in {@link #onConnect} or set via {@link #setAvailableCommands}.
+     *
      * <p>Interoperability: This will be also called by {@link
      * android.support.v4.media.MediaBrowserCompat#sendCustomAction}. If so, {@code extras} from
      * {@link android.support.v4.media.MediaBrowserCompat#sendCustomAction} will be considered as