From 5db6637f8c6c8b3365f0476f1264bf19dfbc7207 Mon Sep 17 00:00:00 2001
From: Glenn Kasten <gkasten@google.com>
Date: Mon, 18 May 2015 16:43:57 -0700
Subject: [PATCH] Explain the void send() throws IOException

Bug: 21044677
Change-Id: If6b51058813aff3780821db7c619004622df64ca
---
 media/java/android/media/midi/MidiReceiver.java | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/media/java/android/media/midi/MidiReceiver.java b/media/java/android/media/midi/MidiReceiver.java
index 85c451f4b478f..45cba3bd38121 100644
--- a/media/java/android/media/midi/MidiReceiver.java
+++ b/media/java/android/media/midi/MidiReceiver.java
@@ -89,12 +89,15 @@ abstract public class MidiReceiver {
     /**
      * Called to send MIDI data to the receiver
      * Data will get split into multiple calls to {@link #onSend} if count exceeds
-     * {@link #getMaxMessageSize}.
+     * {@link #getMaxMessageSize}.  Blocks until all the data is sent or an exception occurs.
+     * In the latter case, the amount of data sent prior to the exception is not provided to caller.
+     * The communication should be considered corrupt.  The sender should reestablish
+     * communication, reset all controllers and send all notes off.
      *
      * @param msg a byte array containing the MIDI data
      * @param offset the offset of the first byte of the data in the array to be sent
      * @param count the number of bytes of MIDI data in the array to be sent
-     * @throws IOException
+     * @throws IOException if the data could not be sent in entirety
      */
     public void send(byte[] msg, int offset, int count) throws IOException {
         send(msg, offset, count, System.nanoTime());
@@ -103,13 +106,16 @@ abstract public class MidiReceiver {
     /**
      * Called to send MIDI data to the receiver to be handled at a specified time in the future
      * Data will get split into multiple calls to {@link #onSend} if count exceeds
-     * {@link #getMaxMessageSize}.
+     * {@link #getMaxMessageSize}.  Blocks until all the data is sent or an exception occurs.
+     * In the latter case, the amount of data sent prior to the exception is not provided to caller.
+     * The communication should be considered corrupt.  The sender should reestablish
+     * communication, reset all controllers and send all notes off.
      *
      * @param msg a byte array containing the MIDI data
      * @param offset the offset of the first byte of the data in the array to be sent
      * @param count the number of bytes of MIDI data in the array to be sent
-     * @param timestamp the timestamp of the message (based on {@link java.lang.System#nanoTime}
-     * @throws IOException
+     * @param timestamp the timestamp of the message, based on {@link java.lang.System#nanoTime}
+     * @throws IOException if the data could not be sent in entirety
      */
     public void send(byte[] msg, int offset, int count, long timestamp)
             throws IOException {