MidiReceiver.java revision 5db6637f8c6c8b3365f0476f1264bf19dfbc7207 
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
91     * Data will get split into multiple calls to {@link #onSend} if count exceeds
92     * {@link #getMaxMessageSize}.  Blocks until all the data is sent or an exception occurs.
93     * In the latter case, the amount of data sent prior to the exception is not provided to caller.
94     * The communication should be considered corrupt.  The sender should reestablish
95     * communication, reset all controllers and send all notes off.
96     *
97     * @param msg a byte array containing the MIDI data
98     * @param offset the offset of the first byte of the data in the array to be sent
99     * @param count the number of bytes of MIDI data in the array to be sent
100     * @throws IOException if the data could not be sent in entirety
101     */
102    public void send(byte[] msg, int offset, int count) throws IOException {
103        send(msg, offset, count, System.nanoTime());
104    }
105
106    /**
107     * Called to send MIDI data to the receiver to be handled at a specified time in the future
108     * Data will get split into multiple calls to {@link #onSend} if count exceeds
109     * {@link #getMaxMessageSize}.  Blocks until all the data is sent or an exception occurs.
110     * In the latter case, the amount of data sent prior to the exception is not provided to caller.
111     * The communication should be considered corrupt.  The sender should reestablish
112     * communication, reset all controllers and send all notes off.
113     *
114     * @param msg a byte array containing the MIDI data
115     * @param offset the offset of the first byte of the data in the array to be sent
116     * @param count the number of bytes of MIDI data in the array to be sent
117     * @param timestamp the timestamp of the message, based on {@link java.lang.System#nanoTime}
118     * @throws IOException if the data could not be sent in entirety
119     */
120    public void send(byte[] msg, int offset, int count, long timestamp)
121            throws IOException {
122        int messageSize = getMaxMessageSize();
123        while (count > 0) {
124            int length = (count > messageSize ? messageSize : count);
125            onSend(msg, offset, length, timestamp);
126            offset += length;
127            count -= length;
128        }
129    }
130}
131