Module java.desktop
Package javax.sound.midi

Interface MidiDevice

所有超接口:
AutoCloseable
所有已知子接口:
Sequencer, Synthesizer
public interface MidiDevice extends AutoCloseable
MidiDevice 是所有MIDI设备的基本接口。常见设备包括合成器、序列器、MIDI输入端口和MIDI输出端口。

MidiDevice 可以是MIDI事件的发送器或接收器，也可以同时兼具两者。因此，它可以提供Transmitter或Receiver实例（或两者）。通常，MIDI输入端口提供发送器，MIDI输出端口和合成器提供接收器。序列器通常提供用于播放的发送器和用于录制的接收器。

MidiDevice 可以显式打开和关闭，也可以隐式打开和关闭。显式打开是通过调用open()来实现的，显式关闭是通过调用MidiDevice实例上的close()来完成的。如果应用程序显式打开了一个MidiDevice，则必须显式关闭它以释放系统资源并使应用程序能够干净地退出。隐式打开是通过调用MidiSystem.getReceiver()和MidiSystem.getTransmitter()来实现的。由MidiSystem.getReceiver和MidiSystem.getTransmitter使用的MidiDevice取决于实现，除非使用属性javax.sound.midi.Receiver和javax.sound.midi.Transmitter（请参阅选择默认提供程序的属性描述MidiSystem）。隐式打开的MidiDevice通过关闭导致打开它的Receiver或Transmitter来隐式关闭。如果应用程序获得了多个隐式打开的Receiver或Transmitter，则在最后一个Receiver或Transmitter关闭后关闭设备。另一方面，在设备实例上直接调用getReceiver或getTransmitter不会隐式打开设备。关闭这些Transmitter和Receiver不会隐式关闭设备。要使用通过这种方式获得的带有Receiver或Transmitter的设备，必须显式打开和关闭设备。

如果在同一个MidiDevice实例上混合使用隐式和显式打开和关闭，则适用以下规则:

  • 在显式打开后（无论是在隐式打开之前还是之后），设备将不会被隐式关闭。显式打开的设备关闭的唯一方法是显式关闭。
  • 显式关闭始终会关闭设备，即使它也已隐式打开。随后的隐式关闭不会产生进一步效果。
要检测MidiDevice是否表示硬件MIDI端口，可以使用以下编程技术: 

 MidiDevice device = ...;
 if (!(device instanceof Sequencer) && !(device instanceof Synthesizer)) {
   // 现在我们确信设备表示MIDI端口
   // ...
 }

MidiDevice包括一个MidiDevice.Info对象，提供制造商信息等。

参见:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    MidiDevice.Info
    MidiDevice.Info对象包含有关MidiDevice的各种数据，包括其名称、创建者公司和描述性文本。

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    关闭设备，指示设备现在应释放其正在使用的任何系统资源。
    MidiDevice.Info
    getDeviceInfo()
    获取有关设备的信息，包括其Java类和包含其名称、供应商和描述的Strings。
    int
    getMaxReceivers()
    获取此MIDI设备上可用于接收MIDI数据的最大MIDI IN连接数。
    int
    getMaxTransmitters()
    获取此MIDI设备上可用于传输MIDI数据的最大MIDI OUT连接数。
    long
    getMicrosecondPosition()
    获取设备的当前时间戳，单位为微秒。
    Receiver
    getReceiver()
    通过此MIDI设备可能接收MIDI数据的MIDI IN接收器。
    List<Receiver>
    getReceivers()
    返回所有当前活动的、未关闭的与此MidiDevice连接的接收器。
    Transmitter
    getTransmitter()
    从中MIDI设备将传输MIDI数据的MIDI OUT连接。
    List<Transmitter>
    getTransmitters()
    返回所有当前活动的、未关闭的与此MidiDevice连接的发送器。
    boolean
    isOpen()
    报告设备是否打开。
    void
    open()
    打开设备，指示它现在应获取其所需的任何系统资源并变为可操作状态。

  • Method Details

    • getDeviceInfo

      MidiDevice.Info getDeviceInfo()
      获取有关设备的信息，包括其Java类和包含其名称、供应商和描述的Strings。
      返回:
      设备信息

    • open

      void open() throws MidiUnavailableException
      打开设备，指示它现在应获取其所需的任何系统资源并变为可操作状态。

      使用此调用显式打开设备的应用程序必须通过调用close()关闭设备。这是为了释放系统资源并允许应用程序干净退出。

      请注意，某些设备一旦关闭就无法重新打开。尝试重新打开此类设备将始终导致MidiUnavailableException。

      抛出:
      MidiUnavailableException - 如果由于资源限制而无法打开设备时抛出
      SecurityException - 如果由于安全限制而无法打开设备时抛出
      参见:

    • close

      void close()
      关闭设备，指示设备现在应释放其正在使用的任何系统资源。

      从此设备打开的所有Receiver和Transmitter实例都将被关闭。这包括通过MidiSystem检索的实例。

      由以下指定:
      close 在接口 AutoCloseable
      参见:

    • isOpen

      boolean isOpen()
      报告设备是否打开。
      返回:
      如果设备打开，则为true，否则为false
      参见:

    • getMicrosecondPosition

      long getMicrosecondPosition()
      获取设备的当前时间戳，单位为微秒。如果设备支持时间戳，则应在打开设备时从0开始计数，并在微秒中继续递增其时间戳，直到关闭设备。如果不支持时间戳，则应始终返回-1。
      返回:
      设备的当前时间戳（单位为微秒），如果设备不支持时间戳，则为-1

    • getMaxReceivers

      int getMaxReceivers()
      获取此MIDI设备上可用于接收MIDI数据的最大MIDI IN连接数。
      返回:
      MIDI IN连接的最大数量，如果可用的连接数量不受限制，则为-1

    • getMaxTransmitters

      int getMaxTransmitters()
      获取此MIDI设备上可用于传输MIDI数据的最大MIDI OUT连接数。
      返回:
      MIDI OUT连接的最大数量，如果可用的连接数量不受限制，则为-1

    • getReceiver

      Receiver getReceiver() throws MidiUnavailableException
      通过此MIDI设备可能接收MIDI数据的MIDI IN接收器。当应用程序使用完毕时，必须关闭返回的接收器。

      通常，返回的接收器实现MidiDeviceReceiver接口。

      使用此方法获取Receiver不会打开设备。要能够使用设备，必须通过调用open()显式打开设备。此外，关闭Receiver不会关闭设备。必须通过调用close()显式关闭设备。

      返回:
      设备的接收器
      抛出:
      MidiUnavailableException - 如果由于资源限制而无法获得接收器时抛出
      参见:

    • getReceivers

      List<Receiver> getReceivers()
      返回所有当前活动的、未关闭的与此MidiDevice连接的接收器。可以通过关闭接收器从设备中移除接收器。

      通常，返回的接收器实现MidiDeviceReceiver接口。

      返回:
      与此设备连接的所有当前活动的、未关闭的接收器的不可修改列表
      自:
      1.5

    • getTransmitter

      Transmitter getTransmitter() throws MidiUnavailableException
      从中获取一个 MIDI OUT 连接，通过该连接 MIDI 设备将传输 MIDI 数据。当应用程序使用完毕后，必须关闭返回的发射器。

      通常返回的发射器实现了 MidiDeviceTransmitter 接口。

      使用此方法获取 Transmitter 不会打开设备。要能够使用设备，必须显式调用 open() 打开设备。同样，关闭 Transmitter 不会关闭设备。必须显式调用 close() 关闭设备。

      返回：
      设备的 MIDI OUT 发射器
      抛出：
      MidiUnavailableException - 如果由于资源限制而无法使用发射器，则抛出
      参见：

    • getTransmitters

      List<Transmitter> getTransmitters()
      返回所有当前活动的、未关闭的与此 MidiDevice 连接的发射器。通过关闭发射器可以将其从设备中移除。

      通常返回的发射器实现了 MidiDeviceTransmitter 接口。

      返回：
      一个不可修改的打开发射器列表
      自：
      1.5