1 /* MidiDevice.java -- Interface for MIDI devices
2    Copyright (C) 2005 Free Software Foundation, Inc.
3 
4 This file is part of GNU Classpath.
5 
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10 
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15 
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING.  If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
20 
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library.  Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25 
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module.  An independent module is a module which is not derived from
33 or based on this library.  If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so.  If you do not wish to do so, delete this
36 exception statement from your version. */
37 
38 
39 package javax.sound.midi;
40 
41 /**
42  * Interface for all MIDI devices.
43  *
44  * @author Anthony Green (green@redhat.com)
45  * @since 1.3
46  *
47  */
48 public interface MidiDevice
49   extends AutoCloseable
50 {
51   /**
52    * Get the Info object describing this device.
53    * @return the Info object describing this device
54    */
getDeviceInfo()55   public Info getDeviceInfo();
56 
57   /**
58    * Open this MIDI device and allocate any system resource we need.
59    *
60    * @throws MidiUnavailableException if we're not able to open for some reason
61    */
open()62   public void open() throws MidiUnavailableException;
63 
64   /**
65    * Close this MIDI device, and release any system resources we're using.
66    */
close()67   public void close();
68 
69   /**
70    * Returns true if this MIDI device is open and false otherwise.
71    *
72    * @return true if this is open, false otherwise
73    */
isOpen()74   public boolean isOpen();
75 
76   /**
77    * If this device supports time-stamps, then it will return the number
78    * of microseconds since this device has been open, and -1 otherwise.
79    *
80    * @return -1 or the number of microseconds since this was opened
81    */
getMicrosecondPosition()82   public long getMicrosecondPosition();
83 
84   /**
85    * The maximum number of MIDI IN connections we can get as Receivers,
86    * or -1 if there is no maximum.
87    *
88    * @return -1 or the maximum number of Receivers we can get
89    */
getMaxReceivers()90   public int getMaxReceivers();
91 
92   /**
93    * The maximum number of MIDI OUT connections we can get as Transmitters,
94    * or -1 if there is no maximum.
95    *
96    * @return -1 or the maximum number of Transmitters we can get
97    */
getMaxTransmitters()98   public int getMaxTransmitters();
99 
100   /**
101    * Get a MIDI IN Receiver for this device.
102    *
103    * @return a MIDI IN Receiver for this device
104    * @throws MidiUnavailableException if we can't get a Receiver
105    */
getReceiver()106   public Receiver getReceiver() throws MidiUnavailableException;
107 
108   /**
109    * Get a MIDI OUT Transmitter for this device.
110    *
111    * @return a MIDI OUT Transmitter for this device
112    * @throws MidiUnavailableException if we can't get a Transmitter
113    */
getTransmitter()114   public Transmitter getTransmitter() throws MidiUnavailableException;
115 
116   /**
117    * A MIDI device descriptor object.
118    *
119    * @author green@redhat.com
120    *
121    */
122   public static class Info
123   {
124     // Private data describing this device
125     private String name;
126     private String vendor;
127     private String description;
128     private String version;
129 
130     /**
131      * Create an Info object for a MIDI device
132      *
133      * @param name the device name
134      * @param vendor the vendor name
135      * @param description the device description
136      * @param version the device version string
137      */
Info(String name, String vendor, String description, String version)138     protected Info(String name, String vendor, String description, String version)
139     {
140       this.name = name;
141       this.vendor = vendor;
142       this.description = description;
143       this.version = version;
144     }
145 
146     /**
147      * This equals method only returns true if this object
148      * is the same as obj.
149      *
150      * @param obj the object we're comparing to
151      * @return true if this is the same object
152      * @see java.lang.Object#equals(java.lang.Object)
153      */
equals(Object obj)154     public final boolean equals(Object obj)
155     {
156       return super.equals(obj);
157     }
158 
159     /**
160      * A hash code for this object.
161      *
162      * @return the hash code for this object
163      * @see java.lang.Object#hashCode()
164      */
hashCode()165     public final int hashCode()
166     {
167       return super.hashCode();
168     }
169 
170     /**
171      * Get the device name.
172      *
173      * @return the device name
174      */
getName()175     public final String getName()
176     {
177       return name;
178     }
179 
180     /**
181      * Get the device vendor.
182      *
183      * @return the device vendor
184      */
getVendor()185     public final String getVendor()
186     {
187       return vendor;
188     }
189 
190     /**
191      * Get the device description
192      *
193      * @return the device description
194      */
getDescription()195     public final String getDescription()
196     {
197       return description;
198     }
199 
200     /**
201      * get the device version
202      *
203      * @return the device version
204      */
getVersion()205     public final String getVersion()
206     {
207       return version;
208     }
209 
210     /**
211      * Simple return the name of the device.
212      *
213      * @return the device name
214      * @see java.lang.Object#toString()
215      */
toString()216     public final String toString()
217     {
218       return name;
219     }
220   }
221 }
222