midi-communications-windows 0.0.3

data/docs/testing-on-windows.md

@@ -0,0 +1,222 @@
+# Testing this gem on Windows without MIDI hardware
+
+*Written 2026-09-06. Section 1 is the part with a shelf life: it describes
+software that was in preview at the time, which Microsoft's release notes said
+was headed for Windows 11 25H2 and later during the last week of November 2026.
+If that has happened, most of section 1 collapses into "nothing to install" and
+the rest still applies.*
+
+This is **the procedure the library was measured with**, not a promise that it
+works on another machine. All of it ran once, on one particular installation.
+Where something was checked, it says so; where it was not, it says that too.
+
+The machine was:
+
+| | |
+|---|---|
+| Windows | 11 25H2, build **26200.9278** |
+| CPU | ARM64 — a VMware VM on Apple silicon |
+| Ruby | 3.4.10 `x64-mingw-ucrt`, **emulated** under Prism (no ARM64 Ruby present) |
+| ffi | 1.17.4 `x64-mingw-ucrt`, precompiled binary |
+| MIDI hardware | **none** — no USB device passed through to the guest |
+
+That last row is why this document exists: with no hardware, a loopback pair is
+the only way to exercise input and output at the same time.
+
+Nothing measured on this setup says anything about **timing**. Emulation inside
+a virtual machine; latency and jitter need real hardware and a native Ruby.
+
+---
+
+## 1. What has to be installed
+
+Windows 11 25H2 ships **Windows MIDI Services** in the box: the `midisrv`
+service (`C:\Windows\System32\midisrv.exe`) and the `wdmaud2.drv` shim,
+registered as `midi1` under
+`HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Drivers32`. That shim is what
+makes endpoints from the new stack **visible to WinMM** without this gem doing
+anything special, and therefore what makes this setup able to test a gem that
+speaks only WinMM.
+
+What is *not* in the box are the MIDI 1.0 loopback transport and the tools. Those
+come from the [`microsoft/MIDI`] repository, release `inbox-dev-preview-6`:
+
+- `Windows.MIDI.Services.Basic.MIDI.1.0.Loopback.Preview.1.0.18-preview.3-arm64.exe`
+- `Windows.MIDI.Services.Tools.0.99.64-devpreview.6-arm64.exe`
+
+There are `-x64` variants of both. The measuring machine used the **native ARM64**
+ones (PE header `0xAA64`) even though the Ruby was emulated x64: the gem talks to
+`winmm.dll`, and Windows handles the crossing.
+
+The Network and Bluetooth transports from the same release are not needed.
+
+[`microsoft/MIDI`]: https://github.com/microsoft/MIDI/releases
+
+### Warnings that are not optional
+
+- **These are unsigned preview binaries.** The release notes require Windows
+  **Developer Mode**, and are explicit: *"There are almost certainly bugs and
+  missing/incomplete features."* This is not production software.
+- **Do not redistribute them.** The release's permitted-use table forbids it. A
+  repository should link to the release and never host the installers.
+- Minimum system version declared: **Windows 11 25H2**.
+- Downloaded through a browser they carry Mark of the Web and SmartScreen will
+  object; `Unblock-File` clears it. Fetched with `Invoke-WebRequest` they do not.
+
+## 2. Installing
+
+Both installers are **WiX bundles**, so they accept `/quiet`, `/norestart` and
+`/log`. Both need **elevation**, and Developer Mode writes to `HKLM`, so it is
+worth doing the whole thing in one elevated script and getting one UAC prompt.
+
+The release notes fix the order: **loopback transport first, tools second.**
+
+```powershell
+# --- 1. Developer Mode (the key may not exist)
+$k = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock'
+if (-not (Test-Path $k)) { New-Item $k -Force | Out-Null }
+Set-ItemProperty $k -Name AllowDevelopmentWithoutDevLicense -Value 1 -Type DWord
+Set-ItemProperty $k -Name AllowAllTrustedApps -Value 1 -Type DWord
+
+# --- 2. installers, in this order
+Start-Process -Wait -FilePath '<...>Basic.MIDI.1.0.Loopback.Preview...-arm64.exe' `
+  -ArgumentList '/quiet','/norestart','/log','loopback.log'
+Start-Process -Wait -FilePath '<...>Tools.0.99.64-devpreview.6-arm64.exe' `
+  -ArgumentList '/quiet','/norestart','/log','tools.log'
+```
+
+**Both return exit `3010`**, which is `ERROR_SUCCESS_REBOOT_REQUIRED`: installed
+correctly, reboot pending. The measuring machine **was not rebooted**, and every
+measurement was taken that way. If something behaves oddly, that reboot is the
+first suspect.
+
+To check the transport registered:
+
+```powershell
+Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\Windows MIDI Services\Transport Plugins'
+# Midi2BasicLoopbackMidiTransport should appear, with Enabled = 1
+```
+
+### `midi.exe` and the PATH
+
+The console lands at:
+
+```
+C:\Program Files\Windows MIDI Services\Tools\Console\midi.exe
+```
+
+The installer **does** add it to the machine PATH, but **a shell opened before
+installing still has the old environment** and will say `midi` does not exist. In
+a fresh shell, `midi` is enough; in the installing shell, use the full path. This
+detail cost time and produced one wrong report before it was noticed.
+
+## 3. Creating the loopback pair
+
+```powershell
+$midi = 'C:\Program Files\Windows MIDI Services\Tools\Console\midi.exe'
+
+& $midi basic-loopback create --name "Reloj Bitwig ñ prueba de longitud"
+& $midi basic-loopback list
+```
+
+Options for `create`:
+
+| option | what it does |
+|---|---|
+| `-n`, `--name` | the endpoint's name |
+| `-u`, `--unique-identifier` | an identifier of your own |
+| `-s`, `--save-to-config` | **persists it in the system configuration** |
+
+**Without `--save-to-config` a loopback is temporary**: it disappears when
+`midisrv` or the machine restarts, and nothing is written to disk. Every
+measurement was taken that way, deliberately. `--save-to-config` does modify the
+user's system configuration — ask before using it.
+
+A `create` returns an **Association Id**, a GUID. Keep it: it is the only thing
+that will remove the loopback again.
+
+### Checking through WinMM, which is what the gem sees
+
+```
+ruby -Ilib examples/list_ports.rb
+```
+
+One loopback shows up as **one input and one output with the same name, byte for
+byte**. With two loopbacks created, enumeration gives 2 inputs and 3 outputs —
+the third being the *Microsoft GS Wavetable Synth*, which is always there.
+
+## 4. The name-collision recipe
+
+WinMM stores **31 characters** of a name (`MAXPNAMELEN` is 32, less the NUL) and
+drops the rest **silently**. To reproduce the case where two distinct ports are
+indistinguishable, create two loopbacks whose **first 31 characters match**:
+
+```powershell
+& $midi basic-loopback create --name "Reloj Bitwig ñ prueba de longitud"
+& $midi basic-loopback create --name "Reloj Bitwig ñ prueba de longitud DOS"
+```
+
+The first is 33 characters, the second 37; both truncate to
+`Reloj Bitwig ñ prueba de longit`. In `MIDIINCAPSW`/`MIDIOUTCAPSW` they come back
+**identical field by field**: same name, same `wMid` (1), same `wPid` (25 for
+inputs, 26 for outputs), same `vDriverVersion`, same `wTechnology`. Only the
+index separates them.
+
+If you change the names, keep the character counts working — the recipe depends
+on one being longer than 31 and both agreeing up to that point.
+
+The truncation happens **upstream of WinMM**: `midi enumerate
+midi-services-endpoints` shows the service already holding the 31-character name.
+Whether the console or the service truncates was not determined; for the gem it
+makes no difference.
+
+The `ñ` survives intact (`U+00F1` in the UTF-16LE dump), which is what validates
+the **W** entry points against a genuinely non-ASCII character.
+
+## 5. Removing
+
+```powershell
+& $midi basic-loopback remove --association-id "{bfba125e-3aca-446c-9b94-692a70153034}"
+```
+
+**The braces around the GUID are required.** `list` prints the id without them;
+they have to be added.
+
+Afterwards, check the machine is back where it started — with `list`, and better
+still by enumerating through WinMM: with no loopbacks there should be **0 inputs
+and 1 output**.
+
+## 6. What this setup can test, and what it cannot
+
+Exercised with it, and working: enumeration with colliding names, short messages
+in all three lengths (3, 2 and 1 bytes), accumulation in `gets`, System Exclusive
+both ways at 200, 3000 and 5000 bytes, buffer recycling, closing and reopening,
+and the propagation of an error from opening a port.
+
+**Not testable with this setup**, and therefore still untested:
+
+- **`SYSEX_TIMEOUT` / `Output#wait_until_sent`.** The only real output device is
+  the *GS Wavetable Synth*, a software synthesiser that marks `MHDR_DONE` in
+  under a millisecond because there is no wire. This needs a physical interface.
+- **`RESET_TIMEOUT` / `Input#await_returned_buffers`.** It never came close:
+  closes took between 4 and 21 ms against a one-second bound. The
+  device-went-away path needs something to unplug.
+- **Renumbering in `Device.enumerate`.** Needs a port to actually appear or go.
+- **`MM_MIM_LONGERROR`.** None could be provoked, not even with a System
+  Exclusive message larger than the entire buffer queue. The code handling it is
+  unexercised — its presence has been shown harmless, which is not the same
+  thing.
+- **That an input and an output of the same device share a name.** Established
+  for a loopback, where they are literally the same device. Not for a real USB
+  interface.
+- **Any measurement of time.**
+
+Those are the items a session with real hardware should close.
+
+## 7. One finding from here worth not forgetting
+
+Multi-client access **follows the endpoint, not the API**. Two WinMM clients on
+the same BLOOP input both work and **both receive every message**. The *GS
+Wavetable Synth*, which belongs to the classic `wdmaud` stack, refuses the second
+open with *"The specified device is already in use."* So on one machine, through
+one API, shareable ports and exclusive ports coexist.

data/examples/input.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+$:.unshift(File.join('..', 'lib'))
+
+require 'midi-communications-windows'
+
+# This program selects the first midi input and sends an inspection of the first
+# 10 messages it receives to standard out
+#
+# gets blocks until something arrives, so this loop needs no delay of its own
+
+num_messages = 10
+
+MIDICommunicationsWindows::Input.first.open do |input|
+  puts "Using input: #{input.id}, #{input.name}"
+
+  puts 'send some MIDI to your input now...'
+
+  received = 0
+  while received < num_messages
+    input.gets.each do |message|
+      puts message.inspect
+      received += 1
+    end
+  end
+
+  puts 'finished'
+end

data/examples/list_ports.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+$:.unshift(File.join('..', 'lib'))
+
+require 'midi-communications-windows'
+
+# This lists every MIDI port WinMM offers, in both directions.
+#
+# The ids are indexes within a direction, so input 0 and output 0 are different
+# ports. Names come back truncated to 31 characters, which is all WinMM stores.
+
+%i[input output].each do |direction|
+  puts "#{direction}s:"
+
+  MIDICommunicationsWindows::Device.all_by_type[direction].each do |port|
+    puts "  #{port.id}: #{port.name}"
+  end
+end

data/examples/output.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+$:.unshift(File.join('..', 'lib'))
+
+require 'midi-communications-windows'
+
+# This program selects the first midi output and sends some arpeggiated chords to it
+#
+# examples/list_ports.rb will list your midi ports
+
+notes = [36, 40, 43] # C E G
+octaves = 5
+duration = 0.1
+
+MIDICommunicationsWindows::Output.first.open do |output|
+  (0..((octaves - 1) * 12)).step(12) do |oct|
+    notes.each do |note|
+      output.puts(0x90, note + oct, 100) # note on
+      sleep(duration) # wait
+      output.puts(0x80, note + oct, 100) # note off
+    end
+  end
+end

data/examples/sysex_output.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+$:.unshift(File.join('..', 'lib'))
+
+require 'midi-communications-windows'
+
+# This example outputs a raw sysex message to the first output port
+# there will not be any output to the console
+#
+# The call does not return until the device reports the message sent, which at
+# MIDI's 31250 baud takes about 320 microseconds per byte
+
+output = MIDICommunicationsWindows::Output.first
+sysex_msg = [0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7]
+
+output.open { |port| port.puts(sysex_msg) }

data/lib/midi-communications-windows/api.rb

@@ -0,0 +1,340 @@
+module MIDICommunicationsWindows
+  # Raised when a WinMM call reports a failure.
+  #
+  # WinMM reports errors as `MMRESULT` codes rather than by any out-of-band
+  # mechanism, so every call is checked and a failure becomes an exception at
+  # the point of the call, carrying the text WinMM itself gives for the code.
+  #
+  # @api public
+  class Error < StandardError
+    # @!attribute [r] code
+    #   @return [Integer, nil] the `MMRESULT` WinMM returned, or nil for a
+    #     failure WinMM did not report as a code — a call that never completed,
+    #     for instance
+    # @!attribute [r] operation
+    #   @return [Symbol] the WinMM function that failed, e.g. `:midiInOpen`
+    attr_reader :code, :operation
+
+    # @param operation [Symbol] the WinMM function that failed
+    # @param code [Integer, nil] the `MMRESULT` code, if there was one
+    # @param text [String, nil] a description of the failure
+    # @api private
+    def initialize(operation, code, text = nil)
+      @operation = operation
+      @code = code
+
+      super(build_message(operation, code, text))
+    end
+
+    private
+
+    # @api private
+    def build_message(operation, code, text)
+      return "#{operation}: #{text}" unless text.nil? || text.empty?
+
+      code.nil? ? "#{operation} failed" : "#{operation} failed with MMRESULT #{code}"
+    end
+  end
+
+  # Low-level FFI bindings to the Windows Multimedia (WinMM) MIDI API.
+  #
+  # This module binds `winmm.dll` directly. Most users should use the
+  # higher-level {Input}, {Output} and {Device} instead.
+  #
+  # ## Why the bindings look the way they do
+  #
+  # **Pointer-sized types are never `:ulong`.** Windows is LLP64: `long` stays
+  # 32 bits on 64-bit Windows while `HANDLE`, `DWORD_PTR` and `UINT_PTR` are
+  # pointer-sized. Measured from inside FFI on Windows 11 x64:
+  # `FFI::Pointer.size` is 8 and `FFI.type_size(:ulong)` is 4. Declaring a
+  # handle as `:ulong` truncates it — silently, because the low half of a
+  # handle often looks plausible. Every pointer-sized parameter here is
+  # `:uintptr_t`.
+  #
+  # **The `W` variants, never the `A` ones.** `midiInGetDevCapsA` returns the
+  # port name in the machine's ANSI code page, which mangles any name that is
+  # not ASCII. A user-created loopback called "Reloj Bitwig" is a realistic
+  # port name, so the wide-character functions are the only correct choice.
+  #
+  # **`dwCallback` is `:uintptr_t`, not a callback type.** WinMM overloads that
+  # parameter by the flags in `dwFlags`: it holds a function pointer under
+  # `CALLBACK_FUNCTION`, a thread id under `CALLBACK_THREAD`, a window handle
+  # under `CALLBACK_WINDOW`, and nothing under `CALLBACK_NULL`. Typing it as a
+  # callback would make the binding lie about three of those four.
+  #
+  # These bindings were written from Microsoft's Win32 documentation. They are
+  # not derived from any existing Ruby binding.
+  #
+  # @api private
+  module API
+    extend FFI::Library
+
+    # user32 and kernel32 come in for the thread message queue, which is how
+    # input is delivered; see {Input}. FFI searches all three for each function.
+    ffi_lib 'winmm', 'user32', 'kernel32'
+    # Ignored on x64, where there is a single calling convention; required on
+    # 32-bit Windows, where WinMM is stdcall.
+    ffi_convention :stdcall
+
+    typedef :uint8, :BYTE
+    typedef :uint16, :WORD
+    typedef :uint32, :DWORD
+    typedef :uint32, :MMRESULT
+    typedef :uintptr_t, :DWORD_PTR
+    typedef :uintptr_t, :UINT_PTR
+    # Handles are opaque and pointer-sized. See the note above on LLP64.
+    typedef :uintptr_t, :HMIDIIN
+    typedef :uintptr_t, :HMIDIOUT
+
+    # Length of a port name in `MIDIINCAPSW`/`MIDIOUTCAPSW`, in characters,
+    # including the terminating NUL. This is the origin of WinMM's 31-character
+    # limit on port names.
+    MAXPNAMELEN = 32
+
+    # `MMRESULT` value meaning success.
+    MMSYSERR_NOERROR = 0
+
+    # Characters reserved for an error description. WinMM truncates to fit.
+    MAX_ERROR_TEXT_LENGTH = 256
+
+    # How WinMM should notify a client of input. Passed in `dwFlags`; decides
+    # how `dwCallback` is interpreted.
+    CALLBACK_NULL     = 0x0000_0000
+    CALLBACK_WINDOW   = 0x0001_0000
+    CALLBACK_THREAD   = 0x0002_0000
+    CALLBACK_FUNCTION = 0x0003_0000
+
+    # Notification messages delivered for an input device.
+    MM_MIM_OPEN      = 0x3C1
+    MM_MIM_CLOSE     = 0x3C2
+    MM_MIM_DATA      = 0x3C3
+    MM_MIM_LONGDATA  = 0x3C4
+    MM_MIM_ERROR     = 0x3C5
+    MM_MIM_LONGERROR = 0x3C6
+
+    # Notification messages delivered for an output device.
+    MM_MOM_OPEN  = 0x3C7
+    MM_MOM_CLOSE = 0x3C8
+    MM_MOM_DONE  = 0x3C9
+
+    # `MIDIHDR#dwFlags` bits.
+    MHDR_DONE     = 0x0000_0001
+    MHDR_PREPARED = 0x0000_0002
+    MHDR_INQUEUE  = 0x0000_0004
+
+    # Thread message queue.
+    WM_QUIT     = 0x0012
+    PM_NOREMOVE = 0x0000
+
+    # Windows posts messages of its own to the same queue WinMM uses. Measured:
+    # a `WM_USER` with both parameters zero follows every WinMM notification,
+    # including those after the port opens and closes. Nothing here emits them
+    # and nothing here knows what does, so the reader dispatches on the message
+    # id and ignores everything it did not ask for.
+    WM_USER = 0x0400
+
+    # Capabilities of a MIDI input device, as `midiInGetDevCapsW` fills it.
+    #
+    # `szPname` is an array of UTF-16 code units, not of bytes: the field is
+    # declared as `:uint16` so that reading it cannot split a character in half.
+    class MIDIInCaps < FFI::Struct
+      layout :wMid, :uint16,
+             :wPid, :uint16,
+             :vDriverVersion, :uint32,
+             :szPname, [:uint16, MAXPNAMELEN],
+             :dwSupport, :uint32
+    end
+
+    # Capabilities of a MIDI output device, as `midiOutGetDevCapsW` fills it.
+    class MIDIOutCaps < FFI::Struct
+      layout :wMid, :uint16,
+             :wPid, :uint16,
+             :vDriverVersion, :uint32,
+             :szPname, [:uint16, MAXPNAMELEN],
+             :wTechnology, :uint16,
+             :wVoices, :uint16,
+             :wNotes, :uint16,
+             :wChannelMask, :uint16,
+             :dwSupport, :uint32
+    end
+
+    # Both capability structures have a size fixed by the Win32 headers, and
+    # WinMM rejects a call whose `cbSize` disagrees with what it expects. A
+    # mismatch here means the layout above is wrong, and every field read from
+    # it afterwards would be garbage that still looks like data — so it is
+    # checked once, at load, rather than discovered as a puzzling device name
+    # much later.
+    #
+    # Verified against Windows 11 25H2 (build 26200), winmm.dll 10.0.26100.
+    raise "MIDIINCAPSW is #{MIDIInCaps.size} bytes, expected 76" unless MIDIInCaps.size == 76
+    raise "MIDIOUTCAPSW is #{MIDIOutCaps.size} bytes, expected 84" unless MIDIOutCaps.size == 84
+
+    # A buffer handed to WinMM, used for System Exclusive in both directions.
+    #
+    # `dwReserved` really is an array of eight pointer-sized words. Declaring it
+    # as a single word makes the structure too short, and WinMM writes past the
+    # end of it. This layout measures 120 bytes on 64-bit Windows, which is what
+    # WinMM there expects.
+    class MIDIHdr < FFI::Struct
+      layout :lpData, :pointer,
+             :dwBufferLength, :uint32,
+             :dwBytesRecorded, :uint32,
+             :dwUser, :uintptr_t,
+             :dwFlags, :uint32,
+             :lpNext, :pointer,
+             :reserved, :uintptr_t,
+             :dwOffset, :uint32,
+             :dwReserved, [:uintptr_t, 8]
+    end
+
+    # Measured against winmm on 64-bit Windows 11. Checked only there, because
+    # the layout's size follows the pointer size and 32-bit Windows produces a
+    # different, equally correct, number.
+    if FFI::Pointer.size == 8 && MIDIHdr.size != 120
+      raise "MIDIHDR is #{MIDIHdr.size} bytes on 64-bit Windows, expected 120"
+    end
+
+    # Enumeration. These touch no device and can fire no callback, so they are
+    # the only calls here that keep the GVL.
+    attach_function :midiInGetNumDevs, [], :uint32
+    attach_function :midiOutGetNumDevs, [], :uint32
+    attach_function :midiInGetDevCapsW, %i[UINT_PTR pointer uint32], :MMRESULT
+    attach_function :midiOutGetDevCapsW, %i[UINT_PTR pointer uint32], :MMRESULT
+
+    # EVERY CALL BELOW RELEASES THE GVL, and that is not an optimisation.
+    #
+    # Measured on Windows 11 25H2 against a system loopback: with an input open
+    # and a Ruby callback attached to it, a `midiOutShortMsg` that holds the GVL
+    # deadlocks against the driver thread waiting for that same GVL to enter the
+    # callback. The shim eventually gives up, the send returns MMSYSERR_ERROR,
+    # and — this is the part that matters — the message is then delivered
+    # TWICE, a second or two later. Three sends produced five, four and five
+    # deliveries across three runs. System Exclusive behaved the same way: 400
+    # bytes received for a 200-byte message.
+    #
+    # Two controls place the cause: sending with no input open succeeds, and so
+    # does sending with an input open under CALLBACK_NULL. It is not the send,
+    # and it is not having an input open. It is a Ruby callback waiting for the
+    # GVL held by the thread that is sending.
+    #
+    # The failure is quiet. Nothing raises; the port simply emits notes nobody
+    # asked for. So the rule is structural rather than case by case: anything
+    # that can reach a device is declared blocking, and a function added here
+    # later should be too.
+    attach_function :midiInOpen, %i[pointer uint32 DWORD_PTR DWORD_PTR DWORD], :MMRESULT, blocking: true
+    attach_function :midiInClose, [:HMIDIIN], :MMRESULT, blocking: true
+    attach_function :midiInStart, [:HMIDIIN], :MMRESULT, blocking: true
+    attach_function :midiInStop, [:HMIDIIN], :MMRESULT, blocking: true
+    attach_function :midiInReset, [:HMIDIIN], :MMRESULT, blocking: true
+
+    attach_function :midiOutOpen, %i[pointer uint32 DWORD_PTR DWORD_PTR DWORD], :MMRESULT, blocking: true
+    attach_function :midiOutClose, [:HMIDIOUT], :MMRESULT, blocking: true
+    attach_function :midiOutReset, [:HMIDIOUT], :MMRESULT, blocking: true
+
+    # Sending
+    attach_function :midiOutShortMsg, %i[HMIDIOUT DWORD], :MMRESULT, blocking: true
+    attach_function :midiOutLongMsg, %i[HMIDIOUT pointer uint32], :MMRESULT, blocking: true
+    attach_function :midiOutPrepareHeader, %i[HMIDIOUT pointer uint32], :MMRESULT, blocking: true
+    attach_function :midiOutUnprepareHeader, %i[HMIDIOUT pointer uint32], :MMRESULT, blocking: true
+
+    # Receiving System Exclusive
+    attach_function :midiInPrepareHeader, %i[HMIDIIN pointer uint32], :MMRESULT, blocking: true
+    attach_function :midiInUnprepareHeader, %i[HMIDIIN pointer uint32], :MMRESULT, blocking: true
+    attach_function :midiInAddBuffer, %i[HMIDIIN pointer uint32], :MMRESULT, blocking: true
+
+    # Diagnostics
+    attach_function :midiInGetErrorTextW, %i[MMRESULT pointer uint32], :MMRESULT
+    attach_function :midiOutGetErrorTextW, %i[MMRESULT pointer uint32], :MMRESULT
+
+    # A message waiting in a thread's queue.
+    #
+    # `POINT pt` is spelled out as two fields because nothing here reads it and
+    # a nested structure would earn its keep only in a mouse handler. The size
+    # is 48 bytes on 64-bit Windows, which is what the queue functions expect.
+    class MSG < FFI::Struct
+      layout :hwnd, :pointer,
+             :message, :uint32,
+             :wParam, :uintptr_t,
+             # LPARAM is a signed LONG_PTR in the headers. It is read unsigned
+             # here because every value this library takes from it is either a
+             # packed MIDI word or a pointer, and a high address arriving as a
+             # negative number would not survive being turned back into one.
+             :lParam, :uintptr_t,
+             :time, :uint32,
+             :pt_x, :int32,
+             :pt_y, :int32
+    end
+
+    raise "MSG is #{MSG.size} bytes on 64-bit Windows, expected 48" if FFI::Pointer.size == 8 && MSG.size != 48
+
+    # The thread message queue.
+    #
+    # `GetMessageW` blocks, so it releases the GVL like everything else that can
+    # wait. It returns an int and not a boolean: above zero for a message, zero
+    # for `WM_QUIT`, and -1 for an error — which is why `BOOL` is bound as `:int`
+    # throughout. FFI's `:bool` is one byte and would read only the low half of
+    # a `BOOL` that Windows defines as a four-byte int.
+    attach_function :GetCurrentThreadId, [], :uint32
+    attach_function :GetMessageW, %i[pointer pointer uint32 uint32], :int, blocking: true
+    attach_function :PeekMessageW, %i[pointer pointer uint32 uint32 uint32], :int
+    attach_function :PostThreadMessageW, %i[uint32 uint32 uintptr_t uintptr_t], :int
+
+    module_function
+
+    # Raises unless the call succeeded.
+    #
+    # @param code [Integer] the `MMRESULT` a WinMM call returned
+    # @param operation [Symbol] the function that returned it, for the message
+    # @param direction [Symbol] `:input` or `:output`, to pick the error table
+    # @return [void]
+    # @raise [Error] when `code` is anything but `MMSYSERR_NOERROR`
+    def check!(code, operation, direction)
+      return if code == MMSYSERR_NOERROR
+
+      raise Error.new(operation, code, error_text(code, direction))
+    end
+
+    # WinMM's own description of an error code.
+    #
+    # The two error tables are not the same, which is why the direction has to
+    # be known: the same numeric code can mean different things for input and
+    # for output.
+    #
+    # @param code [Integer] an `MMRESULT`
+    # @param direction [Symbol] `:input` or `:output`
+    # @return [String, nil] the description, or nil if WinMM has none
+    def error_text(code, direction)
+      buffer = FFI::MemoryPointer.new(:uint16, MAX_ERROR_TEXT_LENGTH)
+
+      result = case direction
+               when :input then midiInGetErrorTextW(code, buffer, MAX_ERROR_TEXT_LENGTH)
+               when :output then midiOutGetErrorTextW(code, buffer, MAX_ERROR_TEXT_LENGTH)
+               end
+
+      read_wide_string(buffer, MAX_ERROR_TEXT_LENGTH) if result == MMSYSERR_NOERROR
+    end
+
+    # Reads a NUL-terminated UTF-16LE string out of native memory.
+    #
+    # Reading is done in code units rather than bytes on purpose: a byte-wise
+    # search for a NUL pair would stop in the middle of a pair such as
+    # `'A' 'Ā'` (`41 00 00 01`) and return a truncated name.
+    #
+    # A name that does not decode is repaired rather than raised on: a port
+    # whose name arrives mangled is still a port the caller may want to open,
+    # and losing the whole enumeration over one bad character would be worse
+    # than showing a replacement character.
+    #
+    # @param pointer [FFI::Pointer] memory holding the string
+    # @param max_characters [Integer] capacity of the field, in characters
+    # @return [String] the decoded string, in UTF-8
+    def read_wide_string(pointer, max_characters)
+      units = pointer.read_array_of_uint16(max_characters)
+      units = units.take_while { |unit| !unit.zero? }
+
+      units.pack('S<*')
+           .force_encoding(Encoding::UTF_16LE)
+           .encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    end
+  end
+end