/*
 * @(#)ShortMessage.java	1.24 03/12/19
 *
 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

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
 *
 * @version 1.24, 03/12/19
 * @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 128)
     */
    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</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);
	}
    }
}