PortMidi
2.2.x
|
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 #ifdef _WINDLL 00110 #define PMEXPORT __declspec(dllexport) 00111 #else 00112 #define PMEXPORT 00113 #endif 00114 00115 #ifndef FALSE 00116 #define FALSE 0 00117 #endif 00118 #ifndef TRUE 00119 #define TRUE 1 00120 #endif 00121 00122 /* default size of buffers for sysex transmission: */ 00123 #define PM_DEFAULT_SYSEX_BUFFER_SIZE 1024 00124 00126 typedef enum { 00127 pmNoError = 0, 00128 pmNoData = 0, 00129 pmGotData = 1, 00130 pmHostError = -10000, 00131 pmInvalidDeviceId, 00136 pmInsufficientMemory, 00137 pmBufferTooSmall, 00138 pmBufferOverflow, 00139 pmBadPtr, /* PortMidiStream parameter is NULL or 00140 * stream is not opened or 00141 * stream is output when input is required or 00142 * stream is input when output is required */ 00143 pmBadData, 00144 pmInternalError, 00145 pmBufferMaxSize 00146 /* NOTE: If you add a new error type, be sure to update Pm_GetErrorText() */ 00147 } PmError; 00148 00153 PMEXPORT PmError Pm_Initialize( void ); 00154 00159 PMEXPORT PmError Pm_Terminate( void ); 00160 00163 typedef void PortMidiStream; 00164 #define PmStream PortMidiStream 00165 00180 PMEXPORT int Pm_HasHostError( PortMidiStream * stream ); 00181 00182 00187 PMEXPORT const char *Pm_GetErrorText( PmError errnum ); 00188 00193 PMEXPORT void Pm_GetHostErrorText(char * msg, unsigned int len); 00194 00195 #define HDRLENGTH 50 00196 #define PM_HOST_ERROR_MSG_LEN 256u /* any host error msg will occupy less 00197 than this number of characters */ 00198 00205 typedef int PmDeviceID; 00206 #define pmNoDevice -1 00207 typedef struct { 00208 int structVersion; 00209 const char *interf; 00210 const char *name; 00211 int input; 00212 int output; 00213 int opened; 00215 } PmDeviceInfo; 00216 00218 PMEXPORT int Pm_CountDevices( void ); 00261 PMEXPORT PmDeviceID Pm_GetDefaultInputDeviceID( void ); 00263 PMEXPORT PmDeviceID Pm_GetDefaultOutputDeviceID( void ); 00264 00269 typedef int32_t PmTimestamp; 00270 typedef PmTimestamp (*PmTimeProcPtr)(void *time_info); 00271 00273 #define PmBefore(t1,t2) ((t1-t2) < 0) 00274 00287 PMEXPORT const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id ); 00288 00353 PMEXPORT PmError Pm_OpenInput( PortMidiStream** stream, 00354 PmDeviceID inputDevice, 00355 void *inputDriverInfo, 00356 int32_t bufferSize, 00357 PmTimeProcPtr time_proc, 00358 void *time_info ); 00359 00360 PMEXPORT PmError Pm_OpenOutput( PortMidiStream** stream, 00361 PmDeviceID outputDevice, 00362 void *outputDriverInfo, 00363 int32_t bufferSize, 00364 PmTimeProcPtr time_proc, 00365 void *time_info, 00366 int32_t latency ); 00374 /* \function PmError Pm_SetFilter( PortMidiStream* stream, int32_t filters ) 00375 Pm_SetFilter() sets filters on an open input stream to drop selected 00376 input types. By default, only active sensing messages are filtered. 00377 To prohibit, say, active sensing and sysex messages, call 00378 Pm_SetFilter(stream, PM_FILT_ACTIVE | PM_FILT_SYSEX); 00379 00380 Filtering is useful when midi routing or midi thru functionality is being 00381 provided by the user application. 00382 For example, you may want to exclude timing messages (clock, MTC, start/stop/continue), 00383 while allowing note-related messages to pass. 00384 Or you may be using a sequencer or drum-machine for MIDI clock information but want to 00385 exclude any notes it may play. 00386 */ 00387 00388 /* Filter bit-mask definitions */ 00390 #define PM_FILT_ACTIVE (1 << 0x0E) 00391 00392 #define PM_FILT_SYSEX (1 << 0x00) 00393 00394 #define PM_FILT_CLOCK (1 << 0x08) 00395 00396 #define PM_FILT_PLAY ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B)) 00397 00398 #define PM_FILT_TICK (1 << 0x09) 00399 00400 #define PM_FILT_FD (1 << 0x0D) 00401 00402 #define PM_FILT_UNDEFINED PM_FILT_FD 00403 00404 #define PM_FILT_RESET (1 << 0x0F) 00405 00406 #define PM_FILT_REALTIME (PM_FILT_ACTIVE | PM_FILT_SYSEX | PM_FILT_CLOCK | \ 00407 PM_FILT_PLAY | PM_FILT_UNDEFINED | PM_FILT_RESET | PM_FILT_TICK) 00408 00409 #define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18)) 00410 00411 #define PM_FILT_CHANNEL_AFTERTOUCH (1 << 0x1D) 00412 00413 #define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A) 00414 00415 #define PM_FILT_AFTERTOUCH (PM_FILT_CHANNEL_AFTERTOUCH | PM_FILT_POLY_AFTERTOUCH) 00416 00417 #define PM_FILT_PROGRAM (1 << 0x1C) 00418 00419 #define PM_FILT_CONTROL (1 << 0x1B) 00420 00421 #define PM_FILT_PITCHBEND (1 << 0x1E) 00422 00423 #define PM_FILT_MTC (1 << 0x01) 00424 00425 #define PM_FILT_SONG_POSITION (1 << 0x02) 00426 00427 #define PM_FILT_SONG_SELECT (1 << 0x03) 00428 00429 #define PM_FILT_TUNE (1 << 0x06) 00430 00431 #define PM_FILT_SYSTEMCOMMON (PM_FILT_MTC | PM_FILT_SONG_POSITION | PM_FILT_SONG_SELECT | PM_FILT_TUNE) 00432 00433 00434 PMEXPORT PmError Pm_SetFilter( PortMidiStream* stream, int32_t filters ); 00435 00436 #define Pm_Channel(channel) (1<<(channel)) 00437 00452 PMEXPORT PmError Pm_SetChannelMask(PortMidiStream *stream, int mask); 00453 00462 PMEXPORT PmError Pm_Abort( PortMidiStream* stream ); 00463 00469 PMEXPORT PmError Pm_Close( PortMidiStream* stream ); 00470 00494 PmError Pm_Synchronize( PortMidiStream* stream ); 00495 00496 00504 #define Pm_Message(status, data1, data2) \ 00505 ((((data2) << 16) & 0xFF0000) | \ 00506 (((data1) << 8) & 0xFF00) | \ 00507 ((status) & 0xFF)) 00508 #define Pm_MessageStatus(msg) ((msg) & 0xFF) 00509 #define Pm_MessageData1(msg) (((msg) >> 8) & 0xFF) 00510 #define Pm_MessageData2(msg) (((msg) >> 16) & 0xFF) 00511 00512 typedef int32_t PmMessage; 00578 typedef struct { 00579 PmMessage message; 00580 PmTimestamp timestamp; 00581 } PmEvent; 00582 00613 PMEXPORT int Pm_Read( PortMidiStream *stream, PmEvent *buffer, int32_t length ); 00614 00619 PMEXPORT PmError Pm_Poll( PortMidiStream *stream); 00620 00634 PMEXPORT PmError Pm_Write( PortMidiStream *stream, PmEvent *buffer, int32_t length ); 00635 00642 PMEXPORT PmError Pm_WriteShort( PortMidiStream *stream, PmTimestamp when, int32_t msg); 00643 00647 PMEXPORT PmError Pm_WriteSysEx( PortMidiStream *stream, PmTimestamp when, unsigned char *msg); 00648 00651 #ifdef __cplusplus 00652 } 00653 #endif /* __cplusplus */ 00654 #endif /* PORT_MIDI_H */