ShortMessage


1   /*
2    * @(#)ShortMessage.java    1.24 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.sound.midi;
9   
10  /**
11   * A <code>ShortMessage</code> contains a MIDI message that has at most
12   * two data bytes following its status byte.  The types of MIDI message
13   * that satisfy this criterion are channel voice, channel mode, system common,
14   * and system real-time--in other words, everything except system exclusive
15   * and meta-events.  The <code>ShortMessage</code> class provides methods
16   * for getting and setting the contents of the MIDI message.
17   * <p>
18   * A number of <code>ShortMessage</code> methods have integer parameters by which
19   * you specify a MIDI status or data byte.  If you know the numeric value, you
20   * can express it directly.  For system common and system real-time messages,
21   * you can often use the corresponding fields of <code>ShortMessage</code>, such as
22   * {@link #SYSTEM_RESET SYSTEM_RESET}.  For channel messages,
23   * the upper four bits of the status byte are specified by a command value and
24   * the lower four bits are specified by a MIDI channel number. To
25   * convert incoming MIDI data bytes that are in the form of Java's signed bytes,
26   * you can use the <A HREF="MidiMessage.html#integersVsBytes">conversion code</A>
27   * given in the <code>{@link MidiMessage}</code> class description.
28   *
29   * @see SysexMessage
30   * @see MetaMessage
31   *
32   * @version 1.24, 03/12/19
33   * @author David Rivas
34   * @author Kara Kytle
35   * @author Florian Bomers
36   */
37  
38  public class ShortMessage extends MidiMessage   {
39  
40  
41      // Status byte defines
42  
43  
44      // System common messages
45  
46      /**
47       * Status byte for MIDI Time Code Quarter Frame message (0xF1, or 241).
48       * @see MidiMessage#getStatus
49       */
50      public static final int MIDI_TIME_CODE              = 0xF1; // 241
51  
52      /**
53       * Status byte for Song Position Pointer message (0xF2, or 242).
54       * @see MidiMessage#getStatus
55       */
56      public static final int SONG_POSITION_POINTER       = 0xF2; // 242
57  
58      /**
59       * Status byte for MIDI Song Select message (0xF3, or 243).
60       * @see MidiMessage#getStatus
61       */
62      public static final int SONG_SELECT                 = 0xF3; // 243
63  
64      /**
65       * Status byte for Tune Request message (0xF6, or 246).
66       * @see MidiMessage#getStatus
67       */
68      public static final int TUNE_REQUEST                = 0xF6; // 246
69  
70      /**
71       * Status byte for End of System Exclusive message (0xF7, or 247).
72       * @see MidiMessage#getStatus
73       */
74      public static final int END_OF_EXCLUSIVE            = 0xF7; // 247
75  
76  
77      // System real-time messages
78  
79      /**
80       * Status byte for Timing Clock messagem (0xF8, or 248).
81       * @see MidiMessage#getStatus
82       */
83      public static final int TIMING_CLOCK                = 0xF8; // 248
84  
85      /**
86       * Status byte for Start message (0xFA, or 250).
87       * @see MidiMessage#getStatus
88       */
89      public static final int START                       = 0xFA; // 250
90  
91      /**
92       * Status byte for Continue message (0xFB, or 251).
93       * @see MidiMessage#getStatus
94       */
95      public static final int CONTINUE                    = 0xFB; // 251
96  
97      /**
98       * Status byte for Stop message (0xFC, or 252).
99       * @see MidiMessage#getStatus
100      */
101     public static final int STOP                        = 0xFC; //252
102 
103     /**
104      * Status byte for Active Sensing message (0xFE, or 254).
105      * @see MidiMessage#getStatus
106      */
107     public static final int ACTIVE_SENSING              = 0xFE; // 254
108 
109     /**
110      * Status byte for System Reset message (0xFF, or 255).
111      * @see MidiMessage#getStatus
112      */
113     public static final int SYSTEM_RESET                = 0xFF; // 255
114 
115 
116     // Channel voice message upper nibble defines
117 
118     /**
119      * Command value for Note Off message (0x80, or 128)
120      */
121     public static final int NOTE_OFF                    = 0x80;  // 128
122 
123     /**
124      * Command value for Note On message (0x90, or 144)
125      */
126     public static final int NOTE_ON                     = 0x90;  // 144
127 
128     /**
129      * Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or 128)
130      */
131     public static final int POLY_PRESSURE               = 0xA0;  // 160
132 
133     /**
134      * Command value for Control Change message (0xB0, or 176)
135      */
136     public static final int CONTROL_CHANGE              = 0xB0;  // 176
137 
138     /**
139      * Command value for Program Change message (0xC0, or 192)
140      */
141     public static final int PROGRAM_CHANGE              = 0xC0;  // 192
142 
143     /**
144      * Command value for Channel Pressure (Aftertouch) message (0xD0, or 208)
145      */
146     public static final int CHANNEL_PRESSURE            = 0xD0;  // 208
147 
148     /**
149      * Command value for Pitch Bend message (0xE0, or 224)
150      */
151     public static final int PITCH_BEND                  = 0xE0;  // 224
152 
153 
154     // Instance variables
155 
156     /**
157      * Constructs a new <code>ShortMessage</code>.  The
158      * contents of the new message are guaranteed to specify
159      * a valid MIDI message.  Subsequently, you may set the
160      * contents of the message using one of the <code>setMessage</code>
161      * methods.
162      * @see #setMessage
163      */
164     public ShortMessage() {
165     this(new byte[3]);
166     // Default message data: NOTE_ON on Channel 0 with max volume
167     data[0] = (byte) (NOTE_ON & 0xFF);
168     data[1] = (byte) 64;
169     data[2] = (byte) 127;
170     length = 3;
171     }
172 
173 
174     /**
175      * Constructs a new <code>ShortMessage</code>.
176      * @param data an array of bytes containing the complete message.
177      * The message data may be changed using the <code>setMessage</code>
178      * method.
179      * @see #setMessage
180      */
181     // $$fb this should throw an Exception in case of an illegal message!
182     protected ShortMessage(byte[] data) {
183     // $$fb this may set an invalid message.
184     // Can't correct without compromising compatibility
185     super(data);
186     }
187 
188 
189     /**
190      * Sets the parameters for a MIDI message that takes no data bytes.
191      * @param status    the MIDI status byte
192      * @throws  <code>InvalidMidiDataException</code> if <code>status</code> does not
193      * specify a valid MIDI status byte for a message that requires no data bytes.
194      * @see #setMessage(int, int, int)
195      * @see #setMessage(int, int, int, int)
196      */
197     public void setMessage(int status) throws InvalidMidiDataException   {
198     // check for valid values
199     int dataLength = getDataLength(status); // can throw InvalidMidiDataException
200     if (dataLength != 0) {
201         throw new InvalidMidiDataException  ("Status byte; " + status + " requires " + dataLength + " data bytes");
202     }
203     setMessage(status, 0, 0);
204     }
205 
206 
207     /**
208      * Sets the  parameters for a MIDI message that takes one or two data
209      * bytes.  If the message takes only one data byte, the second data
210      * byte is ignored; if the message does not take any data bytes, both
211      * data bytes are ignored.
212      *
213      * @param status    the MIDI status byte
214      * @param data1     the first data byte
215      * @param data2     the second data byte
216      * @throws  <code>InvalidMidiDataException</code> if the
217      * the status byte, or all data bytes belonging to the message, do
218      * not specify a valid MIDI message.
219      * @see #setMessage(int, int, int, int)
220      * @see #setMessage(int)
221      */
222     public void setMessage(int status, int data1, int data2) throws InvalidMidiDataException   {
223     // check for valid values
224     int dataLength = getDataLength(status); // can throw InvalidMidiDataException
225     if (dataLength > 0) {
226         if (data1 < 0 || data1 > 127) {
227         throw new InvalidMidiDataException  ("data1 out of range: " + data1);
228         }
229         if (dataLength > 1) {
230         if (data2 < 0 || data2 > 127) {
231             throw new InvalidMidiDataException  ("data2 out of range: " + data2);
232         }
233         }
234     }
235 
236 
237     // set the length
238     length = dataLength + 1;
239     // re-allocate array if ShortMessage(byte[]) constructor gave array with fewer elements
240     if (data == null || data.length < length) {
241         data = new byte[3];
242     }
243 
244     // set the data
245     data[0] = (byte) (status & 0xFF);
246     if (length > 1) {
247         data[1] = (byte) (data1 & 0xFF);
248         if (length > 2) {
249         data[2] = (byte) (data2 & 0xFF);
250         }
251     }
252     }
253 
254 
255     /**
256      * Sets the short message parameters for a  channel message
257      * which takes up to two data bytes.  If the message only
258      * takes one data byte, the second data byte is ignored; if
259      * the message does not take any data bytes, both data bytes
260      * are ignored.
261      *
262      * @param command   the MIDI command represented by this message
263      * @param channel   the channel associated with the message
264      * @param data1     the first data byte
265      * @param data2     the second data byte
266      * @throws      <code>InvalidMidiDataException</code> if the
267      * status byte or all data bytes belonging to the message, do
268      * not specify a valid MIDI message
269      *
270      * @see #setMessage(int, int, int)
271      * @see #setMessage(int)
272      * @see #getCommand
273      * @see #getChannel
274      * @see #getData1
275      * @see #getData2
276      */
277     public void setMessage(int command, int channel, int data1, int data2) throws InvalidMidiDataException   {
278     // check for valid values
279     if (command >= 0xF0 || command < 0x80) {
280         throw new InvalidMidiDataException  ("command out of range: 0x" + Integer.toHexString(command));
281     }
282     if ((channel & 0xFFFFFFF0) != 0) { // <=> (channel<0 || channel>15)
283         throw new InvalidMidiDataException  ("channel out of range: " + channel);
284     }
285     setMessage((command & 0xF0) | (channel & 0x0F), data1, data2);
286     }
287 
288 
289     /**
290      * Obtains the MIDI channel associated with this event.  This method
291      * assumes that the event is a MIDI channel message; if not, the return
292      * value will not be meaningful.
293      * @return MIDI channel associated with the message.
294      * @see #setMessage(int, int, int, int)
295      */
296     public int getChannel() {
297     // this returns 0 if an invalid message is set
298     return (getStatus() & 0x0F);
299     }
300 
301 
302     /**
303      * Obtains the MIDI command associated with this event.  This method
304      * assumes that the event is a MIDI channel message; if not, the return
305      * value will not be meaningful.
306      * @see #setMessage(int, int, int, int)
307      */
308     public int getCommand() {
309     // this returns 0 if an invalid message is set
310     return (getStatus() & 0xF0);
311     }
312 
313 
314     /**
315      * Obtains the first data byte in the message.
316      * @return the value of the <code>data1</code> field
317      * @see #setMessage(int, int, int)
318      */
319     public int getData1() {
320     if (length > 1) {
321         return (data[1] & 0xFF);
322     }
323     return 0;
324     }
325 
326 
327     /**
328      * Obtains the second data byte in the message.
329      * @return the value of the <code>data2</code> field
330      * @see #setMessage(int, int, int)
331      */
332     public int getData2() {
333     if (length > 2) {
334         return (data[2] & 0xFF);
335     }
336     return 0;
337     }
338 
339 
340     /**
341      * Creates a new object of the same class and with the same contents
342      * as this object.
343      * @return a clone of this instance.
344      */
345     public Object   clone() {
346     byte[] newData = new byte[length];
347     System.arraycopy(data, 0, newData, 0, newData.length);
348 
349     ShortMessage   msg = new ShortMessage  (newData);
350     return msg;
351     }
352 
353 
354     /**
355      * Retrieves the number of data bytes associated with a particular
356      * status byte value.
357      * @param status status byte value, which must represent a short MIDI message
358      * @return data length in bytes (0, 1, or 2)
359      * @throws <code>InvalidMidiDataException</code> if the
360      * <code>status</code> argument does not represent the status byte for any
361      * short message
362      */
363     protected final int getDataLength(int status) throws InvalidMidiDataException   {
364     // system common and system real-time messages
365     switch(status) {
366     case 0xF6:          // Tune Request
367     case 0xF7:          // EOX
368         // System real-time messages
369     case 0xF8:          // Timing Clock
370     case 0xF9:          // Undefined
371     case 0xFA:          // Start
372     case 0xFB:          // Continue
373     case 0xFC:          // Stop
374     case 0xFD:          // Undefined
375     case 0xFE:          // Active Sensing
376     case 0xFF:          // System Reset
377         return 0;
378     case 0xF1:          // MTC Quarter Frame
379     case 0xF3:          // Song Select
380         return 1;
381     case 0xF2:          // Song Position Pointer
382         return 2;
383     default:
384     }
385 
386     // channel voice and mode messages
387     switch(status & 0xF0) {
388     case 0x80:
389     case 0x90:
390     case 0xA0:
391     case 0xB0:
392     case 0xE0:
393         return 2;
394     case 0xC0:
395     case 0xD0:
396         return 1;
397     default:
398         throw new InvalidMidiDataException  ("Invalid status byte: " + status);
399     }
400     }
401 }
402
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags