portmidi.h

#ifndef PORT_MIDI_H
#define PORT_MIDI_H
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
/*
 * PortMidi Portable Real-Time MIDI Library
 * PortMidi API Header File
 * Latest version available at: http://sourceforge.net/projects/portmedia
 *
 * Copyright (c) 1999-2000 Ross Bencina and Phil Burk
 * Copyright (c) 2001-2006 Roger B. Dannenberg
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files
 * (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge,
 * publish, distribute, sublicense, and/or sell copies of the Software,
 * and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
/*
 * The text above constitutes the entire PortMidi license; however, 
 * the PortMusic community also makes the following non-binding requests:
 *
 * Any person wishing to distribute modifications to the Software is
 * requested to send the modifications to the original developer so that
 * they can be incorporated into the canonical version. It is also
 * requested that these non-binding requests be included along with the 
 * license above.
 */
 
/* CHANGELOG FOR PORTMIDI
 *     (see ../CHANGELOG.txt)
 *
 * NOTES ON HOST ERROR REPORTING: 
 *
 *    PortMidi errors (of type PmError) are generic,
 *    system-independent errors.  When an error does not map to one of
 *    the more specific PmErrors, the catch-all code pmHostError is
 *    returned. This means that PortMidi has retained a more specific
 *    system-dependent error code. The caller can get more information
 *    by calling Pm_GetHostErrorText() to get a text string describing
 *    the error. Host errors can arise asynchronously from callbacks,
 *    * so there is no specific return code. Asynchronous errors are
 *    checked and reported by Pm_Poll. You can also check by calling
 *    Pm_HasHostError().  If this returns TRUE, Pm_GetHostErrorText()
 *    will return a text description of the error.
 *
 * NOTES ON COMPILE-TIME SWITCHES
 *
 *    DEBUG assumes stdio and a console. Use this if you want
 *        automatic, simple error reporting, e.g. for prototyping. If
 *        you are using MFC or some other graphical interface with no
 *        console, DEBUG probably should be undefined.
 *    PM_CHECK_ERRORS more-or-less takes over error checking for
 *        return values, stopping your program and printing error
 *        messages when an error occurs. This also uses stdio for
 *        console text I/O. You can selectively disable this error
 *        checking by declaring extern int pm_check_errors; and 
 *        setting pm_check_errors = FALSE; You can also reenable.
 */
#include <stdint.h>
 
#ifdef _WINDLL
#define PMEXPORT __declspec(dllexport)
#else
#define PMEXPORT 
#endif
 
#ifndef FALSE
    #define FALSE 0
#endif
#ifndef TRUE
    #define TRUE 1
#endif
 
/* default size of buffers for sysex transmission: */
#define PM_DEFAULT_SYSEX_BUFFER_SIZE 1024
 
 
typedef enum {
    pmNoError = 0, 
    pmNoData = 0, 
    pmGotData = 1, 
    pmHostError = -10000,
    pmInvalidDeviceId, 
    pmInsufficientMemory,
    pmBufferTooSmall,
    pmBufferOverflow,
    pmBadPtr, 
    pmBadData, 
    pmInternalError,
    pmBufferMaxSize, 
    pmNotImplemented, 
    pmInterfaceNotSupported, 
    pmNameConflict 
    /* NOTE: If you add a new error type, you must update Pm_GetErrorText(). */
} PmError; 
PMEXPORT PmError Pm_Initialize(void);
 
PMEXPORT PmError Pm_Terminate(void);
 
typedef void PortMidiStream;
 
#define PmStream PortMidiStream
 
PMEXPORT int Pm_HasHostError(PortMidiStream * stream);
 
 
PMEXPORT const char *Pm_GetErrorText(PmError errnum);
 
PMEXPORT void Pm_GetHostErrorText(char * msg, unsigned int len);
 
#define PM_HOST_ERROR_MSG_LEN 256u 
 
typedef int PmDeviceID;
 
#define pmNoDevice -1
 
#define PM_DEVICEINFO_VERS 200
typedef struct {
    int structVersion; 
    const char *interf; 
    char *name;   
    int input; 
    int output; 
    int opened; 
    int is_virtual; 
} PmDeviceInfo;
 
PMEXPORT int Pm_CountDevices(void);
 
PMEXPORT PmDeviceID Pm_GetDefaultInputDeviceID(void);
 
PMEXPORT PmDeviceID Pm_GetDefaultOutputDeviceID(void);
 
typedef int32_t PmTimestamp;
typedef PmTimestamp (*PmTimeProcPtr)(void *time_info);
 
#define PmBefore(t1,t2) ((t1-t2) < 0)
PMEXPORT const PmDeviceInfo *Pm_GetDeviceInfo(PmDeviceID id);
 
PMEXPORT PmError Pm_OpenInput(PortMidiStream** stream,
                PmDeviceID inputDevice,
                void *inputDriverInfo,
                int32_t bufferSize,
                PmTimeProcPtr time_proc,
                void *time_info);
 
PMEXPORT PmError Pm_OpenOutput(PortMidiStream** stream,
                PmDeviceID outputDevice,
                void *outputDriverInfo,
                int32_t bufferSize,
                PmTimeProcPtr time_proc,
                void *time_info,
                int32_t latency);
 
PMEXPORT PmError Pm_CreateVirtualInput(const char *name,
                                       const char *interf,
                                       void *deviceInfo);
 
PMEXPORT PmError Pm_CreateVirtualOutput(const char *name,
                                        const char *interf,
                                        void *deviceInfo);
 
PMEXPORT PmError Pm_DeleteVirtualDevice(PmDeviceID device);
/* Filter bit-mask definitions */
#define PM_FILT_ACTIVE (1 << 0x0E)
#define PM_FILT_SYSEX (1 << 0x00)
#define PM_FILT_CLOCK (1 << 0x08)
#define PM_FILT_PLAY ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B))
#define PM_FILT_TICK (1 << 0x09)
#define PM_FILT_FD (1 << 0x0D)
#define PM_FILT_UNDEFINED PM_FILT_FD
#define PM_FILT_RESET (1 << 0x0F)
#define PM_FILT_REALTIME (PM_FILT_ACTIVE | PM_FILT_SYSEX | PM_FILT_CLOCK | \
    PM_FILT_PLAY | PM_FILT_UNDEFINED | PM_FILT_RESET | PM_FILT_TICK)
#define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18))
#define PM_FILT_CHANNEL_AFTERTOUCH (1 << 0x1D)
#define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A)
#define PM_FILT_AFTERTOUCH (PM_FILT_CHANNEL_AFTERTOUCH | \
                            PM_FILT_POLY_AFTERTOUCH)
#define PM_FILT_PROGRAM (1 << 0x1C)
#define PM_FILT_CONTROL (1 << 0x1B)
#define PM_FILT_PITCHBEND (1 << 0x1E)
#define PM_FILT_MTC (1 << 0x01)
#define PM_FILT_SONG_POSITION (1 << 0x02)
#define PM_FILT_SONG_SELECT (1 << 0x03)
#define PM_FILT_TUNE (1 << 0x06)
#define PM_FILT_SYSTEMCOMMON (PM_FILT_MTC | PM_FILT_SONG_POSITION | \
                              PM_FILT_SONG_SELECT | PM_FILT_TUNE)
 
 
/*  Set filters on an open input stream to drop selected input types.
    
    @param stream an open MIDI input stream.
 
    @param filters indicate message types to filter (block).
 
    @return #pmNoError or an error code.
 
    By default, only active sensing messages are filtered.
    To prohibit, say, active sensing and sysex messages, call
    Pm_SetFilter(stream, PM_FILT_ACTIVE | PM_FILT_SYSEX);
 
    Filtering is useful when midi routing or midi thru functionality
    is being provided by the user application.
    For example, you may want to exclude timing messages (clock, MTC,
    start/stop/continue), while allowing note-related messages to pass.
    Or you may be using a sequencer or drum-machine for MIDI clock
    information but want to exclude any notes it may play.
 */
PMEXPORT PmError Pm_SetFilter(PortMidiStream* stream, int32_t filters);
 
#define Pm_Channel(channel) (1<<(channel))
 
PMEXPORT PmError Pm_SetChannelMask(PortMidiStream *stream, int mask);
 
PMEXPORT PmError Pm_Abort(PortMidiStream* stream);
     
PMEXPORT PmError Pm_Close(PortMidiStream* stream);
 
PMEXPORT PmError Pm_Synchronize(PortMidiStream* stream);
 
 
#define Pm_Message(status, data1, data2) \
         ((((data2) << 16) & 0xFF0000) | \
          (((data1) << 8) & 0xFF00) | \
          ((status) & 0xFF))
#define Pm_MessageStatus(msg) ((msg) & 0xFF)
#define Pm_MessageData1(msg) (((msg) >> 8) & 0xFF)
#define Pm_MessageData2(msg) (((msg) >> 16) & 0xFF)
 
typedef int32_t PmMessage; 
typedef struct {
    PmMessage      message;
    PmTimestamp    timestamp;
} PmEvent;
 
PMEXPORT int Pm_Read(PortMidiStream *stream, PmEvent *buffer, int32_t length);
 
PMEXPORT PmError Pm_Poll(PortMidiStream *stream);
 
PMEXPORT PmError Pm_Write(PortMidiStream *stream, PmEvent *buffer,
                          int32_t length);
 
PMEXPORT PmError Pm_WriteShort(PortMidiStream *stream, PmTimestamp when,
                               PmMessage msg);
 
PMEXPORT PmError Pm_WriteSysEx(PortMidiStream *stream, PmTimestamp when, 
                               unsigned char *msg);
 
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* PORT_MIDI_H */