1 /*
2 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sound.midi;
27
28 /**
29 * A {@code MetaMessage} is a {@link MidiMessage} that is not meaningful to
30 * synthesizers, but that can be stored in a MIDI file and interpreted by a
31 * sequencer program. (See the discussion in the {@code MidiMessage} class
32 * description.) The Standard MIDI Files specification defines various types of
33 * meta-events, such as sequence number, lyric, cue point, and set tempo. There
34 * are also meta-events for such information as lyrics, copyrights, tempo
35 * indications, time and key signatures, markers, etc. For more information, see
36 * the Standard MIDI Files 1.0 specification, which is part of the Complete MIDI
37 * 1.0 Detailed Specification published by the MIDI Manufacturer's Association
38 * (<a href = http://www.midi.org>http://www.midi.org</a>).
39 * <p>
40 * When data is being transported using MIDI wire protocol, a
41 * {@link ShortMessage} with the status value {@code 0xFF} represents a system
42 * reset message. In MIDI files, this same status value denotes a
43 * {@code MetaMessage}. The types of meta-message are distinguished from each
44 * other by the first byte that follows the status byte {@code 0xFF}. The
45 * subsequent bytes are data bytes. As with system exclusive messages, there are
46 * an arbitrary number of data bytes, depending on the type of
47 * {@code MetaMessage}.
48 *
49 * @author David Rivas
50 * @author Kara Kytle
51 * @see MetaEventListener
52 */
53 public class MetaMessage extends MidiMessage {
54
55 /**
56 * Status byte for {@code MetaMessage} (0xFF, or 255), which is used in MIDI
57 * files. It has the same value as SYSTEM_RESET, which is used in the
58 * real-time "MIDI wire" protocol.
59 *
60 * @see MidiMessage#getStatus
61 */
62 public static final int META = 0xFF; // 255
63
64 /**
65 * The length of the actual message in the data array. This is used to
66 * determine how many bytes of the data array is the message, and how many
67 * are the status byte, the type byte, and the variable-length-int
68 * describing the length of the message.
69 */
70 private int dataLength = 0;
71
72 /**
73 * Constructs a new {@code MetaMessage}. The contents of the message are not
74 * set here; use {@link #setMessage(int, byte[], int) setMessage} to set
75 * them subsequently.
76 */
77 public MetaMessage() {
78 // Default meta message data: just the META status byte value
79 this(new byte[]{(byte) META, 0});
80 }
81
82 /**
83 * Constructs a new {@code MetaMessage} and sets the message parameters. The
84 * contents of the message can be changed by using the {@code setMessage}
85 * method.
86 *
87 * @param type meta-message type (must be less than 128)
88 * @param data the data bytes in the MIDI message
89 * @param length an amount of bytes in the {@code data} byte array; it
90 * should be non-negative and less than or equal to
91 * {@code data.length}
92 * @throws InvalidMidiDataException if the parameter values do not specify a
93 * valid MIDI meta message
94 * @see #setMessage(int, byte[], int)
95 * @see #getType()
96 * @see #getData()
97 * @since 1.7
98 */
99 public MetaMessage(int type, byte[] data, int length)
100 throws InvalidMidiDataException {
101 super(null);
102 setMessage(type, data, length); // can throw InvalidMidiDataException
103 }
104
105 /**
106 * Constructs a new {@code MetaMessage}.
107 *
108 * @param data an array of bytes containing the complete message. The
109 * message data may be changed using the {@code setMessage} method.
110 * @see #setMessage
111 */
112 protected MetaMessage(byte[] data) {
113 super(data);
114 //$$fb 2001-10-06: need to calculate dataLength. Fix for bug #4511796
115 if (data.length>=3) {
116 dataLength=data.length-3;
117 int pos=2;
118 while (pos<data.length && (data[pos] & 0x80)!=0) {
119 dataLength--; pos++;
120 }
121 }
122 }
123
124 /**
125 * Sets the message parameters for a {@code MetaMessage}. Since only one
126 * status byte value, {@code 0xFF}, is allowed for meta-messages, it does
127 * not need to be specified here. Calls to
128 * {@link MidiMessage#getStatus getStatus} return {@code 0xFF} for all
129 * meta-messages.
130 * <p>
131 * The {@code type} argument should be a valid value for the byte that
132 * follows the status byte in the {@code MetaMessage}. The {@code data}
133 * argument should contain all the subsequent bytes of the
134 * {@code MetaMessage}. In other words, the byte that specifies the type of
135 * {@code MetaMessage} is not considered a data byte.
136 *
137 * @param type meta-message type (must be less than 128)
138 * @param data the data bytes in the MIDI message
139 * @param length the number of bytes in the {@code data} byte array
140 * @throws InvalidMidiDataException if the parameter values do not specify a
141 * valid MIDI meta message
142 */
143 public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException {
144
145 if (type >= 128 || type < 0) {
146 throw new InvalidMidiDataException("Invalid meta event with type " + type);
147 }
148 if ((length > 0 && length > data.length) || length < 0) {
149 throw new InvalidMidiDataException("length out of bounds: "+length);
150 }
151
152 this.length = 2 + getVarIntLength(length) + length;
153 this.dataLength = length;
154 this.data = new byte[this.length];
155 this.data[0] = (byte) META; // status value for MetaMessages (meta events)
156 this.data[1] = (byte) type; // MetaMessage type
157 writeVarInt(this.data, 2, length); // write the length as a variable int
158 if (length > 0) {
159 System.arraycopy(data, 0, this.data, this.length - this.dataLength, this.dataLength);
160 }
161 }
162
163 /**
164 * Obtains the type of the {@code MetaMessage}.
165 *
166 * @return an integer representing the {@code MetaMessage} type
167 */
168 public int getType() {
169 if (length>=2) {
170 return data[1] & 0xFF;
171 }
172 return 0;
173 }
174
175 /**
176 * Obtains a copy of the data for the meta message. The returned array of
177 * bytes does not include the status byte or the message length data. The
178 * length of the data for the meta message is the length of the array. Note
179 * that the length of the entire message includes the status byte and the
180 * meta message type byte, and therefore may be longer than the returned
181 * array.
182 *
183 * @return array containing the meta message data
184 * @see MidiMessage#getLength
185 */
186 public byte[] getData() {
187 byte[] returnedArray = new byte[dataLength];
188 System.arraycopy(data, (length - dataLength), returnedArray, 0, dataLength);
189 return returnedArray;
190 }
191
192 /**
193 * Creates a new object of the same class and with the same contents as this
194 * object.
195 *
196 * @return a clone of this instance
197 */
198 @Override
199 public Object clone() {
200 byte[] newData = new byte[length];
201 System.arraycopy(data, 0, newData, 0, newData.length);
202
203 MetaMessage event = new MetaMessage(newData);
204 return event;
205 }
206
207 // HELPER METHODS
208
209 private int getVarIntLength(long value) {
210 int length = 0;
211 do {
212 value = value >> 7;
213 length++;
214 } while (value > 0);
215 return length;
216 }
217
218 private static final long mask = 0x7F;
219
220 private void writeVarInt(byte[] data, int off, long value) {
221 int shift=63; // number of bitwise left-shifts of mask
222 // first screen out leading zeros
223 while ((shift > 0) && ((value & (mask << shift)) == 0)) shift-=7;
224 // then write actual values
225 while (shift > 0) {
226 data[off++]=(byte) (((value & (mask << shift)) >> shift) | 0x80);
227 shift-=7;
228 }
229 data[off] = (byte) (value & mask);
230 }
231 }