00001 #ifndef PORT_MIDI_H 00002 #define PORT_MIDI_H 00003 #ifdef __cplusplus 00004 extern "C" { 00005 #endif /* __cplusplus */ 00006 00007 /* 00008 * PortMidi Portable Real-Time MIDI Library 00009 * PortMidi API Header File 00010 * Latest version available at: http://sourceforge.net/projects/portmedia 00011 * 00012 * Copyright (c) 1999-2000 Ross Bencina and Phil Burk 00013 * Copyright (c) 2001-2006 Roger B. Dannenberg 00014 * 00015 * Permission is hereby granted, free of charge, to any person obtaining 00016 * a copy of this software and associated documentation files 00017 * (the "Software"), to deal in the Software without restriction, 00018 * including without limitation the rights to use, copy, modify, merge, 00019 * publish, distribute, sublicense, and/or sell copies of the Software, 00020 * and to permit persons to whom the Software is furnished to do so, 00021 * subject to the following conditions: 00022 * 00023 * The above copyright notice and this permission notice shall be 00024 * included in all copies or substantial portions of the Software. 00025 * 00026 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 00027 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 00028 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 00029 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 00030 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 00031 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 00032 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 00033 */ 00034 00035 /* 00036 * The text above constitutes the entire PortMidi license; however, 00037 * the PortMusic community also makes the following non-binding requests: 00038 * 00039 * Any person wishing to distribute modifications to the Software is 00040 * requested to send the modifications to the original developer so that 00041 * they can be incorporated into the canonical version. It is also 00042 * requested that these non-binding requests be included along with the 00043 * license above. 00044 */ 00045 00046 /* CHANGELOG FOR PORTMIDI 00047 * (see ../CHANGELOG.txt) 00048 * 00049 * NOTES ON HOST ERROR REPORTING: 00050 * 00051 * PortMidi errors (of type PmError) are generic, system-independent errors. 00052 * When an error does not map to one of the more specific PmErrors, the 00053 * catch-all code pmHostError is returned. This means that PortMidi has 00054 * retained a more specific system-dependent error code. The caller can 00055 * get more information by calling Pm_HasHostError() to test if there is 00056 * a pending host error, and Pm_GetHostErrorText() to get a text string 00057 * describing the error. Host errors are reported on a per-device basis 00058 * because only after you open a device does PortMidi have a place to 00059 * record the host error code. I.e. only 00060 * those routines that receive a (PortMidiStream *) argument check and 00061 * report errors. One exception to this is that Pm_OpenInput() and 00062 * Pm_OpenOutput() can report errors even though when an error occurs, 00063 * there is no PortMidiStream* to hold the error. Fortunately, both 00064 * of these functions return any error immediately, so we do not really 00065 * need per-device error memory. Instead, any host error code is stored 00066 * in a global, pmHostError is returned, and the user can call 00067 * Pm_GetHostErrorText() to get the error message (and the invalid stream 00068 * parameter will be ignored.) The functions 00069 * pm_init and pm_term do not fail or raise 00070 * errors. The job of pm_init is to locate all available devices so that 00071 * the caller can get information via PmDeviceInfo(). If an error occurs, 00072 * the device is simply not listed as available. 00073 * 00074 * Host errors come in two flavors: 00075 * a) host error 00076 * b) host error during callback 00077 * These can occur w/midi input or output devices. (b) can only happen 00078 * asynchronously (during callback routines), whereas (a) only occurs while 00079 * synchronously running PortMidi and any resulting system dependent calls. 00080 * Both (a) and (b) are reported by the next read or write call. You can 00081 * also query for asynchronous errors (b) at any time by calling 00082 * Pm_HasHostError(). 00083 * 00084 * NOTES ON COMPILE-TIME SWITCHES 00085 * 00086 * DEBUG assumes stdio and a console. Use this if you want automatic, simple 00087 * error reporting, e.g. for prototyping. If you are using MFC or some 00088 * other graphical interface with no console, DEBUG probably should be 00089 * undefined. 00090 * PM_CHECK_ERRORS more-or-less takes over error checking for return values, 00091 * stopping your program and printing error messages when an error 00092 * occurs. This also uses stdio for console text I/O. 00093 */ 00094 00095 #ifndef WIN32 00096 // Linux and OS X have stdint.h 00097 #include <stdint.h> 00098 #else 00099 #ifndef INT32_DEFINED 00100 // rather than having users install a special .h file for windows, 00101 // just put the required definitions inline here. porttime.h uses 00102 // these too, so the definitions are (unfortunately) duplicated there 00103 typedef int int32_t; 00104 typedef unsigned int uint32_t; 00105 #define INT32_DEFINED 00106 #endif 00107 #endif 00108 00109 #ifndef FALSE 00110 #define FALSE 0 00111 #endif 00112 #ifndef TRUE 00113 #define TRUE 1 00114 #endif 00115 00116 /* default size of buffers for sysex transmission: */ 00117 #define PM_DEFAULT_SYSEX_BUFFER_SIZE 1024 00118 00120 typedef enum { 00121 pmNoError = 0, 00122 pmNoData = 0, 00123 pmGotData = 1, 00124 pmHostError = -10000, 00125 pmInvalidDeviceId, 00130 pmInsufficientMemory, 00131 pmBufferTooSmall, 00132 pmBufferOverflow, 00133 pmBadPtr, /* PortMidiStream parameter is NULL or 00134 * stream is not opened or 00135 * stream is output when input is required or 00136 * stream is input when output is required */ 00137 pmBadData, 00138 pmInternalError, 00139 pmBufferMaxSize 00140 /* NOTE: If you add a new error type, be sure to update Pm_GetErrorText() */ 00141 } PmError; 00142 00147 PmError Pm_Initialize( void ); 00148 00153 PmError Pm_Terminate( void ); 00154 00157 typedef void PortMidiStream; 00158 #define PmStream PortMidiStream 00159 00174 int Pm_HasHostError( PortMidiStream * stream ); 00175 00176 00181 const char *Pm_GetErrorText( PmError errnum ); 00182 00187 void Pm_GetHostErrorText(char * msg, unsigned int len); 00188 00189 #define HDRLENGTH 50 00190 #define PM_HOST_ERROR_MSG_LEN 256u /* any host error msg will occupy less 00191 than this number of characters */ 00192 00199 typedef int PmDeviceID; 00200 #define pmNoDevice -1 00201 typedef struct { 00202 int structVersion; 00203 const char *interf; 00204 const char *name; 00205 int input; 00206 int output; 00207 int opened; 00209 } PmDeviceInfo; 00210 00212 int Pm_CountDevices( void ); 00255 PmDeviceID Pm_GetDefaultInputDeviceID( void ); 00257 PmDeviceID Pm_GetDefaultOutputDeviceID( void ); 00258 00263 typedef int32_t PmTimestamp; 00264 typedef PmTimestamp (*PmTimeProcPtr)(void *time_info); 00265 00267 #define PmBefore(t1,t2) ((t1-t2) < 0) 00268 00281 const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id ); 00282 00347 PmError Pm_OpenInput( PortMidiStream** stream, 00348 PmDeviceID inputDevice, 00349 void *inputDriverInfo, 00350 int32_t bufferSize, 00351 PmTimeProcPtr time_proc, 00352 void *time_info ); 00353 00354 PmError Pm_OpenOutput( PortMidiStream** stream, 00355 PmDeviceID outputDevice, 00356 void *outputDriverInfo, 00357 int32_t bufferSize, 00358 PmTimeProcPtr time_proc, 00359 void *time_info, 00360 int32_t latency ); 00368 /* \function PmError Pm_SetFilter( PortMidiStream* stream, int32_t filters ) 00369 Pm_SetFilter() sets filters on an open input stream to drop selected 00370 input types. By default, only active sensing messages are filtered. 00371 To prohibit, say, active sensing and sysex messages, call 00372 Pm_SetFilter(stream, PM_FILT_ACTIVE | PM_FILT_SYSEX); 00373 00374 Filtering is useful when midi routing or midi thru functionality is being 00375 provided by the user application. 00376 For example, you may want to exclude timing messages (clock, MTC, start/stop/continue), 00377 while allowing note-related messages to pass. 00378 Or you may be using a sequencer or drum-machine for MIDI clock information but want to 00379 exclude any notes it may play. 00380 */ 00381 00382 /* Filter bit-mask definitions */ 00384 #define PM_FILT_ACTIVE (1 << 0x0E) 00385 00386 #define PM_FILT_SYSEX (1 << 0x00) 00387 00388 #define PM_FILT_CLOCK (1 << 0x08) 00389 00390 #define PM_FILT_PLAY ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B)) 00391 00392 #define PM_FILT_TICK (1 << 0x09) 00393 00394 #define PM_FILT_FD (1 << 0x0D) 00395 00396 #define PM_FILT_UNDEFINED PM_FILT_FD 00397 00398 #define PM_FILT_RESET (1 << 0x0F) 00399 00400 #define PM_FILT_REALTIME (PM_FILT_ACTIVE | PM_FILT_SYSEX | PM_FILT_CLOCK | \ 00401 PM_FILT_PLAY | PM_FILT_UNDEFINED | PM_FILT_RESET | PM_FILT_TICK) 00402 00403 #define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18)) 00404 00405 #define PM_FILT_CHANNEL_AFTERTOUCH (1 << 0x1D) 00406 00407 #define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A) 00408 00409 #define PM_FILT_AFTERTOUCH (PM_FILT_CHANNEL_AFTERTOUCH | PM_FILT_POLY_AFTERTOUCH) 00410 00411 #define PM_FILT_PROGRAM (1 << 0x1C) 00412 00413 #define PM_FILT_CONTROL (1 << 0x1B) 00414 00415 #define PM_FILT_PITCHBEND (1 << 0x1E) 00416 00417 #define PM_FILT_MTC (1 << 0x01) 00418 00419 #define PM_FILT_SONG_POSITION (1 << 0x02) 00420 00421 #define PM_FILT_SONG_SELECT (1 << 0x03) 00422 00423 #define PM_FILT_TUNE (1 << 0x06) 00424 00425 #define PM_FILT_SYSTEMCOMMON (PM_FILT_MTC | PM_FILT_SONG_POSITION | PM_FILT_SONG_SELECT | PM_FILT_TUNE) 00426 00427 00428 PmError Pm_SetFilter( PortMidiStream* stream, int32_t filters ); 00429 00430 #define Pm_Channel(channel) (1<<(channel)) 00431 00442 PmError Pm_SetChannelMask(PortMidiStream *stream, int mask); 00443 00452 PmError Pm_Abort( PortMidiStream* stream ); 00453 00459 PmError Pm_Close( PortMidiStream* stream ); 00460 00468 #define Pm_Message(status, data1, data2) \ 00469 ((((data2) << 16) & 0xFF0000) | \ 00470 (((data1) << 8) & 0xFF00) | \ 00471 ((status) & 0xFF)) 00472 #define Pm_MessageStatus(msg) ((msg) & 0xFF) 00473 #define Pm_MessageData1(msg) (((msg) >> 8) & 0xFF) 00474 #define Pm_MessageData2(msg) (((msg) >> 16) & 0xFF) 00475 00476 typedef int32_t PmMessage; 00542 typedef struct { 00543 PmMessage message; 00544 PmTimestamp timestamp; 00545 } PmEvent; 00546 00577 int Pm_Read( PortMidiStream *stream, PmEvent *buffer, int32_t length ); 00578 00583 PmError Pm_Poll( PortMidiStream *stream); 00584 00598 PmError Pm_Write( PortMidiStream *stream, PmEvent *buffer, int32_t length ); 00599 00606 PmError Pm_WriteShort( PortMidiStream *stream, PmTimestamp when, int32_t msg); 00607 00611 PmError Pm_WriteSysEx( PortMidiStream *stream, PmTimestamp when, unsigned char *msg); 00612 00615 #ifdef __cplusplus 00616 } 00617 #endif /* __cplusplus */ 00618 #endif /* PORT_MIDI_H */