PortMidi  2.2.x
portmidi.h
1 #ifndef PORT_MIDI_H
2 #define PORT_MIDI_H
3 #ifdef __cplusplus
4 extern "C" {
5 #endif /* __cplusplus */
6 
7 /*
8  * PortMidi Portable Real-Time MIDI Library
9  * PortMidi API Header File
10  * Latest version available at: http://sourceforge.net/projects/portmedia
11  *
12  * Copyright (c) 1999-2000 Ross Bencina and Phil Burk
13  * Copyright (c) 2001-2006 Roger B. Dannenberg
14  *
15  * Permission is hereby granted, free of charge, to any person obtaining
16  * a copy of this software and associated documentation files
17  * (the "Software"), to deal in the Software without restriction,
18  * including without limitation the rights to use, copy, modify, merge,
19  * publish, distribute, sublicense, and/or sell copies of the Software,
20  * and to permit persons to whom the Software is furnished to do so,
21  * subject to the following conditions:
22  *
23  * The above copyright notice and this permission notice shall be
24  * included in all copies or substantial portions of the Software.
25  *
26  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
27  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
28  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
29  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
30  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
31  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
32  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
33  */
34 
35 /*
36  * The text above constitutes the entire PortMidi license; however,
37  * the PortMusic community also makes the following non-binding requests:
38  *
39  * Any person wishing to distribute modifications to the Software is
40  * requested to send the modifications to the original developer so that
41  * they can be incorporated into the canonical version. It is also
42  * requested that these non-binding requests be included along with the
43  * license above.
44  */
45 
46 /* CHANGELOG FOR PORTMIDI
47  * (see ../CHANGELOG.txt)
48  *
49  * NOTES ON HOST ERROR REPORTING:
50  *
51  * PortMidi errors (of type PmError) are generic, system-independent errors.
52  * When an error does not map to one of the more specific PmErrors, the
53  * catch-all code pmHostError is returned. This means that PortMidi has
54  * retained a more specific system-dependent error code. The caller can
55  * get more information by calling Pm_HasHostError() to test if there is
56  * a pending host error, and Pm_GetHostErrorText() to get a text string
57  * describing the error. Host errors are reported on a per-device basis
58  * because only after you open a device does PortMidi have a place to
59  * record the host error code. I.e. only
60  * those routines that receive a (PortMidiStream *) argument check and
61  * report errors. One exception to this is that Pm_OpenInput() and
62  * Pm_OpenOutput() can report errors even though when an error occurs,
63  * there is no PortMidiStream* to hold the error. Fortunately, both
64  * of these functions return any error immediately, so we do not really
65  * need per-device error memory. Instead, any host error code is stored
66  * in a global, pmHostError is returned, and the user can call
67  * Pm_GetHostErrorText() to get the error message (and the invalid stream
68  * parameter will be ignored.) The functions
69  * pm_init and pm_term do not fail or raise
70  * errors. The job of pm_init is to locate all available devices so that
71  * the caller can get information via PmDeviceInfo(). If an error occurs,
72  * the device is simply not listed as available.
73  *
74  * Host errors come in two flavors:
75  * a) host error
76  * b) host error during callback
77  * These can occur w/midi input or output devices. (b) can only happen
78  * asynchronously (during callback routines), whereas (a) only occurs while
79  * synchronously running PortMidi and any resulting system dependent calls.
80  * Both (a) and (b) are reported by the next read or write call. You can
81  * also query for asynchronous errors (b) at any time by calling
82  * Pm_HasHostError().
83  *
84  * NOTES ON COMPILE-TIME SWITCHES
85  *
86  * DEBUG assumes stdio and a console. Use this if you want automatic, simple
87  * error reporting, e.g. for prototyping. If you are using MFC or some
88  * other graphical interface with no console, DEBUG probably should be
89  * undefined.
90  * PM_CHECK_ERRORS more-or-less takes over error checking for return values,
91  * stopping your program and printing error messages when an error
92  * occurs. This also uses stdio for console text I/O.
93  */
94 
95 #ifndef WIN32
96 // Linux and OS X have stdint.h
97 #include <stdint.h>
98 #else
99 #ifndef INT32_DEFINED
100 // rather than having users install a special .h file for windows,
101 // just put the required definitions inline here. porttime.h uses
102 // these too, so the definitions are (unfortunately) duplicated there
103 typedef int int32_t;
104 typedef unsigned int uint32_t;
105 #define INT32_DEFINED
106 #endif
107 #endif
108 
109 #ifdef _WINDLL
110 #define PMEXPORT __declspec(dllexport)
111 #else
112 #define PMEXPORT
113 #endif
114 
115 #ifndef FALSE
116  #define FALSE 0
117 #endif
118 #ifndef TRUE
119  #define TRUE 1
120 #endif
121 
122 /* default size of buffers for sysex transmission: */
123 #define PM_DEFAULT_SYSEX_BUFFER_SIZE 1024
124 
126 typedef enum {
127  pmNoError = 0,
128  pmNoData = 0,
129  pmGotData = 1,
130  pmHostError = -10000,
131  pmInvalidDeviceId,
136  pmInsufficientMemory,
137  pmBufferTooSmall,
138  pmBufferOverflow,
139  pmBadPtr, /* PortMidiStream parameter is NULL or
140  * stream is not opened or
141  * stream is output when input is required or
142  * stream is input when output is required */
143  pmBadData,
144  pmInternalError,
145  pmBufferMaxSize
146  /* NOTE: If you add a new error type, be sure to update Pm_GetErrorText() */
147 } PmError;
148 
153 PMEXPORT PmError Pm_Initialize( void );
154 
159 PMEXPORT PmError Pm_Terminate( void );
160 
163 typedef void PortMidiStream;
164 #define PmStream PortMidiStream
165 
180 PMEXPORT int Pm_HasHostError( PortMidiStream * stream );
181 
182 
187 PMEXPORT const char *Pm_GetErrorText( PmError errnum );
188 
193 PMEXPORT void Pm_GetHostErrorText(char * msg, unsigned int len);
194 
195 #define HDRLENGTH 50
196 #define PM_HOST_ERROR_MSG_LEN 256u /* any host error msg will occupy less
197  than this number of characters */
198 
205 typedef int PmDeviceID;
206 #define pmNoDevice -1
207 typedef struct {
209  const char *interf;
210  const char *name;
211  int input;
212  int output;
213  int opened;
215 } PmDeviceInfo;
216 
218 PMEXPORT int Pm_CountDevices( void );
261 PMEXPORT PmDeviceID Pm_GetDefaultInputDeviceID( void );
263 PMEXPORT PmDeviceID Pm_GetDefaultOutputDeviceID( void );
264 
269 typedef int32_t PmTimestamp;
270 typedef PmTimestamp (*PmTimeProcPtr)(void *time_info);
271 
273 #define PmBefore(t1,t2) ((t1-t2) < 0)
274 
287 PMEXPORT const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id );
288 
353 PMEXPORT PmError Pm_OpenInput( PortMidiStream** stream,
354  PmDeviceID inputDevice,
355  void *inputDriverInfo,
356  int32_t bufferSize,
357  PmTimeProcPtr time_proc,
358  void *time_info );
359 
360 PMEXPORT PmError Pm_OpenOutput( PortMidiStream** stream,
361  PmDeviceID outputDevice,
362  void *outputDriverInfo,
363  int32_t bufferSize,
364  PmTimeProcPtr time_proc,
365  void *time_info,
366  int32_t latency );
374 /* \function PmError Pm_SetFilter( PortMidiStream* stream, int32_t filters )
375  Pm_SetFilter() sets filters on an open input stream to drop selected
376  input types. By default, only active sensing messages are filtered.
377  To prohibit, say, active sensing and sysex messages, call
378  Pm_SetFilter(stream, PM_FILT_ACTIVE | PM_FILT_SYSEX);
379 
380  Filtering is useful when midi routing or midi thru functionality is being
381  provided by the user application.
382  For example, you may want to exclude timing messages (clock, MTC, start/stop/continue),
383  while allowing note-related messages to pass.
384  Or you may be using a sequencer or drum-machine for MIDI clock information but want to
385  exclude any notes it may play.
386  */
387 
388 /* Filter bit-mask definitions */
390 #define PM_FILT_ACTIVE (1 << 0x0E)
391 
392 #define PM_FILT_SYSEX (1 << 0x00)
393 
394 #define PM_FILT_CLOCK (1 << 0x08)
395 
396 #define PM_FILT_PLAY ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B))
397 
398 #define PM_FILT_TICK (1 << 0x09)
399 
400 #define PM_FILT_FD (1 << 0x0D)
401 
402 #define PM_FILT_UNDEFINED PM_FILT_FD
403 
404 #define PM_FILT_RESET (1 << 0x0F)
405 
406 #define PM_FILT_REALTIME (PM_FILT_ACTIVE | PM_FILT_SYSEX | PM_FILT_CLOCK | \
407  PM_FILT_PLAY | PM_FILT_UNDEFINED | PM_FILT_RESET | PM_FILT_TICK)
408 
409 #define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18))
410 
411 #define PM_FILT_CHANNEL_AFTERTOUCH (1 << 0x1D)
412 
413 #define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A)
414 
415 #define PM_FILT_AFTERTOUCH (PM_FILT_CHANNEL_AFTERTOUCH | PM_FILT_POLY_AFTERTOUCH)
416 
417 #define PM_FILT_PROGRAM (1 << 0x1C)
418 
419 #define PM_FILT_CONTROL (1 << 0x1B)
420 
421 #define PM_FILT_PITCHBEND (1 << 0x1E)
422 
423 #define PM_FILT_MTC (1 << 0x01)
424 
425 #define PM_FILT_SONG_POSITION (1 << 0x02)
426 
427 #define PM_FILT_SONG_SELECT (1 << 0x03)
428 
429 #define PM_FILT_TUNE (1 << 0x06)
430 
431 #define PM_FILT_SYSTEMCOMMON (PM_FILT_MTC | PM_FILT_SONG_POSITION | PM_FILT_SONG_SELECT | PM_FILT_TUNE)
432 
433 
434 PMEXPORT PmError Pm_SetFilter( PortMidiStream* stream, int32_t filters );
435 
436 #define Pm_Channel(channel) (1<<(channel))
437 
452 PMEXPORT PmError Pm_SetChannelMask(PortMidiStream *stream, int mask);
453 
462 PMEXPORT PmError Pm_Abort( PortMidiStream* stream );
463 
469 PMEXPORT PmError Pm_Close( PortMidiStream* stream );
470 
494 PmError Pm_Synchronize( PortMidiStream* stream );
495 
496 
504 #define Pm_Message(status, data1, data2) \
505  ((((data2) << 16) & 0xFF0000) | \
506  (((data1) << 8) & 0xFF00) | \
507  ((status) & 0xFF))
508 #define Pm_MessageStatus(msg) ((msg) & 0xFF)
509 #define Pm_MessageData1(msg) (((msg) >> 8) & 0xFF)
510 #define Pm_MessageData2(msg) (((msg) >> 16) & 0xFF)
511 
512 typedef int32_t PmMessage;
578 typedef struct {
579  PmMessage message;
580  PmTimestamp timestamp;
581 } PmEvent;
582 
613 PMEXPORT int Pm_Read( PortMidiStream *stream, PmEvent *buffer, int32_t length );
614 
619 PMEXPORT PmError Pm_Poll( PortMidiStream *stream);
620 
634 PMEXPORT PmError Pm_Write( PortMidiStream *stream, PmEvent *buffer, int32_t length );
635 
642 PMEXPORT PmError Pm_WriteShort( PortMidiStream *stream, PmTimestamp when, int32_t msg);
643 
647 PMEXPORT PmError Pm_WriteSysEx( PortMidiStream *stream, PmTimestamp when, unsigned char *msg);
648 
651 #ifdef __cplusplus
652 }
653 #endif /* __cplusplus */
654 #endif /* PORT_MIDI_H */
PMEXPORT PmError Pm_Write(PortMidiStream *stream, PmEvent *buffer, int32_t length)
Pm_Write() writes midi data from a buffer.
Definition: portmidi.c:448
PMEXPORT PmError Pm_SetChannelMask(PortMidiStream *stream, int mask)
Pm_SetChannelMask() filters incoming messages based on channel.
Definition: portmidi.c:831
PMEXPORT PmError Pm_OpenInput(PortMidiStream **stream, PmDeviceID inputDevice, void *inputDriverInfo, int32_t bufferSize, PmTimeProcPtr time_proc, void *time_info)
Pm_OpenInput() and Pm_OpenOutput() open devices.
Definition: portmidi.c:669
int32_t PmMessage
see PmEvent
Definition: portmidi.h:512
const char * interf
underlying MIDI API, e.g.
Definition: portmidi.h:209
int opened
used by generic PortMidi code to do error checking on arguments
Definition: portmidi.h:213
PMEXPORT int Pm_Read(PortMidiStream *stream, PmEvent *buffer, int32_t length)
Pm_Read() retrieves midi data into a buffer, and returns the number of events read.
Definition: portmidi.c:357
PMEXPORT PmError Pm_WriteSysEx(PortMidiStream *stream, PmTimestamp when, unsigned char *msg)
Pm_WriteSysEx() writes a timestamped system-exclusive midi message.
Definition: portmidi.c:591
int input
true iff input is available
Definition: portmidi.h:211
PMEXPORT PmError Pm_WriteShort(PortMidiStream *stream, PmTimestamp when, int32_t msg)
Pm_WriteShort() writes a timestamped non-system-exclusive midi message.
Definition: portmidi.c:581
PMEXPORT PmError Pm_Close(PortMidiStream *stream)
Pm_Close() closes a midi stream, flushing any pending buffers.
Definition: portmidi.c:860
int structVersion
this internal structure version
Definition: portmidi.h:208
const char * name
device name, e.g.
Definition: portmidi.h:210
All midi data comes in the form of PmEvent structures.
Definition: portmidi.h:578
PMEXPORT const PmDeviceInfo * Pm_GetDeviceInfo(PmDeviceID id)
Pm_GetDeviceInfo() returns a pointer to a PmDeviceInfo structure referring to the device specified by...
Definition: portmidi.c:183
PmError Pm_Synchronize(PortMidiStream *stream)
Pm_Synchronize() instructs PortMidi to (re)synchronize to the time_proc passed when the stream was op...
Definition: portmidi.c:892
int output
true iff output is available
Definition: portmidi.h:212
PMEXPORT PmError Pm_Abort(PortMidiStream *stream)
Pm_Abort() terminates outgoing messages immediately The caller should immediately close the output po...
Definition: portmidi.c:906
PMEXPORT PmError Pm_Poll(PortMidiStream *stream)
Pm_Poll() tests whether input is available, returning TRUE, FALSE, or an error value.
Definition: portmidi.c:398

Generated for PortMidi by doxygen 1.8.13