diff options
| -rw-r--r-- | core/java/android/midi/MidiDevice.java | 22 | ||||
| -rw-r--r-- | core/java/android/midi/MidiDeviceInfo.java | 7 | ||||
| -rw-r--r-- | core/java/android/midi/MidiInputPort.java | 9 | ||||
| -rw-r--r-- | core/java/android/midi/MidiManager.java | 56 | ||||
| -rw-r--r-- | core/java/android/midi/MidiOutputPort.java | 15 | ||||
| -rw-r--r-- | core/java/android/midi/MidiPort.java | 7 | ||||
| -rw-r--r-- | core/java/android/midi/MidiReceiver.java | 15 | ||||
| -rw-r--r-- | core/java/android/midi/MidiSender.java | 11 |
8 files changed, 123 insertions, 19 deletions
diff --git a/core/java/android/midi/MidiDevice.java b/core/java/android/midi/MidiDevice.java index e704ea085d28..7f83896dd5ad 100644 --- a/core/java/android/midi/MidiDevice.java +++ b/core/java/android/midi/MidiDevice.java @@ -140,6 +140,12 @@ public final class MidiDevice implements Parcelable { mReceivers = new ArrayList[outputPorts]; } + /** + * Called to open a {@link MidiInputPort} for the specified port number. + * + * @param portNumber the number of the input port to open + * @return the {@link MidiInputPort} + */ public MidiInputPort openInputPort(int portNumber) { if (portNumber < 0 || portNumber >= mDeviceInfo.getInputPortCount()) { throw new IllegalArgumentException("input port number out of range"); @@ -152,6 +158,12 @@ public final class MidiDevice implements Parcelable { } } + /** + * Called to open a {@link MidiOutputPort} for the specified port number. + * + * @param portNumber the number of the output port to open + * @return the {@link MidiOutputPort} + */ public MidiOutputPort openOutputPort(int portNumber) { if (portNumber < 0 || portNumber >= mDeviceInfo.getOutputPortCount()) { throw new IllegalArgumentException("output port number out of range"); @@ -203,7 +215,7 @@ public final class MidiDevice implements Parcelable { return true; } - void close() { + /* package */ void close() { try { if (mInputStream != null) { mInputStream.close(); @@ -216,7 +228,11 @@ public final class MidiDevice implements Parcelable { } } - // returns our MidiDeviceInfo object, which describes this device + /** + * Returns a {@link MidiDeviceInfo} object, which describes this device. + * + * @return the {@link MidiDeviceInfo} object + */ public MidiDeviceInfo getInfo() { return mDeviceInfo; } @@ -239,10 +255,12 @@ public final class MidiDevice implements Parcelable { } }; + @Override public int describeContents() { return 0; } + @Override public void writeToParcel(Parcel parcel, int flags) { parcel.writeParcelable(mDeviceInfo, flags); parcel.writeParcelable(mParcelFileDescriptor, flags); diff --git a/core/java/android/midi/MidiDeviceInfo.java b/core/java/android/midi/MidiDeviceInfo.java index 239481b73ee5..5b5769638e10 100644 --- a/core/java/android/midi/MidiDeviceInfo.java +++ b/core/java/android/midi/MidiDeviceInfo.java @@ -34,7 +34,14 @@ public class MidiDeviceInfo implements Parcelable { private static final String TAG = "MidiDeviceInfo"; + /** + * Constant representing USB MIDI devices for {@link #getType} + */ public static final int TYPE_USB = 1; + + /** + * Constant representing virtual (software based) MIDI devices for {@link #getType} + */ public static final int TYPE_VIRTUAL = 2; private final int mType; // USB or virtual diff --git a/core/java/android/midi/MidiInputPort.java b/core/java/android/midi/MidiInputPort.java index 583c367ba7bc..31449a576d60 100644 --- a/core/java/android/midi/MidiInputPort.java +++ b/core/java/android/midi/MidiInputPort.java @@ -38,14 +38,15 @@ public final class MidiInputPort extends MidiPort implements MidiReceiver { /** * Writes a MIDI message to the input port * - * @param msg message bytes - * @param offset offset of first byte of the message in msg array + * @param msg byte array containing the message + * @param offset offset of first byte of the message in msg byte array * @param count size of the message in bytes - * @param timestamp future time to post the message + * @param timestamp future time to post the message (based on + * {@link java.lang.System#nanoTime} */ public void onPost(byte[] msg, int offset, int count, long timestamp) throws IOException { synchronized (mBuffer) { - int length = MidiDevice.packMessage(msg, offset, count, timestamp, mPortNumber, + int length = MidiDevice.packMessage(msg, offset, count, timestamp, getPortNumber(), mBuffer); mOutputStream.write(mBuffer, 0, length); } diff --git a/core/java/android/midi/MidiManager.java b/core/java/android/midi/MidiManager.java index f4d19182896a..64cd4feaf363 100644 --- a/core/java/android/midi/MidiManager.java +++ b/core/java/android/midi/MidiManager.java @@ -35,6 +35,7 @@ import java.util.HashMap; * * {@samplecode * MidiManager manager = (MidiManager) getSystemService(Context.MIDI_SERVICE);} + * * @hide */ public class MidiManager { @@ -64,9 +65,22 @@ public class MidiManager { } } - // Callback interface clients to receive Device added and removed notifications + /** + * Callback interface used for clients to receive MIDI device added and removed notifications + */ public interface DeviceCallback { + /** + * Called to notify when a new MIDI device has been added + * + * @param device a {@link MidiDeviceInfo} for the newly added device + */ void onDeviceAdded(MidiDeviceInfo device); + + /** + * Called to notify when a MIDI device has been removed + * + * @param device a {@link MidiDeviceInfo} for the removed device + */ void onDeviceRemoved(MidiDeviceInfo device); } @@ -78,7 +92,11 @@ public class MidiManager { mService = service; } - // Used by clients to register for Device added and removed notifications + /** + * Registers a callback to receive notifications when MIDI devices are added and removed. + * + * @param callback a {@link DeviceCallback} for MIDI device notifications + */ public void registerDeviceCallback(DeviceCallback callback) { DeviceListener deviceListener = new DeviceListener(callback); try { @@ -90,7 +108,11 @@ public class MidiManager { mDeviceListeners.put(callback, deviceListener); } - // Used by clients to unregister for device added and removed notifications + /** + * Unregisters a {@link DeviceCallback}. + * + * @param callback a {@link DeviceCallback} to unregister + */ public void unregisterDeviceCallback(DeviceCallback callback) { DeviceListener deviceListener = mDeviceListeners.remove(callback); if (deviceListener != null) { @@ -102,6 +124,11 @@ public class MidiManager { } } + /** + * Gets the list of all connected MIDI devices. + * + * @return an array of all MIDI devices + */ public MidiDeviceInfo[] getDeviceList() { try { return mService.getDeviceList(); @@ -111,7 +138,12 @@ public class MidiManager { } } - // Use this if you want to communicate with a MIDI device. + /** + * Opens a MIDI device for reading and writing. + * + * @param deviceInfo a {@link android.midi.MidiDeviceInfo} to open + * @return a {@link MidiDevice} object for the device + */ public MidiDevice openDevice(MidiDeviceInfo deviceInfo) { try { ParcelFileDescriptor pfd = mService.openDevice(mToken, deviceInfo); @@ -130,8 +162,15 @@ public class MidiManager { return null; } - // Use this if you want to register and implement a virtual device. - // The MidiDevice returned by this method is the proxy you use to implement the device. + /** + * Creates a new MIDI virtual device. + * NOTE: The method for creating virtual devices is likely to change before release. + * + * @param numInputPorts number of input ports for the virtual device + * @param numOutputPorts number of output ports for the virtual device + * @param properties a {@link android.os.Bundle} containing properties describing the device + * @return a {@link MidiDevice} object to locally represent the device + */ public MidiDevice createVirtualDevice(int numInputPorts, int numOutputPorts, Bundle properties) { try { @@ -147,6 +186,11 @@ public class MidiManager { } } + /** + * Removes a MIDI virtual device. + * + * @param device the {@link MidiDevice} for the virtual device to remove + */ public void closeVirtualDevice(MidiDevice device) { try { device.close(); diff --git a/core/java/android/midi/MidiOutputPort.java b/core/java/android/midi/MidiOutputPort.java index 69a33cb0f566..7ce286b3ad9c 100644 --- a/core/java/android/midi/MidiOutputPort.java +++ b/core/java/android/midi/MidiOutputPort.java @@ -32,11 +32,22 @@ public final class MidiOutputPort extends MidiPort implements MidiSender { mDevice = device; } + /** + * Connects a {@link MidiReceiver} to the output port to allow receiving + * MIDI messages from the port. + * + * @param receiver the receiver to connect + */ public void connect(MidiReceiver receiver) { - mDevice.connect(receiver, mPortNumber); + mDevice.connect(receiver, getPortNumber()); } + /** + * Disconnects a {@link MidiReceiver} from the output port. + * + * @param receiver the receiver to connect + */ public void disconnect(MidiReceiver receiver) { - mDevice.disconnect(receiver, mPortNumber); + mDevice.disconnect(receiver, getPortNumber()); } } diff --git a/core/java/android/midi/MidiPort.java b/core/java/android/midi/MidiPort.java index e94f62db2d52..fdd023371b67 100644 --- a/core/java/android/midi/MidiPort.java +++ b/core/java/android/midi/MidiPort.java @@ -20,13 +20,14 @@ import java.io.FileOutputStream; import java.io.IOException; /** - * This class represents a MIDI input or output port + * This class represents a MIDI input or output port. + * Base class for {@link MidiInputPort} and {@link MidiOutputPort} * * @hide */ public class MidiPort { - protected final int mPortNumber; + private final int mPortNumber; /* package */ MidiPort(int portNumber) { mPortNumber = portNumber; @@ -37,7 +38,7 @@ public class MidiPort { * * @return the port's port number */ - public int getPortNumber() { + public final int getPortNumber() { return mPortNumber; } } diff --git a/core/java/android/midi/MidiReceiver.java b/core/java/android/midi/MidiReceiver.java index 1101105ebabf..0b183cca3b5b 100644 --- a/core/java/android/midi/MidiReceiver.java +++ b/core/java/android/midi/MidiReceiver.java @@ -24,7 +24,18 @@ import java.io.IOException; * @hide */ public interface MidiReceiver { - // NOTE: the msg array is only valid within the context of this call. - // the byte array may get reused by the MIDI device for the next message. + /** + * Called to pass a MIDI event to the receiver. + * + * NOTE: the msg array parameter is only valid within the context of this call. + * The msg bytes should be copied by the receiver rather than retaining a reference + * to this parameter. + * + * @param msg a byte array containing the MIDI message + * @param offset the offset of the first byte of the message in the byte array + * @param count the number of bytes in the message + * @param timestamp the timestamp of the message (based on {@link java.lang.System#nanoTime} + * @throws IOException + */ public void onPost(byte[] msg, int offset, int count, long timestamp) throws IOException; } diff --git a/core/java/android/midi/MidiSender.java b/core/java/android/midi/MidiSender.java index cba707905517..7958a0698d97 100644 --- a/core/java/android/midi/MidiSender.java +++ b/core/java/android/midi/MidiSender.java @@ -23,6 +23,17 @@ package android.midi; * @hide */ public interface MidiSender { + /** + * Called to connect a {@link MidiReceiver} to the sender + * + * @param receiver the receiver to connect + */ public void connect(MidiReceiver receiver); + + /** + * Called to disconnect a {@link MidiReceiver} from the sender + * + * @param receiver the receiver to disconnect + */ public void disconnect(MidiReceiver receiver); } |