/* * Copyright (c) 1998, 2005, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.sound.midi; /** * A <code>ShortMessage</code> contains a MIDI message that has at most * two data bytes following its status byte.  The types of MIDI message * that satisfy this criterion are channel voice, channel mode, system common, * and system real-time--in other words, everything except system exclusive * and meta-events.  The <code>ShortMessage</code> class provides methods * for getting and setting the contents of the MIDI message. * <p> * A number of <code>ShortMessage</code> methods have integer parameters by which * you specify a MIDI status or data byte.  If you know the numeric value, you * can express it directly.  For system common and system real-time messages, * you can often use the corresponding fields of <code>ShortMessage</code>, such as * {@link #SYSTEM_RESET SYSTEM_RESET}.  For channel messages, * the upper four bits of the status byte are specified by a command value and * the lower four bits are specified by a MIDI channel number. To * convert incoming MIDI data bytes that are in the form of Java's signed bytes, * you can use the <A HREF="MidiMessage.html#integersVsBytes">conversion code</A> * given in the <code>{@link MidiMessage}</code> class description. * * @see SysexMessage * @see MetaMessage * * @author David Rivas * @author Kara Kytle * @author Florian Bomers */ public class ShortMessage extends MidiMessage {      // Status byte defines      // System common messages     /**     * Status byte for MIDI Time Code Quarter Frame message (0xF1, or 241).     * @see MidiMessage#getStatus     */    public static final int MIDI_TIME_CODE                              = 0xF1; // 241     /**     * Status byte for Song Position Pointer message (0xF2, or 242).     * @see MidiMessage#getStatus     */    public static final int SONG_POSITION_POINTER               = 0xF2; // 242     /**     * Status byte for MIDI Song Select message (0xF3, or 243).     * @see MidiMessage#getStatus     */    public static final int SONG_SELECT                                 = 0xF3; // 243     /**     * Status byte for Tune Request message (0xF6, or 246).     * @see MidiMessage#getStatus     */    public static final int TUNE_REQUEST                                = 0xF6; // 246     /**     * Status byte for End of System Exclusive message (0xF7, or 247).     * @see MidiMessage#getStatus     */    public static final int END_OF_EXCLUSIVE                    = 0xF7; // 247      // System real-time messages     /**     * Status byte for Timing Clock messagem (0xF8, or 248).     * @see MidiMessage#getStatus     */    public static final int TIMING_CLOCK                                = 0xF8; // 248     /**     * Status byte for Start message (0xFA, or 250).     * @see MidiMessage#getStatus     */    public static final int START                                               = 0xFA; // 250     /**     * Status byte for Continue message (0xFB, or 251).     * @see MidiMessage#getStatus     */    public static final int CONTINUE                                    = 0xFB; // 251     /**     * Status byte for Stop message (0xFC, or 252).     * @see MidiMessage#getStatus     */    public static final int STOP                                                = 0xFC; //252     /**     * Status byte for Active Sensing message (0xFE, or 254).     * @see MidiMessage#getStatus     */    public static final int ACTIVE_SENSING                              = 0xFE; // 254     /**     * Status byte for System Reset message (0xFF, or 255).     * @see MidiMessage#getStatus     */    public static final int SYSTEM_RESET                                = 0xFF; // 255      // Channel voice message upper nibble defines     /**     * Command value for Note Off message (0x80, or 128)     */    public static final int NOTE_OFF                                    = 0x80;  // 128     /**     * Command value for Note On message (0x90, or 144)     */    public static final int NOTE_ON                                             = 0x90;  // 144     /**     * Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or 160)     */    public static final int POLY_PRESSURE                               = 0xA0;  // 160     /**     * Command value for Control Change message (0xB0, or 176)     */    public static final int CONTROL_CHANGE                              = 0xB0;  // 176     /**     * Command value for Program Change message (0xC0, or 192)     */    public static final int PROGRAM_CHANGE                              = 0xC0;  // 192     /**     * Command value for Channel Pressure (Aftertouch) message (0xD0, or 208)     */    public static final int CHANNEL_PRESSURE                    = 0xD0;  // 208     /**     * Command value for Pitch Bend message (0xE0, or 224)     */    public static final int PITCH_BEND                                  = 0xE0;  // 224      // Instance variables     /**     * Constructs a new <code>ShortMessage</code>.  The     * contents of the new message are guaranteed to specify     * a valid MIDI message.  Subsequently, you may set the     * contents of the message using one of the <code>setMessage</code>     * methods.     * @see #setMessage     */    public ShortMessage() {        this(new byte[3]);        // Default message data: NOTE_ON on Channel 0 with max volume        data[0] = (byte) (NOTE_ON & 0xFF);        data[1] = (byte) 64;        data[2] = (byte) 127;        length = 3;    }     /**     * Constructs a new {@code ShortMessage} which represents a MIDI     * message that takes no data bytes.     * The contents of the message can be changed by using one of     * the {@code setMessage} methods.     *     * @param status the MIDI status byte     * @throws InvalidMidiDataException if {@code status} does not specify     *     a valid MIDI status byte for a message that requires no data bytes     * @see #setMessage(int)     * @see #setMessage(int, int, int)     * @see #setMessage(int, int, int, int)     * @see #getStatus()     * @since 1.7     */    public ShortMessage(int status) throws InvalidMidiDataException {        super(null);        setMessage(status); // can throw InvalidMidiDataException    }     /**     * Constructs a new {@code ShortMessage} which represents a MIDI message     * that takes up to two data bytes. If the message only takes one data byte,     * the second data byte is ignored. If the message does not take     * any data bytes, both data bytes are ignored.     * The contents of the message can be changed by using one of     * the {@code setMessage} methods.     *     * @param status   the MIDI status byte     * @param data1    the first data byte     * @param data2    the second data byte     * @throws InvalidMidiDataException if the status byte or all data bytes     *     belonging to the message do not specify a valid MIDI message     * @see #setMessage(int)     * @see #setMessage(int, int, int)     * @see #setMessage(int, int, int, int)     * @see #getStatus()     * @see #getData1()     * @see #getData2()     * @since 1.7     */    public ShortMessage(int status, int data1, int data2)            throws InvalidMidiDataException {        super(null);        setMessage(status, data1, data2); // can throw InvalidMidiDataException    }     /**     * Constructs a new {@code ShortMessage} which represents a channel     * MIDI message that takes up to two data bytes. If the message only takes     * one data byte, the second data byte is ignored. If the message does not     * take any data bytes, both data bytes are ignored.     * The contents of the message can be changed by using one of     * the {@code setMessage} methods.     *     * @param command  the MIDI command represented by this message     * @param channel  the channel associated with the message     * @param data1    the first data byte     * @param data2    the second data byte     * @throws InvalidMidiDataException if the command value, channel value     *     or all data bytes belonging to the message do not specify     *     a valid MIDI message     * @see #setMessage(int)     * @see #setMessage(int, int, int)     * @see #setMessage(int, int, int, int)     * @see #getCommand()     * @see #getChannel()     * @see #getData1()     * @see #getData2()     * @since 1.7     */    public ShortMessage(int command, int channel, int data1, int data2)            throws InvalidMidiDataException {        super(null);        setMessage(command, channel, data1, data2);    }      /**     * Constructs a new <code>ShortMessage</code>.     * @param data an array of bytes containing the complete message.     * The message data may be changed using the <code>setMessage</code>     * method.     * @see #setMessage     */    // $$fb this should throw an Exception in case of an illegal message!    protected ShortMessage(byte[] data) {        // $$fb this may set an invalid message.        // Can't correct without compromising compatibility        super(data);    }      /**     * Sets the parameters for a MIDI message that takes no data bytes.     * @param status    the MIDI status byte     * @throws  <code>InvalidMidiDataException</code> if <code>status</code> does not     * specify a valid MIDI status byte for a message that requires no data bytes.     * @see #setMessage(int, int, int)     * @see #setMessage(int, int, int, int)     */    public void setMessage(int status) throws InvalidMidiDataException {        // check for valid values        int dataLength = getDataLength(status); // can throw InvalidMidiDataException        if (dataLength != 0) {            throw new InvalidMidiDataException("Status byte; " + status + " requires " + dataLength + " data bytes");        }        setMessage(status, 0, 0);    }      /**     * Sets the  parameters for a MIDI message that takes one or two data     * bytes.  If the message takes only one data byte, the second data     * byte is ignored; if the message does not take any data bytes, both     * data bytes are ignored.     *     * @param status    the MIDI status byte     * @param data1             the first data byte     * @param data2             the second data byte     * @throws  <code>InvalidMidiDataException</code> if the     * the status byte, or all data bytes belonging to the message, do     * not specify a valid MIDI message.     * @see #setMessage(int, int, int, int)     * @see #setMessage(int)     */    public void setMessage(int status, int data1, int data2) throws InvalidMidiDataException {        // check for valid values        int dataLength = getDataLength(status); // can throw InvalidMidiDataException        if (dataLength > 0) {            if (data1 < 0 || data1 > 127) {                throw new InvalidMidiDataException("data1 out of range: " + data1);            }            if (dataLength > 1) {                if (data2 < 0 || data2 > 127) {                    throw new InvalidMidiDataException("data2 out of range: " + data2);                }            }        }          // set the length        length = dataLength + 1;        // re-allocate array if ShortMessage(byte[]) constructor gave array with fewer elements        if (data == null || data.length < length) {            data = new byte[3];        }         // set the data        data[0] = (byte) (status & 0xFF);        if (length > 1) {            data[1] = (byte) (data1 & 0xFF);            if (length > 2) {                data[2] = (byte) (data2 & 0xFF);            }        }    }      /**     * Sets the short message parameters for a  channel message     * which takes up to two data bytes.  If the message only     * takes one data byte, the second data byte is ignored; if     * the message does not take any data bytes, both data bytes     * are ignored.     *     * @param command   the MIDI command represented by this message     * @param channel   the channel associated with the message     * @param data1             the first data byte     * @param data2             the second data byte     * @throws          <code>InvalidMidiDataException</code> if the     * status byte or all data bytes belonging to the message, do     * not specify a valid MIDI message     *     * @see #setMessage(int, int, int)     * @see #setMessage(int)     * @see #getCommand     * @see #getChannel     * @see #getData1     * @see #getData2     */    public void setMessage(int command, int channel, int data1, int data2) throws InvalidMidiDataException {        // check for valid values        if (command >= 0xF0 || command < 0x80) {            throw new InvalidMidiDataException("command out of range: 0x" + Integer.toHexString(command));        }        if ((channel & 0xFFFFFFF0) != 0) { // <=> (channel<0 || channel>15)            throw new InvalidMidiDataException("channel out of range: " + channel);        }        setMessage((command & 0xF0) | (channel & 0x0F), data1, data2);    }      /**     * Obtains the MIDI channel associated with this event.  This method     * assumes that the event is a MIDI channel message; if not, the return     * value will not be meaningful.     * @return MIDI channel associated with the message.     * @see #setMessage(int, int, int, int)     */    public int getChannel() {        // this returns 0 if an invalid message is set        return (getStatus() & 0x0F);    }      /**     * Obtains the MIDI command associated with this event.  This method     * assumes that the event is a MIDI channel message; if not, the return     * value will not be meaningful.     * @see #setMessage(int, int, int, int)     */    public int getCommand() {        // this returns 0 if an invalid message is set        return (getStatus() & 0xF0);    }      /**     * Obtains the first data byte in the message.     * @return the value of the <code>data1</code> field     * @see #setMessage(int, int, int)     */    public int getData1() {        if (length > 1) {            return (data[1] & 0xFF);        }        return 0;    }      /**     * Obtains the second data byte in the message.     * @return the value of the <code>data2</code> field     * @see #setMessage(int, int, int)     */    public int getData2() {        if (length > 2) {            return (data[2] & 0xFF);        }        return 0;    }      /**     * Creates a new object of the same class and with the same contents     * as this object.     * @return a clone of this instance.     */    public Object clone() {        byte[] newData = new byte[length];        System.arraycopy(data, 0, newData, 0, newData.length);         ShortMessage msg = new ShortMessage(newData);        return msg;    }      /**     * Retrieves the number of data bytes associated with a particular     * status byte value.     * @param status status byte value, which must represent a short MIDI message     * @return data length in bytes (0, 1, or 2)     * @throws <code>InvalidMidiDataException</code> if the     * <code>status</code> argument does not represent the status byte for any     * short message     */    protected final int getDataLength(int status) throws InvalidMidiDataException {        // system common and system real-time messages        switch(status) {        case 0xF6:                      // Tune Request        case 0xF7:                      // EOX            // System real-time messages        case 0xF8:                      // Timing Clock        case 0xF9:                      // Undefined        case 0xFA:                      // Start        case 0xFB:                      // Continue        case 0xFC:                      // Stop        case 0xFD:                      // Undefined        case 0xFE:                      // Active Sensing        case 0xFF:                      // System Reset            return 0;        case 0xF1:                      // MTC Quarter Frame        case 0xF3:                      // Song Select            return 1;        case 0xF2:                      // Song Position Pointer            return 2;        default:        }         // channel voice and mode messages        switch(status & 0xF0) {        case 0x80:        case 0x90:        case 0xA0:        case 0xB0:        case 0xE0:            return 2;        case 0xC0:        case 0xD0:            return 1;        default:            throw new InvalidMidiDataException("Invalid status byte: " + status);        }    }}