1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.media.midi;
18
19import java.io.IOException;
20
21/**
22 * Interface for sending and receiving data to and from a MIDI device.
23 */
24abstract public class MidiReceiver {
25
26    private final int mMaxMessageSize;
27
28    /**
29     * Default MidiReceiver constructor. Maximum message size is set to
30     * {@link java.lang.Integer#MAX_VALUE}
31     */
32    public MidiReceiver() {
33        mMaxMessageSize = Integer.MAX_VALUE;
34    }
35
36    /**
37     * MidiReceiver constructor.
38     * @param maxMessageSize the maximum size of a message this receiver can receive
39     */
40    public MidiReceiver(int maxMessageSize) {
41        mMaxMessageSize = maxMessageSize;
42    }
43
44    /**
45     * Called whenever the receiver is passed new MIDI data.
46     * Subclasses override this method to receive MIDI data.
47     * May fail if count exceeds {@link #getMaxMessageSize}.
48     *
49     * NOTE: the msg array parameter is only valid within the context of this call.
50     * The msg bytes should be copied by the receiver rather than retaining a reference
51     * to this parameter.
52     * Also, modifying the contents of the msg array parameter may result in other receivers
53     * in the same application receiving incorrect values in their {link #onSend} method.
54     *
55     * @param msg a byte array containing the MIDI data
56     * @param offset the offset of the first byte of the data in the array to be processed
57     * @param count the number of bytes of MIDI data in the array to be processed
58     * @param timestamp the timestamp of the message (based on {@link java.lang.System#nanoTime}
59     * @throws IOException
60     */
61    abstract public void onSend(byte[] msg, int offset, int count, long timestamp)
62            throws IOException;
63
64    /**
65     * Instructs the receiver to discard all pending MIDI data.
66     * @throws IOException
67     */
68    public void flush() throws IOException {
69        onFlush();
70    }
71
72    /**
73     * Called when the receiver is instructed to discard all pending MIDI data.
74     * Subclasses should override this method if they maintain a list or queue of MIDI data
75     * to be processed in the future.
76     * @throws IOException
77     */
78    public void onFlush() throws IOException {
79    }
80
81    /**
82     * Returns the maximum size of a message this receiver can receive.
83     * @return maximum message size
84     */
85    public final int getMaxMessageSize() {
86        return mMaxMessageSize;
87    }
88
89    /**
90     * Called to send MIDI data to the receiver without a timestamp.
91     * Data will be processed by receiver in the order sent.
92     * Data will get split into multiple calls to {@link #onSend} if count exceeds
93     * {@link #getMaxMessageSize}.  Blocks until all the data is sent or an exception occurs.
94     * In the latter case, the amount of data sent prior to the exception is not provided to caller.
95     * The communication should be considered corrupt.  The sender should reestablish
96     * communication, reset all controllers and send all notes off.
97     *
98     * @param msg a byte array containing the MIDI data
99     * @param offset the offset of the first byte of the data in the array to be sent
100     * @param count the number of bytes of MIDI data in the array to be sent
101     * @throws IOException if the data could not be sent in entirety
102     */
103    public void send(byte[] msg, int offset, int count) throws IOException {
104        // TODO add public static final TIMESTAMP_NONE = 0L
105        send(msg, offset, count, 0L);
106    }
107
108    /**
109     * Called to send MIDI data to the receiver with a specified timestamp.
110     * Data will be processed by receiver in order first by timestamp, then in the order sent.
111     * Data will get split into multiple calls to {@link #onSend} if count exceeds
112     * {@link #getMaxMessageSize}.  Blocks until all the data is sent or an exception occurs.
113     * In the latter case, the amount of data sent prior to the exception is not provided to caller.
114     * The communication should be considered corrupt.  The sender should reestablish
115     * communication, reset all controllers and send all notes off.
116     *
117     * @param msg a byte array containing the MIDI data
118     * @param offset the offset of the first byte of the data in the array to be sent
119     * @param count the number of bytes of MIDI data in the array to be sent
120     * @param timestamp the timestamp of the message, based on {@link java.lang.System#nanoTime}
121     * @throws IOException if the data could not be sent in entirety
122     */
123    public void send(byte[] msg, int offset, int count, long timestamp)
124            throws IOException {
125        int messageSize = getMaxMessageSize();
126        while (count > 0) {
127            int length = (count > messageSize ? messageSize : count);
128            onSend(msg, offset, length, timestamp);
129            offset += length;
130            count -= length;
131        }
132    }
133}
134