• Main Page
  • Modules
  • Data Structures
  • Files
  • File List

portmidi.h

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 */

Generated on Thu Mar 3 2011 for PortMidi by  doxygen 1.7.1