001/* MidiDevice.java -- Interface for MIDI devices
002   Copyright (C) 2005 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.sound.midi;
040
041/**
042 * Interface for all MIDI devices.
043 *
044 * @author Anthony Green (green@redhat.com)
045 * @since 1.3
046 *
047 */
048public interface MidiDevice
049  extends AutoCloseable
050{
051  /**
052   * Get the Info object describing this device.
053   * @return the Info object describing this device
054   */
055  public Info getDeviceInfo();
056
057  /**
058   * Open this MIDI device and allocate any system resource we need.
059   *
060   * @throws MidiUnavailableException if we're not able to open for some reason
061   */
062  public void open() throws MidiUnavailableException;
063
064  /**
065   * Close this MIDI device, and release any system resources we're using.
066   */
067  public void close();
068
069  /**
070   * Returns true if this MIDI device is open and false otherwise.
071   *
072   * @return true if this is open, false otherwise
073   */
074  public boolean isOpen();
075
076  /**
077   * If this device supports time-stamps, then it will return the number
078   * of microseconds since this device has been open, and -1 otherwise.
079   *
080   * @return -1 or the number of microseconds since this was opened
081   */
082  public long getMicrosecondPosition();
083
084  /**
085   * The maximum number of MIDI IN connections we can get as Receivers,
086   * or -1 if there is no maximum.
087   *
088   * @return -1 or the maximum number of Receivers we can get
089   */
090  public int getMaxReceivers();
091
092  /**
093   * The maximum number of MIDI OUT connections we can get as Transmitters,
094   * or -1 if there is no maximum.
095   *
096   * @return -1 or the maximum number of Transmitters we can get
097   */
098  public int getMaxTransmitters();
099
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   */
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   */
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     */
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     */
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     */
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     */
175    public final String getName()
176    {
177      return name;
178    }
179
180    /**
181     * Get the device vendor.
182     *
183     * @return the device vendor
184     */
185    public final String getVendor()
186    {
187      return vendor;
188    }
189
190    /**
191     * Get the device description
192     *
193     * @return the device description
194     */
195    public final String getDescription()
196    {
197      return description;
198    }
199
200    /**
201     * get the device version
202     *
203     * @return the device version
204     */
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     */
216    public final String toString()
217    {
218      return name;
219    }
220  }
221}