PortMidi 2.2.x
portmidi.h
1#ifndef PORT_MIDI_H
2#define PORT_MIDI_H
3#ifdef __cplusplus
4extern "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
103typedef int int32_t;
104typedef 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
126typedef 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
153PMEXPORT PmError Pm_Initialize( void );
154
159PMEXPORT PmError Pm_Terminate( void );
160
163typedef void PortMidiStream;
164#define PmStream PortMidiStream
165
180PMEXPORT int Pm_HasHostError( PortMidiStream * stream );
181
182
187PMEXPORT const char *Pm_GetErrorText( PmError errnum );
188
193PMEXPORT 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
205typedef int PmDeviceID;
206#define pmNoDevice -1
207typedef struct {
209 const char *interf;
210 const char *name;
211 int input;
212 int output;
213 int opened;
214
216
218PMEXPORT int Pm_CountDevices( void );
261PMEXPORT PmDeviceID Pm_GetDefaultInputDeviceID( void );
263PMEXPORT PmDeviceID Pm_GetDefaultOutputDeviceID( void );
264
269typedef int32_t PmTimestamp;
270typedef PmTimestamp (*PmTimeProcPtr)(void *time_info);
271
273#define PmBefore(t1,t2) ((t1-t2) < 0)
287PMEXPORT const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id );
288
353PMEXPORT PmError Pm_OpenInput( PortMidiStream** stream,
354 PmDeviceID inputDevice,
355 void *inputDriverInfo,
356 int32_t bufferSize,
357 PmTimeProcPtr time_proc,
358 void *time_info );
359
360PMEXPORT 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 );
368
373
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)
392#define PM_FILT_SYSEX (1 << 0x00)
394#define PM_FILT_CLOCK (1 << 0x08)
396#define PM_FILT_PLAY ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B))
398#define PM_FILT_TICK (1 << 0x09)
400#define PM_FILT_FD (1 << 0x0D)
402#define PM_FILT_UNDEFINED PM_FILT_FD
404#define PM_FILT_RESET (1 << 0x0F)
405/** filter all real-time messages */
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)
409#define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18))
411#define PM_FILT_CHANNEL_AFTERTOUCH (1 << 0x1D)
413#define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A)
415#define PM_FILT_AFTERTOUCH (PM_FILT_CHANNEL_AFTERTOUCH | PM_FILT_POLY_AFTERTOUCH)
417#define PM_FILT_PROGRAM (1 << 0x1C)
419#define PM_FILT_CONTROL (1 << 0x1B)
421#define PM_FILT_PITCHBEND (1 << 0x1E)
423#define PM_FILT_MTC (1 << 0x01)
425#define PM_FILT_SONG_POSITION (1 << 0x02)
427#define PM_FILT_SONG_SELECT (1 << 0x03)
429#define PM_FILT_TUNE (1 << 0x06)
431#define PM_FILT_SYSTEMCOMMON (PM_FILT_MTC | PM_FILT_SONG_POSITION | PM_FILT_SONG_SELECT | PM_FILT_TUNE)
432
433
434PMEXPORT PmError Pm_SetFilter( PortMidiStream* stream, int32_t filters );
435
436#define Pm_Channel(channel) (1<<(channel))
452PMEXPORT PmError Pm_SetChannelMask(PortMidiStream *stream, int mask);
453
462PMEXPORT PmError Pm_Abort( PortMidiStream* stream );
463
469PMEXPORT PmError Pm_Close( PortMidiStream* stream );
470
494PmError 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)
512typedef int32_t PmMessage;
577 */
578typedef struct {
579 PmMessage message;
580 PmTimestamp timestamp;
581} PmEvent;
582
613PMEXPORT int Pm_Read( PortMidiStream *stream, PmEvent *buffer, int32_t length );
614
619PMEXPORT PmError Pm_Poll( PortMidiStream *stream);
620
634PMEXPORT PmError Pm_Write( PortMidiStream *stream, PmEvent *buffer, int32_t length );
635
642PMEXPORT PmError Pm_WriteShort( PortMidiStream *stream, PmTimestamp when, int32_t msg);
643
647PMEXPORT PmError Pm_WriteSysEx( PortMidiStream *stream, PmTimestamp when, unsigned char *msg);
648
650
651#ifdef __cplusplus
652}
653#endif /* __cplusplus */
654#endif /* PORT_MIDI_H */
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
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
PMEXPORT PmError Pm_Close(PortMidiStream *stream)
Pm_Close() closes a midi stream, flushing any pending buffers.
Definition portmidi.c:860
PMEXPORT PmError Pm_SetChannelMask(PortMidiStream *stream, int mask)
Pm_SetChannelMask() filters incoming messages based on channel.
Definition portmidi.c:831
PMEXPORT PmError Pm_Abort(PortMidiStream *stream)
Pm_Abort() terminates outgoing messages immediately The caller should immediately close the output po...
Definition portmidi.c:906
int32_t PmMessage
see PmEvent
Definition portmidi.h:511
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
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_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_WriteSysEx(PortMidiStream *stream, PmTimestamp when, unsigned char *msg)
Pm_WriteSysEx() writes a timestamped system-exclusive midi message.
Definition portmidi.c:591
PMEXPORT PmError Pm_Poll(PortMidiStream *stream)
Pm_Poll() tests whether input is available, returning TRUE, FALSE, or an error value.
Definition portmidi.c:398
PMEXPORT PmError Pm_Write(PortMidiStream *stream, PmEvent *buffer, int32_t length)
Pm_Write() writes midi data from a buffer.
Definition portmidi.c:448
int output
true iff output is available
Definition portmidi.h:211
const char * name
device name, e.g.
Definition portmidi.h:209
const char * interf
underlying MIDI API, e.g.
Definition portmidi.h:208
int input
true iff input is available
Definition portmidi.h:210
int structVersion
this internal structure version
Definition portmidi.h:207
int opened
used by generic PortMidi code to do error checking on arguments
Definition portmidi.h:212
All midi data comes in the form of PmEvent structures.
Definition portmidi.h:577

Generated for PortMidi by doxygen 1.14.0