midi-communications-windows 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +8 -0
  3. data/.version +6 -0
  4. data/.yardoc/checksums +8 -0
  5. data/.yardoc/complete +0 -0
  6. data/.yardoc/object_types +0 -0
  7. data/.yardoc/objects/root.dat +0 -0
  8. data/.yardoc/proxy_types +0 -0
  9. data/.yardopts +8 -0
  10. data/Gemfile +3 -0
  11. data/LICENSE +165 -0
  12. data/README.md +176 -0
  13. data/Rakefile +13 -0
  14. data/doc/MIDICommunicationsWindows/API/MIDIHdr.html +144 -0
  15. data/doc/MIDICommunicationsWindows/API/MIDIInCaps.html +142 -0
  16. data/doc/MIDICommunicationsWindows/API/MIDIOutCaps.html +140 -0
  17. data/doc/MIDICommunicationsWindows/API/MSG.html +143 -0
  18. data/doc/MIDICommunicationsWindows/API.html +981 -0
  19. data/doc/MIDICommunicationsWindows/Device/ClassMethods.html +365 -0
  20. data/doc/MIDICommunicationsWindows/Device/InstanceMethods.html +1096 -0
  21. data/doc/MIDICommunicationsWindows/Device.html +988 -0
  22. data/doc/MIDICommunicationsWindows/Error.html +438 -0
  23. data/doc/MIDICommunicationsWindows/Input.html +1554 -0
  24. data/doc/MIDICommunicationsWindows/Message.html +700 -0
  25. data/doc/MIDICommunicationsWindows/Output.html +1697 -0
  26. data/doc/MIDICommunicationsWindows/TypeConversion.html +369 -0
  27. data/doc/MIDICommunicationsWindows.html +210 -0
  28. data/doc/_index.html +262 -0
  29. data/doc/class_list.html +54 -0
  30. data/doc/css/common.css +1 -0
  31. data/doc/css/full_list.css +206 -0
  32. data/doc/css/style.css +1089 -0
  33. data/doc/file.README.html +240 -0
  34. data/doc/file.testing-on-windows.html +253 -0
  35. data/doc/file_list.html +64 -0
  36. data/doc/frames.html +22 -0
  37. data/doc/index.html +240 -0
  38. data/doc/js/app.js +801 -0
  39. data/doc/js/full_list.js +334 -0
  40. data/doc/js/jquery.js +4 -0
  41. data/doc/method_list.html +382 -0
  42. data/doc/top-level-namespace.html +112 -0
  43. data/docs/testing-on-windows.md +222 -0
  44. data/examples/input.rb +27 -0
  45. data/examples/list_ports.rb +17 -0
  46. data/examples/output.rb +22 -0
  47. data/examples/sysex_output.rb +15 -0
  48. data/lib/midi-communications-windows/api.rb +340 -0
  49. data/lib/midi-communications-windows/device.rb +310 -0
  50. data/lib/midi-communications-windows/input.rb +486 -0
  51. data/lib/midi-communications-windows/message.rb +133 -0
  52. data/lib/midi-communications-windows/output.rb +206 -0
  53. data/lib/midi-communications-windows/type_conversion.rb +20 -0
  54. data/lib/midi-communications-windows/version.rb +4 -0
  55. data/lib/midi-communications-windows.rb +76 -0
  56. data/midi-communications-windows.gemspec +32 -0
  57. metadata +220 -0
data/doc/MIDICommunicationsWindows/API.html ADDED
@@ -0,0 +1,981 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ Module: MIDICommunicationsWindows::API
8
+
9
+ &mdash; MIDI Communications Windows API
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="../css/style.css" type="text/css">
14
+
15
+ <link rel="stylesheet" href="../css/common.css" type="text/css">
16
+
17
+ <script type="text/javascript">
18
+ pathId = "MIDICommunicationsWindows::API";
19
+ relpath = '../';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div id="main_progress" aria-hidden="true"></div>
31
+
32
+ <div class="nav_wrap">
33
+ <iframe id="nav" src="../class_list.html?1"></iframe>
34
+ <div id="resizer"></div>
35
+ </div>
36
+
37
+ <div id="main" tabindex="-1">
38
+ <div id="header">
39
+ <div id="menu">
40
+
41
+ <a href="../_index.html">Index (A)</a> &raquo;
42
+ <span class='title'><span class='object_link'><a href="../MIDICommunicationsWindows.html" title="MIDICommunicationsWindows (module)">MIDICommunicationsWindows</a></span></span>
43
+ &raquo;
44
+ <span class="title">API</span>
45
+
46
+ </div>
47
+
48
+ <div id="search">
49
+
50
+ <a class="full_list_link" id="class_list_link"
51
+ href="../class_list.html">
52
+
53
+ <svg width="24" height="24">
54
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
55
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
56
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
57
+ </svg>
58
+ </a>
59
+
60
+ </div>
61
+ <div class="clear"></div>
62
+ </div>
63
+
64
+ <div id="content"><h1>Module: MIDICommunicationsWindows::API
65
+
66
+
67
+ <span class="private note title">Private</span>
68
+ </h1>
69
+ <div class="box_info">
70
+
71
+
72
+
73
+
74
+ <dl>
75
+ <dt>Extended by:</dt>
76
+ <dd>FFI::Library</dd>
77
+ </dl>
78
+
79
+
80
+
81
+
82
+
83
+
84
+
85
+
86
+ <dl>
87
+ <dt>Defined in:</dt>
88
+ <dd>lib/midi-communications-windows/api.rb
89
+ </dd>
90
+ </dl>
91
+
92
+ </div>
93
+
94
+ <h2>Overview</h2><div class="docstring">
95
+ <div class="discussion">
96
+ <p class="note private">
97
+ <strong>This module is part of a private API.</strong>
98
+ You should avoid using this module if possible, as it may be removed or be changed in the future.
99
+ </p>
100
+ <p>Low-level FFI bindings to the Windows Multimedia (WinMM) MIDI API.</p>
101
+ <p>This module binds <code>winmm.dll</code> directly. Most users should use the
102
+ higher-level <span class='object_link'><a href="Input.html" title="MIDICommunicationsWindows::Input (class)">Input</a></span>, <span class='object_link'><a href="Output.html" title="MIDICommunicationsWindows::Output (class)">Output</a></span> and <span class='object_link'><a href="Device.html" title="MIDICommunicationsWindows::Device (module)">Device</a></span> instead.</p>
103
+ <h2 id="Why_the_bindings_look_the_way_they_do">Why the bindings look the way they do</h2>
104
+ <p><strong>Pointer-sized types are never <code>:ulong</code>.</strong> Windows is LLP64: <code>long</code> stays
105
+ 32 bits on 64-bit Windows while <code>HANDLE</code>, <code>DWORD_PTR</code> and <code>UINT_PTR</code> are
106
+ pointer-sized. Measured from inside FFI on Windows 11 x64:
107
+ <code>FFI::Pointer.size</code> is 8 and <code>FFI.type_size(:ulong)</code> is 4. Declaring a
108
+ handle as <code>:ulong</code> truncates it — silently, because the low half of a
109
+ handle often looks plausible. Every pointer-sized parameter here is
110
+ <code>:uintptr_t</code>.</p>
111
+ <p><strong>The <code>W</code> variants, never the <code>A</code> ones.</strong> <code>midiInGetDevCapsA</code> returns the
112
+ port name in the machine's ANSI code page, which mangles any name that is
113
+ not ASCII. A user-created loopback called &quot;Reloj Bitwig&quot; is a realistic
114
+ port name, so the wide-character functions are the only correct choice.</p>
115
+ <p><strong><code>dwCallback</code> is <code>:uintptr_t</code>, not a callback type.</strong> WinMM overloads that
116
+ parameter by the flags in <code>dwFlags</code>: it holds a function pointer under
117
+ <code>CALLBACK_FUNCTION</code>, a thread id under <code>CALLBACK_THREAD</code>, a window handle
118
+ under <code>CALLBACK_WINDOW</code>, and nothing under <code>CALLBACK_NULL</code>. Typing it as a
119
+ callback would make the binding lie about three of those four.</p>
120
+ <p>These bindings were written from Microsoft's Win32 documentation. They are
121
+ not derived from any existing Ruby binding.</p>
122
+
123
+ </div>
124
+ </div>
125
+ <div class="tags">
126
+
127
+
128
+ </div><h2>Defined Under Namespace</h2>
129
+ <p class="children">
130
+
131
+
132
+
133
+
134
+ <strong class="classes">Classes:</strong> <span class='object_link'><a href="API/MIDIHdr.html" title="MIDICommunicationsWindows::API::MIDIHdr (class)">MIDIHdr</a></span>, <span class='object_link'><a href="API/MIDIInCaps.html" title="MIDICommunicationsWindows::API::MIDIInCaps (class)">MIDIInCaps</a></span>, <span class='object_link'><a href="API/MIDIOutCaps.html" title="MIDICommunicationsWindows::API::MIDIOutCaps (class)">MIDIOutCaps</a></span>, <span class='object_link'><a href="API/MSG.html" title="MIDICommunicationsWindows::API::MSG (class)">MSG</a></span>
135
+
136
+
137
+ </p>
138
+
139
+
140
+ <h2>
141
+ Constant Summary
142
+ <small><a href="#" class="constants_summary_toggle">collapse</a></small>
143
+ </h2>
144
+
145
+ <dl class="constants">
146
+
147
+ <dt id="MAXPNAMELEN-constant" class="">MAXPNAMELEN =
148
+ <div class="docstring">
149
+ <div class="discussion">
150
+ <p class="note private">
151
+ <strong>This constant is part of a private API.</strong>
152
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
153
+ </p>
154
+ <p>Length of a port name in <code>MIDIINCAPSW</code>/<code>MIDIOUTCAPSW</code>, in characters,
155
+ including the terminating NUL. This is the origin of WinMM's 31-character
156
+ limit on port names.</p>
157
+
158
+ </div>
159
+ </div>
160
+ <div class="tags">
161
+
162
+
163
+ </div>
164
+ </dt>
165
+ <dd><pre class="code"><span class='int'>32</span></pre></dd>
166
+
167
+ <dt id="MMSYSERR_NOERROR-constant" class="">MMSYSERR_NOERROR =
168
+ <div class="docstring">
169
+ <div class="discussion">
170
+ <p class="note private">
171
+ <strong>This constant is part of a private API.</strong>
172
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
173
+ </p>
174
+ <p><code>MMRESULT</code> value meaning success.</p>
175
+
176
+ </div>
177
+ </div>
178
+ <div class="tags">
179
+
180
+
181
+ </div>
182
+ </dt>
183
+ <dd><pre class="code"><span class='int'>0</span></pre></dd>
184
+
185
+ <dt id="MAX_ERROR_TEXT_LENGTH-constant" class="">MAX_ERROR_TEXT_LENGTH =
186
+ <div class="docstring">
187
+ <div class="discussion">
188
+ <p class="note private">
189
+ <strong>This constant is part of a private API.</strong>
190
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
191
+ </p>
192
+ <p>Characters reserved for an error description. WinMM truncates to fit.</p>
193
+
194
+ </div>
195
+ </div>
196
+ <div class="tags">
197
+
198
+
199
+ </div>
200
+ </dt>
201
+ <dd><pre class="code"><span class='int'>256</span></pre></dd>
202
+
203
+ <dt id="CALLBACK_NULL-constant" class="">CALLBACK_NULL =
204
+ <div class="docstring">
205
+ <div class="discussion">
206
+ <p class="note private">
207
+ <strong>This constant is part of a private API.</strong>
208
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
209
+ </p>
210
+ <p>How WinMM should notify a client of input. Passed in <code>dwFlags</code>; decides
211
+ how <code>dwCallback</code> is interpreted.</p>
212
+
213
+ </div>
214
+ </div>
215
+ <div class="tags">
216
+
217
+
218
+ </div>
219
+ </dt>
220
+ <dd><pre class="code"><span class='int'>0x0000_0000</span></pre></dd>
221
+
222
+ <dt id="CALLBACK_WINDOW-constant" class="">CALLBACK_WINDOW =
223
+ <div class="docstring">
224
+ <div class="discussion">
225
+ <p class="note private">
226
+ <strong>This constant is part of a private API.</strong>
227
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
228
+ </p>
229
+
230
+
231
+ </div>
232
+ </div>
233
+ <div class="tags">
234
+
235
+
236
+ </div>
237
+ </dt>
238
+ <dd><pre class="code"><span class='int'>0x0001_0000</span></pre></dd>
239
+
240
+ <dt id="CALLBACK_THREAD-constant" class="">CALLBACK_THREAD =
241
+ <div class="docstring">
242
+ <div class="discussion">
243
+ <p class="note private">
244
+ <strong>This constant is part of a private API.</strong>
245
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
246
+ </p>
247
+
248
+
249
+ </div>
250
+ </div>
251
+ <div class="tags">
252
+
253
+
254
+ </div>
255
+ </dt>
256
+ <dd><pre class="code"><span class='int'>0x0002_0000</span></pre></dd>
257
+
258
+ <dt id="CALLBACK_FUNCTION-constant" class="">CALLBACK_FUNCTION =
259
+ <div class="docstring">
260
+ <div class="discussion">
261
+ <p class="note private">
262
+ <strong>This constant is part of a private API.</strong>
263
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
264
+ </p>
265
+
266
+
267
+ </div>
268
+ </div>
269
+ <div class="tags">
270
+
271
+
272
+ </div>
273
+ </dt>
274
+ <dd><pre class="code"><span class='int'>0x0003_0000</span></pre></dd>
275
+
276
+ <dt id="MM_MIM_OPEN-constant" class="">MM_MIM_OPEN =
277
+ <div class="docstring">
278
+ <div class="discussion">
279
+ <p class="note private">
280
+ <strong>This constant is part of a private API.</strong>
281
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
282
+ </p>
283
+ <p>Notification messages delivered for an input device.</p>
284
+
285
+ </div>
286
+ </div>
287
+ <div class="tags">
288
+
289
+
290
+ </div>
291
+ </dt>
292
+ <dd><pre class="code"><span class='int'>0x3C1</span></pre></dd>
293
+
294
+ <dt id="MM_MIM_CLOSE-constant" class="">MM_MIM_CLOSE =
295
+ <div class="docstring">
296
+ <div class="discussion">
297
+ <p class="note private">
298
+ <strong>This constant is part of a private API.</strong>
299
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
300
+ </p>
301
+
302
+
303
+ </div>
304
+ </div>
305
+ <div class="tags">
306
+
307
+
308
+ </div>
309
+ </dt>
310
+ <dd><pre class="code"><span class='int'>0x3C2</span></pre></dd>
311
+
312
+ <dt id="MM_MIM_DATA-constant" class="">MM_MIM_DATA =
313
+ <div class="docstring">
314
+ <div class="discussion">
315
+ <p class="note private">
316
+ <strong>This constant is part of a private API.</strong>
317
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
318
+ </p>
319
+
320
+
321
+ </div>
322
+ </div>
323
+ <div class="tags">
324
+
325
+
326
+ </div>
327
+ </dt>
328
+ <dd><pre class="code"><span class='int'>0x3C3</span></pre></dd>
329
+
330
+ <dt id="MM_MIM_LONGDATA-constant" class="">MM_MIM_LONGDATA =
331
+ <div class="docstring">
332
+ <div class="discussion">
333
+ <p class="note private">
334
+ <strong>This constant is part of a private API.</strong>
335
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
336
+ </p>
337
+
338
+
339
+ </div>
340
+ </div>
341
+ <div class="tags">
342
+
343
+
344
+ </div>
345
+ </dt>
346
+ <dd><pre class="code"><span class='int'>0x3C4</span></pre></dd>
347
+
348
+ <dt id="MM_MIM_ERROR-constant" class="">MM_MIM_ERROR =
349
+ <div class="docstring">
350
+ <div class="discussion">
351
+ <p class="note private">
352
+ <strong>This constant is part of a private API.</strong>
353
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
354
+ </p>
355
+
356
+
357
+ </div>
358
+ </div>
359
+ <div class="tags">
360
+
361
+
362
+ </div>
363
+ </dt>
364
+ <dd><pre class="code"><span class='int'>0x3C5</span></pre></dd>
365
+
366
+ <dt id="MM_MIM_LONGERROR-constant" class="">MM_MIM_LONGERROR =
367
+ <div class="docstring">
368
+ <div class="discussion">
369
+ <p class="note private">
370
+ <strong>This constant is part of a private API.</strong>
371
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
372
+ </p>
373
+
374
+
375
+ </div>
376
+ </div>
377
+ <div class="tags">
378
+
379
+
380
+ </div>
381
+ </dt>
382
+ <dd><pre class="code"><span class='int'>0x3C6</span></pre></dd>
383
+
384
+ <dt id="MM_MOM_OPEN-constant" class="">MM_MOM_OPEN =
385
+ <div class="docstring">
386
+ <div class="discussion">
387
+ <p class="note private">
388
+ <strong>This constant is part of a private API.</strong>
389
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
390
+ </p>
391
+ <p>Notification messages delivered for an output device.</p>
392
+
393
+ </div>
394
+ </div>
395
+ <div class="tags">
396
+
397
+
398
+ </div>
399
+ </dt>
400
+ <dd><pre class="code"><span class='int'>0x3C7</span></pre></dd>
401
+
402
+ <dt id="MM_MOM_CLOSE-constant" class="">MM_MOM_CLOSE =
403
+ <div class="docstring">
404
+ <div class="discussion">
405
+ <p class="note private">
406
+ <strong>This constant is part of a private API.</strong>
407
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
408
+ </p>
409
+
410
+
411
+ </div>
412
+ </div>
413
+ <div class="tags">
414
+
415
+
416
+ </div>
417
+ </dt>
418
+ <dd><pre class="code"><span class='int'>0x3C8</span></pre></dd>
419
+
420
+ <dt id="MM_MOM_DONE-constant" class="">MM_MOM_DONE =
421
+ <div class="docstring">
422
+ <div class="discussion">
423
+ <p class="note private">
424
+ <strong>This constant is part of a private API.</strong>
425
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
426
+ </p>
427
+
428
+
429
+ </div>
430
+ </div>
431
+ <div class="tags">
432
+
433
+
434
+ </div>
435
+ </dt>
436
+ <dd><pre class="code"><span class='int'>0x3C9</span></pre></dd>
437
+
438
+ <dt id="MHDR_DONE-constant" class="">MHDR_DONE =
439
+ <div class="docstring">
440
+ <div class="discussion">
441
+ <p class="note private">
442
+ <strong>This constant is part of a private API.</strong>
443
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
444
+ </p>
445
+ <p><code>MIDIHDR#dwFlags</code> bits.</p>
446
+
447
+ </div>
448
+ </div>
449
+ <div class="tags">
450
+
451
+
452
+ </div>
453
+ </dt>
454
+ <dd><pre class="code"><span class='int'>0x0000_0001</span></pre></dd>
455
+
456
+ <dt id="MHDR_PREPARED-constant" class="">MHDR_PREPARED =
457
+ <div class="docstring">
458
+ <div class="discussion">
459
+ <p class="note private">
460
+ <strong>This constant is part of a private API.</strong>
461
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
462
+ </p>
463
+
464
+
465
+ </div>
466
+ </div>
467
+ <div class="tags">
468
+
469
+
470
+ </div>
471
+ </dt>
472
+ <dd><pre class="code"><span class='int'>0x0000_0002</span></pre></dd>
473
+
474
+ <dt id="MHDR_INQUEUE-constant" class="">MHDR_INQUEUE =
475
+ <div class="docstring">
476
+ <div class="discussion">
477
+ <p class="note private">
478
+ <strong>This constant is part of a private API.</strong>
479
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
480
+ </p>
481
+
482
+
483
+ </div>
484
+ </div>
485
+ <div class="tags">
486
+
487
+
488
+ </div>
489
+ </dt>
490
+ <dd><pre class="code"><span class='int'>0x0000_0004</span></pre></dd>
491
+
492
+ <dt id="WM_QUIT-constant" class="">WM_QUIT =
493
+ <div class="docstring">
494
+ <div class="discussion">
495
+ <p class="note private">
496
+ <strong>This constant is part of a private API.</strong>
497
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
498
+ </p>
499
+ <p>Thread message queue.</p>
500
+
501
+ </div>
502
+ </div>
503
+ <div class="tags">
504
+
505
+
506
+ </div>
507
+ </dt>
508
+ <dd><pre class="code"><span class='int'>0x0012</span></pre></dd>
509
+
510
+ <dt id="PM_NOREMOVE-constant" class="">PM_NOREMOVE =
511
+ <div class="docstring">
512
+ <div class="discussion">
513
+ <p class="note private">
514
+ <strong>This constant is part of a private API.</strong>
515
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
516
+ </p>
517
+
518
+
519
+ </div>
520
+ </div>
521
+ <div class="tags">
522
+
523
+
524
+ </div>
525
+ </dt>
526
+ <dd><pre class="code"><span class='int'>0x0000</span></pre></dd>
527
+
528
+ <dt id="WM_USER-constant" class="">WM_USER =
529
+ <div class="docstring">
530
+ <div class="discussion">
531
+ <p class="note private">
532
+ <strong>This constant is part of a private API.</strong>
533
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
534
+ </p>
535
+ <p>Windows posts messages of its own to the same queue WinMM uses. Measured:
536
+ a <code>WM_USER</code> with both parameters zero follows every WinMM notification,
537
+ including those after the port opens and closes. Nothing here emits them
538
+ and nothing here knows what does, so the reader dispatches on the message
539
+ id and ignores everything it did not ask for.</p>
540
+
541
+ </div>
542
+ </div>
543
+ <div class="tags">
544
+
545
+
546
+ </div>
547
+ </dt>
548
+ <dd><pre class="code"><span class='int'>0x0400</span></pre></dd>
549
+
550
+ </dl>
551
+
552
+
553
+
554
+
555
+
556
+
557
+
558
+
559
+
560
+ <h2>
561
+ Class Method Summary
562
+ <small><a href="#" class="summary_toggle">collapse</a></small>
563
+ </h2>
564
+
565
+ <ul class="summary">
566
+
567
+ <li class="public ">
568
+ <span class="summary_signature">
569
+
570
+ <a href="#check!-class_method" title="check! (class method)">.<strong>check!</strong>(code, operation, direction) &#x21d2; void </a>
571
+
572
+
573
+
574
+ </span>
575
+
576
+
577
+
578
+
579
+
580
+
581
+ <span class="private note title">private</span>
582
+
583
+
584
+ <span class="summary_desc"><div class='inline'><p>Raises unless the call succeeded.</p></div></span>
585
+
586
+ </li>
587
+
588
+
589
+ <li class="public ">
590
+ <span class="summary_signature">
591
+
592
+ <a href="#error_text-class_method" title="error_text (class method)">.<strong>error_text</strong>(code, direction) &#x21d2; String<sup>?</sup> </a>
593
+
594
+
595
+
596
+ </span>
597
+
598
+
599
+
600
+
601
+
602
+
603
+ <span class="private note title">private</span>
604
+
605
+
606
+ <span class="summary_desc"><div class='inline'><p>WinMM's own description of an error code.</p></div></span>
607
+
608
+ </li>
609
+
610
+
611
+ <li class="public ">
612
+ <span class="summary_signature">
613
+
614
+ <a href="#read_wide_string-class_method" title="read_wide_string (class method)">.<strong>read_wide_string</strong>(pointer, max_characters) &#x21d2; String </a>
615
+
616
+
617
+
618
+ </span>
619
+
620
+
621
+
622
+
623
+
624
+
625
+ <span class="private note title">private</span>
626
+
627
+
628
+ <span class="summary_desc"><div class='inline'><p>Reads a NUL-terminated UTF-16LE string out of native memory.</p></div></span>
629
+
630
+ </li>
631
+
632
+
633
+ </ul>
634
+
635
+
636
+
637
+
638
+
639
+
640
+ <div id="class_method_details" class="method_details_list">
641
+ <h2>Class Method Details</h2>
642
+
643
+
644
+ <div class="method_details first">
645
+ <h3 class="signature first" id="check!-class_method">
646
+
647
+ .<strong>check!</strong>(code, operation, direction) &#x21d2; <tt>void</tt>
648
+
649
+
650
+
651
+
652
+
653
+ </h3><div class="docstring">
654
+ <div class="discussion">
655
+ <p class="note private">
656
+ <strong>This method is part of a private API.</strong>
657
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
658
+ </p>
659
+ <p class="note returns_void">This method returns an undefined value.</p><p>Raises unless the call succeeded.</p>
660
+
661
+ </div>
662
+ </div>
663
+ <div class="tags">
664
+ <p class="tag_title">Parameters:</p>
665
+ <ul class="param">
666
+
667
+ <li>
668
+
669
+ <span class='name'>code</span>
670
+
671
+
672
+ <span class='type'>(<tt>Integer</tt>)</span>
673
+
674
+
675
+
676
+ &mdash;
677
+ <div class='inline'><p>the <code>MMRESULT</code> a WinMM call returned</p></div>
678
+
679
+ </li>
680
+
681
+ <li>
682
+
683
+ <span class='name'>operation</span>
684
+
685
+
686
+ <span class='type'>(<tt>Symbol</tt>)</span>
687
+
688
+
689
+
690
+ &mdash;
691
+ <div class='inline'><p>the function that returned it, for the message</p></div>
692
+
693
+ </li>
694
+
695
+ <li>
696
+
697
+ <span class='name'>direction</span>
698
+
699
+
700
+ <span class='type'>(<tt>Symbol</tt>)</span>
701
+
702
+
703
+
704
+ &mdash;
705
+ <div class='inline'><p><code>:input</code> or <code>:output</code>, to pick the error table</p></div>
706
+
707
+ </li>
708
+
709
+ </ul>
710
+
711
+ <p class="tag_title">Raises:</p>
712
+ <ul class="raise">
713
+
714
+ <li>
715
+
716
+
717
+ <span class='type'>(<tt><span class='object_link'><a href="Error.html" title="MIDICommunicationsWindows::Error (class)">Error</a></span></tt>)</span>
718
+
719
+
720
+
721
+ &mdash;
722
+ <div class='inline'><p>when <code>code</code> is anything but <code>MMSYSERR_NOERROR</code></p></div>
723
+
724
+ </li>
725
+
726
+ </ul>
727
+
728
+ </div><table class="source_code">
729
+ <tr>
730
+ <td>
731
+ <pre class="lines">
732
+
733
+
734
+ 291
735
+ 292
736
+ 293
737
+ 294
738
+ 295</pre>
739
+ </td>
740
+ <td>
741
+ <pre class="code"><span class="info file"># File 'lib/midi-communications-windows/api.rb', line 291</span>
742
+
743
+ <span class='kw'>def</span> <span class='id identifier rubyid_check!'>check!</span><span class='lparen'>(</span><span class='id identifier rubyid_code'>code</span><span class='comma'>,</span> <span class='id identifier rubyid_operation'>operation</span><span class='comma'>,</span> <span class='id identifier rubyid_direction'>direction</span><span class='rparen'>)</span>
744
+ <span class='kw'>return</span> <span class='kw'>if</span> <span class='id identifier rubyid_code'>code</span> <span class='op'>==</span> <span class='const'><span class='object_link'><a href="#MMSYSERR_NOERROR-constant" title="MIDICommunicationsWindows::API::MMSYSERR_NOERROR (constant)">MMSYSERR_NOERROR</a></span></span>
745
+
746
+ <span class='id identifier rubyid_raise'>raise</span> <span class='const'><span class='object_link'><a href="Error.html" title="MIDICommunicationsWindows::Error (class)">Error</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Error.html#initialize-instance_method" title="MIDICommunicationsWindows::Error#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_operation'>operation</span><span class='comma'>,</span> <span class='id identifier rubyid_code'>code</span><span class='comma'>,</span> <span class='id identifier rubyid_error_text'>error_text</span><span class='lparen'>(</span><span class='id identifier rubyid_code'>code</span><span class='comma'>,</span> <span class='id identifier rubyid_direction'>direction</span><span class='rparen'>)</span><span class='rparen'>)</span>
747
+ <span class='kw'>end</span></pre>
748
+ </td>
749
+ </tr>
750
+ </table>
751
+ </div>
752
+
753
+ <div class="method_details ">
754
+ <h3 class="signature " id="error_text-class_method">
755
+
756
+ .<strong>error_text</strong>(code, direction) &#x21d2; <tt>String</tt><sup>?</sup>
757
+
758
+
759
+
760
+
761
+
762
+ </h3><div class="docstring">
763
+ <div class="discussion">
764
+ <p class="note private">
765
+ <strong>This method is part of a private API.</strong>
766
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
767
+ </p>
768
+ <p>WinMM's own description of an error code.</p>
769
+ <p>The two error tables are not the same, which is why the direction has to
770
+ be known: the same numeric code can mean different things for input and
771
+ for output.</p>
772
+
773
+ </div>
774
+ </div>
775
+ <div class="tags">
776
+ <p class="tag_title">Parameters:</p>
777
+ <ul class="param">
778
+
779
+ <li>
780
+
781
+ <span class='name'>code</span>
782
+
783
+
784
+ <span class='type'>(<tt>Integer</tt>)</span>
785
+
786
+
787
+
788
+ &mdash;
789
+ <div class='inline'><p>an <code>MMRESULT</code></p></div>
790
+
791
+ </li>
792
+
793
+ <li>
794
+
795
+ <span class='name'>direction</span>
796
+
797
+
798
+ <span class='type'>(<tt>Symbol</tt>)</span>
799
+
800
+
801
+
802
+ &mdash;
803
+ <div class='inline'><p><code>:input</code> or <code>:output</code></p></div>
804
+
805
+ </li>
806
+
807
+ </ul>
808
+
809
+ <p class="tag_title">Returns:</p>
810
+ <ul class="return">
811
+
812
+ <li>
813
+
814
+
815
+ <span class='type'>(<tt>String</tt>, <tt>nil</tt>)</span>
816
+
817
+
818
+
819
+ &mdash;
820
+ <div class='inline'><p>the description, or nil if WinMM has none</p></div>
821
+
822
+ </li>
823
+
824
+ </ul>
825
+
826
+ </div><table class="source_code">
827
+ <tr>
828
+ <td>
829
+ <pre class="lines">
830
+
831
+
832
+ 306
833
+ 307
834
+ 308
835
+ 309
836
+ 310
837
+ 311
838
+ 312
839
+ 313
840
+ 314
841
+ 315</pre>
842
+ </td>
843
+ <td>
844
+ <pre class="code"><span class="info file"># File 'lib/midi-communications-windows/api.rb', line 306</span>
845
+
846
+ <span class='kw'>def</span> <span class='id identifier rubyid_error_text'>error_text</span><span class='lparen'>(</span><span class='id identifier rubyid_code'>code</span><span class='comma'>,</span> <span class='id identifier rubyid_direction'>direction</span><span class='rparen'>)</span>
847
+ <span class='id identifier rubyid_buffer'>buffer</span> <span class='op'>=</span> <span class='const'>FFI</span><span class='op'>::</span><span class='const'>MemoryPointer</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='symbol'>:uint16</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="#MAX_ERROR_TEXT_LENGTH-constant" title="MIDICommunicationsWindows::API::MAX_ERROR_TEXT_LENGTH (constant)">MAX_ERROR_TEXT_LENGTH</a></span></span><span class='rparen'>)</span>
848
+
849
+ <span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='kw'>case</span> <span class='id identifier rubyid_direction'>direction</span>
850
+ <span class='kw'>when</span> <span class='symbol'>:input</span> <span class='kw'>then</span> <span class='id identifier rubyid_midiInGetErrorTextW'>midiInGetErrorTextW</span><span class='lparen'>(</span><span class='id identifier rubyid_code'>code</span><span class='comma'>,</span> <span class='id identifier rubyid_buffer'>buffer</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="#MAX_ERROR_TEXT_LENGTH-constant" title="MIDICommunicationsWindows::API::MAX_ERROR_TEXT_LENGTH (constant)">MAX_ERROR_TEXT_LENGTH</a></span></span><span class='rparen'>)</span>
851
+ <span class='kw'>when</span> <span class='symbol'>:output</span> <span class='kw'>then</span> <span class='id identifier rubyid_midiOutGetErrorTextW'>midiOutGetErrorTextW</span><span class='lparen'>(</span><span class='id identifier rubyid_code'>code</span><span class='comma'>,</span> <span class='id identifier rubyid_buffer'>buffer</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="#MAX_ERROR_TEXT_LENGTH-constant" title="MIDICommunicationsWindows::API::MAX_ERROR_TEXT_LENGTH (constant)">MAX_ERROR_TEXT_LENGTH</a></span></span><span class='rparen'>)</span>
852
+ <span class='kw'>end</span>
853
+
854
+ <span class='id identifier rubyid_read_wide_string'>read_wide_string</span><span class='lparen'>(</span><span class='id identifier rubyid_buffer'>buffer</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="#MAX_ERROR_TEXT_LENGTH-constant" title="MIDICommunicationsWindows::API::MAX_ERROR_TEXT_LENGTH (constant)">MAX_ERROR_TEXT_LENGTH</a></span></span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='id identifier rubyid_result'>result</span> <span class='op'>==</span> <span class='const'><span class='object_link'><a href="#MMSYSERR_NOERROR-constant" title="MIDICommunicationsWindows::API::MMSYSERR_NOERROR (constant)">MMSYSERR_NOERROR</a></span></span>
855
+ <span class='kw'>end</span></pre>
856
+ </td>
857
+ </tr>
858
+ </table>
859
+ </div>
860
+
861
+ <div class="method_details ">
862
+ <h3 class="signature " id="read_wide_string-class_method">
863
+
864
+ .<strong>read_wide_string</strong>(pointer, max_characters) &#x21d2; <tt>String</tt>
865
+
866
+
867
+
868
+
869
+
870
+ </h3><div class="docstring">
871
+ <div class="discussion">
872
+ <p class="note private">
873
+ <strong>This method is part of a private API.</strong>
874
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
875
+ </p>
876
+ <p>Reads a NUL-terminated UTF-16LE string out of native memory.</p>
877
+ <p>Reading is done in code units rather than bytes on purpose: a byte-wise
878
+ search for a NUL pair would stop in the middle of a pair such as
879
+ <code>'A' 'Ā'</code> (<code>41 00 00 01</code>) and return a truncated name.</p>
880
+ <p>A name that does not decode is repaired rather than raised on: a port
881
+ whose name arrives mangled is still a port the caller may want to open,
882
+ and losing the whole enumeration over one bad character would be worse
883
+ than showing a replacement character.</p>
884
+
885
+ </div>
886
+ </div>
887
+ <div class="tags">
888
+ <p class="tag_title">Parameters:</p>
889
+ <ul class="param">
890
+
891
+ <li>
892
+
893
+ <span class='name'>pointer</span>
894
+
895
+
896
+ <span class='type'>(<tt>FFI::Pointer</tt>)</span>
897
+
898
+
899
+
900
+ &mdash;
901
+ <div class='inline'><p>memory holding the string</p></div>
902
+
903
+ </li>
904
+
905
+ <li>
906
+
907
+ <span class='name'>max_characters</span>
908
+
909
+
910
+ <span class='type'>(<tt>Integer</tt>)</span>
911
+
912
+
913
+
914
+ &mdash;
915
+ <div class='inline'><p>capacity of the field, in characters</p></div>
916
+
917
+ </li>
918
+
919
+ </ul>
920
+
921
+ <p class="tag_title">Returns:</p>
922
+ <ul class="return">
923
+
924
+ <li>
925
+
926
+
927
+ <span class='type'>(<tt>String</tt>)</span>
928
+
929
+
930
+
931
+ &mdash;
932
+ <div class='inline'><p>the decoded string, in UTF-8</p></div>
933
+
934
+ </li>
935
+
936
+ </ul>
937
+
938
+ </div><table class="source_code">
939
+ <tr>
940
+ <td>
941
+ <pre class="lines">
942
+
943
+
944
+ 331
945
+ 332
946
+ 333
947
+ 334
948
+ 335
949
+ 336
950
+ 337
951
+ 338</pre>
952
+ </td>
953
+ <td>
954
+ <pre class="code"><span class="info file"># File 'lib/midi-communications-windows/api.rb', line 331</span>
955
+
956
+ <span class='kw'>def</span> <span class='id identifier rubyid_read_wide_string'>read_wide_string</span><span class='lparen'>(</span><span class='id identifier rubyid_pointer'>pointer</span><span class='comma'>,</span> <span class='id identifier rubyid_max_characters'>max_characters</span><span class='rparen'>)</span>
957
+ <span class='id identifier rubyid_units'>units</span> <span class='op'>=</span> <span class='id identifier rubyid_pointer'>pointer</span><span class='period'>.</span><span class='id identifier rubyid_read_array_of_uint16'>read_array_of_uint16</span><span class='lparen'>(</span><span class='id identifier rubyid_max_characters'>max_characters</span><span class='rparen'>)</span>
958
+ <span class='id identifier rubyid_units'>units</span> <span class='op'>=</span> <span class='id identifier rubyid_units'>units</span><span class='period'>.</span><span class='id identifier rubyid_take_while'>take_while</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_unit'>unit</span><span class='op'>|</span> <span class='op'>!</span><span class='id identifier rubyid_unit'>unit</span><span class='period'>.</span><span class='id identifier rubyid_zero?'>zero?</span> <span class='rbrace'>}</span>
959
+
960
+ <span class='id identifier rubyid_units'>units</span><span class='period'>.</span><span class='id identifier rubyid_pack'>pack</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>S&lt;*</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
961
+ <span class='period'>.</span><span class='id identifier rubyid_force_encoding'>force_encoding</span><span class='lparen'>(</span><span class='const'>Encoding</span><span class='op'>::</span><span class='const'>UTF_16LE</span><span class='rparen'>)</span>
962
+ <span class='period'>.</span><span class='id identifier rubyid_encode'>encode</span><span class='lparen'>(</span><span class='const'>Encoding</span><span class='op'>::</span><span class='const'>UTF_8</span><span class='comma'>,</span> <span class='label'>invalid:</span> <span class='symbol'>:replace</span><span class='comma'>,</span> <span class='label'>undef:</span> <span class='symbol'>:replace</span><span class='rparen'>)</span>
963
+ <span class='kw'>end</span></pre>
964
+ </td>
965
+ </tr>
966
+ </table>
967
+ </div>
968
+
969
+ </div>
970
+
971
+ </div>
972
+
973
+ <div id="footer">
974
+ Generated on Sun Sep 6 21:20:52 2026 by
975
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
976
+ 0.9.45 (ruby-3.4.7).
977
+ </div>
978
+
979
+ </div>
980
+ </body>
981
+ </html>