portmidi.h

#ifndef PORTMIDI_PORTMIDI_H
#define PORTMIDI_PORTMIDI_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.
 */
/** 
    \defgroup grp_basics Basic Definitions
    @{
*/

#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, /**< Normal return value indicating no error. */
    pmNoData = 0, /**< @brief No error, also indicates no data available.
                   * Use this constant where a value greater than zero would
                   * indicate data is available.
                   */
    pmGotData = 1, /**< A "no error" return also indicating data available. */
    pmHostError = -10000,
    pmInvalidDeviceId, /**< Out of range or 
                        * output device when input is requested or 
                        * input device when output is requested or
                        * device is already opened. 
                        */
    pmInsufficientMemory,
    pmBufferTooSmall,
    pmBufferOverflow,
    pmBadPtr, /**< #PortMidiStream parameter is NULL or
               * stream is not opened or
               * stream is output when input is required or
               * stream is input when output is required. */
    pmBadData, /**< Illegal midi data, e.g., missing EOX. */
    pmInternalError,
    pmBufferMaxSize, /**< Buffer is already as large as it can be. */
    pmNotImplemented, /**< The function is not implemented, nothing was done. */
    pmInterfaceNotSupported, /**< The requested interface is not supported. */
    pmNameConflict, /**< Cannot create virtual device because name is taken. */
    pmDeviceRemoved  /**< Output attempted after (USB) device was removed. */
    /* NOTE: If you add a new error type, you must update Pm_GetErrorText(). */
} PmError; /**< @brief @enum PmError PortMidi error code; a common return type. 
            * No error is indicated by zero; errors are indicated by < 0.
            */

/**
    Pm_Initialize() is the library initialization function - call this before
    using the library.

    *NOTE:* PortMidi scans for available devices when #Pm_Initialize
    is called.  To observe subsequent changes in the available
    devices, you must shut down PortMidi by calling #Pm_Terminate and
    then restart by calling #Pm_Initialize again. *IMPORTANT*: On
    MacOS, #Pm_Initialize *must* always be called on the same
    thread. Otherwise, changes in the available MIDI devices will
    *not* be seen by PortMidi. As an example, if you start PortMidi in
    a thread for processing MIDI, do not try to rescan devices by
    calling #Pm_Initialize in a GUI thread. Instead, start PortMidi
    the first time and every time in the GUI thread.  Alternatively,
    let the GUI request a restart in the MIDI thread.  (These
    restrictions only apply to macOS.) Speaking of threads, on all
    platforms, you are allowed to call #Pm_Initialize in one thread,
    yet send MIDI or poll for incoming MIDI in another
    thread. However, PortMidi is not "thread safe," which means you
    cannot allow threads to call PortMidi functions concurrently.

    @return pmNoError.

    PortMidi is designed to support multiple interfaces (such as ALSA,
    CoreMIDI and WinMM). It is possible to return pmNoError because there
    are no supported interfaces. In that case, zero devices will be 
    available.
*/
PMEXPORT PmError Pm_Initialize(void);

/**
    Pm_Terminate() is the library termination function - call this after
    using the library.
*/
PMEXPORT PmError Pm_Terminate(void);

/** Represents an open MIDI device. */
typedef void PortMidiStream;

/** A shorter form of #PortMidiStream. */
#define PmStream PortMidiStream

/** Test whether stream has a pending host error. Normally, the client
    finds out about errors through returned error codes, but some
    errors can occur asynchronously where the client does not
    explicitly call a function, and therefore cannot receive an error
    code.  The client can test for a pending error using
    Pm_HasHostError(). If true, the error can be accessed by calling
    Pm_GetHostErrorText().  Pm_Poll() is similar to Pm_HasHostError(),
    but if there is no error, it will return TRUE (1) if there is a
    pending input message.
*/
PMEXPORT int Pm_HasHostError(PortMidiStream * stream);


/** Translate portmidi error number into human readable message.
    These strings are constants (set at compile time) so client has 
    no need to allocate storage.
*/
PMEXPORT const char *Pm_GetErrorText(PmError errnum);

/** Translate portmidi host error into human readable message.
    These strings are computed at run time, so client has to allocate storage.
    After this routine executes, the host error is cleared. 
*/
PMEXPORT void Pm_GetHostErrorText(char * msg, unsigned int len);

/** Any host error msg has at most this many characters, including EOS. */
#define PM_HOST_ERROR_MSG_LEN 256u 

/** Devices are represented as small integers. Device ids range from 0
    to Pm_CountDevices()-1. Pm_GetDeviceInfo() is used to get information
    about the device, and Pm_OpenInput() and PmOpenOutput() are used to
    open the device.
*/
typedef int PmDeviceID;

/** This PmDeviceID (constant) value represents no device and may be
    returned by  Pm_GetDefaultInputDeviceID() or
    Pm_GetDefaultOutputDeviceID() if no default exists.
*/
#define pmNoDevice -1

/** MIDI device information is returned in this structure, which is
    owned by PortMidi and read-only to applications. See Pm_GetDeviceInfo().
*/
#define PM_DEVICEINFO_VERS 200
typedef struct {
    int structVersion; /**< @brief this internal structure version */ 
    const char *interf; /**< @brief underlying MIDI API, e.g. 
                                    "MMSystem" or "DirectX" */
    char *name;   /**< @brief device name, e.g. "USB MidiSport 1x1" */
    int input; /**< @brief true iff input is available */
    int output; /**< @brief true iff output is available */
    int opened; /**< @brief used by generic PortMidi for error checking */
    int is_virtual; /**< @brief true iff this is/was a virtual device */
} PmDeviceInfo;

/** MIDI system-dependent device or driver info is passed in this
    structure, which is owned by the caller.
*/
#define PM_SYSDEPINFO_VERS 210

enum PmSysDepPropertyKey {
    pmKeyNone = 0,  /**< a "noop" key value */
    /** CoreMIDI Manufacturer name, value is string */
    pmKeyCoreMidiManufacturer = 1,
    /** Linux ALSA snd_seq_port_info_set_name, value is a string. Can be 
        passed in PmSysDepInfo to Pm_OpenInput or Pm_OpenOutput when opening
        a device. The created port will be named accordingly and will be 
        visible for externally made connections (subscriptions). (Linux ALSA
        ports are always enabled for this, but only get application-specific
        names if you give it one.) This key/value is ignored when opening
        virtual ports, which are named when they are created.) */
    pmKeyAlsaPortName = 2,
    /** Linux ALSA snd_seq_set_client_name, value is a string.
        Can be passed in PmSysDepInfo to Pm_OpenInput or Pm_OpenOutput.
        Pm_CreateVirtualInput or Pm_CreateVirtualOutput. Will override
        any previously set client name and applies to all ports. */
    pmKeyAlsaClientName = 3
    /* if system-dependent code introduces more options, register
       the key here to avoid conflicts. */
};

/** System-dependent information can be passed when creating and opening
    ports using this data structure, which stores alternating keys and
    values (addresses). See `pm_test/sendvirtual.c`, `pm_test/recvvirtual.c`,
    and `pm_test/testio.c` for examples.
 */
typedef struct {
    int structVersion;  /**< @brief this structure version */
    int length;  /**< @brief number of properties in this structure */
    struct {
        enum PmSysDepPropertyKey key;
        const void *value;
    } properties[];
} PmSysDepInfo;


/** Get devices count, ids range from 0 to Pm_CountDevices()-1. */
PMEXPORT int Pm_CountDevices(void);

/**
    Return the default device ID or pmNoDevice if there are no devices.
    The result (but not pmNoDevice) can be passed to Pm_OpenMidi().
    
    The use of these functions is not recommended. There is no natural
    "default device" on any system, so defaults must be set by users.
    (Currently, PortMidi just returns the first device it finds as
    "default", so if there *is* a default, implementors should use
    pm_add_device to add system default input and output devices
    first.)

    The recommended solution is pass the burden to applications. It is
    easy to scan devices with PortMidi and build a device menu, and to
    save menu selections in application preferences for next
    time. This is my recommendation for any GUI program. For simple
    command-line applications and utilities, see pm_test where all the
    test programs now accept device numbers on the command line and/or
    prompt for their entry.

    On linux, you can create virtual ports and use an external program
    to set up inter-application and device connections.

    Some advice for preferences: MIDI devices used to be built-in or
    plug-in cards, so the numbers rarely changed. Now MIDI devices are
    often plug-in USB devices, so device numbers change, and you
    probably need to design to reinitialize PortMidi to rescan
    devices. MIDI is pretty stateless, so this isn't a big problem,
    although it means you cannot find a new device while playing or
    recording MIDI.

    Since device numbering can change whenever a USB device is plugged
    in, preferences should record *names* of devices rather than
    device numbers. It is simple enough to use string matching to find
    a prefered device, so PortMidi does not provide any built-in
    lookup function.
*/
PMEXPORT PmDeviceID Pm_GetDefaultInputDeviceID(void);

/** @brief see PmDeviceID Pm_GetDefaultInputDeviceID() */
PMEXPORT PmDeviceID Pm_GetDefaultOutputDeviceID(void);

/** Find a device that matches a pattern. 

    @param pattern a substring of the device name, or if the pattern
    contains the two-character separator ", ", then the first part of
    the pattern represents a device interface substring and the second
    part after the separator represents a device name substring. 

    @param is_input restricts the search to an input when true, or an
    output when false.

    @return the number of the first device whose device interface
    contains the interface pattern (if any), whose device name
    contains the name pattern, and whose direction (input or output)
    matches the #is_input parameter. If no match is found, #pmNoDevice
    (-1) is returned.
*/
PMEXPORT PmDeviceID Pm_FindDevice(char *pattern, int is_input);


/** Represents a millisecond clock with arbitrary start time. 
    This type is used for all MIDI timestamps and clocks.
*/
typedef int32_t PmTimestamp;
typedef PmTimestamp (*PmTimeProcPtr)(void *time_info);

/** TRUE if t1 before t2 */
#define PmBefore(t1,t2) (((t1)-(t2)) < 0)
/** @} */
/** 
    \defgroup grp_device Input/Output Devices Handling
    @{
*/
/** Get a PmDeviceInfo structure describing a MIDI device.
    
    @param id the device to be queried.

    If \p id is out of range or if the device designates a deleted
    virtual device, the function returns NULL.

    The returned structure is owned by the PortMidi implementation and
    must not be manipulated or freed. The pointer is guaranteed to be
    valid between calls to Pm_Initialize() and Pm_Terminate().
*/
PMEXPORT const PmDeviceInfo *Pm_GetDeviceInfo(PmDeviceID id);

/** Open a MIDI device for input.

    @param stream the address of a #PortMidiStream pointer which will
    receive a pointer to the newly opened stream.

    @param inputDevice the ID of the device to be opened (see #PmDeviceID).

    @param inputSysDepInfo a pointer to an optional system-dependent
    data structure (a #PmSysDepInfo struct) containing additional
    information for device setup or handle processing. This parameter
    is never required for correct operation. If not used, specify
    NULL.  Declared `void *` here for backward compatibility. Note that
    with Linux ALSA, you can use this parameter to specify a client name
    and port name.

    @param bufferSize the number of input events to be buffered
    waiting to be read using Pm_Read(). Messages will be lost if the
    number of unread messages exceeds this value.

    @param time_proc (address of) a procedure that returns time in
    milliseconds. It may be NULL, in which case a default millisecond
    timebase (PortTime) is used. If the application wants to use
    PortTime, it should start the timer (call Pt_Start) before calling
    Pm_OpenInput or Pm_OpenOutput. If the application tries to start
    the timer *after* Pm_OpenInput or Pm_OpenOutput, it may get a
    ptAlreadyStarted error from Pt_Start, and the application's
    preferred time resolution and callback function will be ignored.
    \p time_proc result values are appended to incoming MIDI data,
    normally by mapping system-provided timestamps to the \p time_proc
    timestamps to maintain the precision of system-provided
    timestamps.

    @param time_info is a pointer passed to time_proc.

    @return #pmNoError and places a pointer to a valid
    #PortMidiStream in the stream argument.  If the open operation
    fails, a nonzero error code is returned (see #PMError) and
    the value of stream is invalid.

    Any stream that is successfully opened should eventually be closed
    by calling Pm_Close().
*/
PMEXPORT PmError Pm_OpenInput(PortMidiStream** stream,
                PmDeviceID inputDevice,
                void *inputSysDepInfo,
                int32_t bufferSize,
                PmTimeProcPtr time_proc,
                void *time_info);

/** Open a MIDI device for output.

    @param stream the address of a #PortMidiStream pointer which will
    receive a pointer to the newly opened stream.

    @param outputDevice the ID of the device to be opened (see #PmDeviceID).

    @param inputSysDepInfo a pointer to an optional system-specific
    data structure (a #PmSysDepInfo struct) containing additional
    information for device setup or handle processing. This parameter
    is never required for correct operation. If not used, specify
    NULL. Declared `void *` here for backward compatibility. Note that
    with Linux ALSA, you can use this parameter to specify a client name
    and port name.

    @param bufferSize the number of output events to be buffered
    waiting for output. In some cases -- see below -- PortMidi does
    not buffer output at all and merely passes data to a lower-level
    API, in which case \p bufferSize is ignored. Since MIDI speeds now
    vary from 1 to 50 or more messages per ms (over USB), put some
    thought into this number. E.g. if latency is 20ms and you want to
    burst 100 messages in that time (5000 messages per second), you
    should set \p bufferSize to at least 100. The default on Windows
    assumes an average rate of 500 messages per second and in this
    example, output would be slowed waiting for free buffers.
    
    @param latency the delay in milliseconds applied to timestamps
    to determine when the output should actually occur. (If latency is
    < 0, 0 is assumed.)  If latency is zero, timestamps are ignored
    and all output is delivered immediately. If latency is greater
    than zero, output is delayed until the message timestamp plus the
    latency. (NOTE: the time is measured relative to the time source
    indicated by time_proc. Timestamps are absolute, not relative
    delays or offsets.) In some cases, PortMidi can obtain better
    timing than your application by passing timestamps along to the
    device driver or hardware, so the best strategy to minimize jitter
    is: wait until the real time to send the message, compute the
    message, attach the *ideal* output time (not the current real
    time, because some time may have elapsed), and send the
    message. The \p latency will be added to the timestamp, and
    provided the elapsed computation time has not exceeded \p latency,
    the message will be delivered according to the timestamp. If the
    real time is already past the timestamp, the message will be
    delivered as soon as possible. Latency may also help you to
    synchronize MIDI data to audio data by matching \p latency to the
    audio buffer latency.

    @param time_proc (address of) a pointer to a procedure that
    returns time in milliseconds. It may be NULL, in which case a
    default millisecond timebase (PortTime) is used. If the
    application wants to use PortTime, it should start the timer (call
    Pt_Start) before calling #Pm_OpenInput or #Pm_OpenOutput. If the
    application tries to start the timer *after* #Pm_OpenInput or
    #Pm_OpenOutput, it may get a #ptAlreadyStarted error from #Pt_Start,
    and the application's preferred time resolution and callback
    function will be ignored.  \p time_proc times are used to schedule
    outgoing MIDI data (when latency is non-zero), usually by mapping
    from time_proc timestamps to internal system timestamps to
    maintain the precision of system-supported timing.

    @param time_info a pointer passed to time_proc.

    @return #pmNoError and places a pointer to a valid #PortMidiStream
    in the stream argument.  If the operation fails, a nonzero error
    code is returned (see PMError) and the value of \p stream is
    invalid.

    Note: ALSA appears to have a fixed-size priority queue for timed
    output messages. Testing indicates the queue can hold a little
    over 400 3-byte MIDI messages. Thus, you can send 10,000
    messages/second if the latency is 30ms (30ms * 10000 msgs/sec *
    0.001 sec/ms = 300 msgs), but not if the latency is 50ms
    (resulting in about 500 pending messages, which is greater than
    the 400 message limit). Since timestamps in ALSA are relative,
    they are of less value than absolute timestamps in macOS and
    Windows. This is a limitation of ALSA and apparently a design
    flaw.

    Example 1: If I provide a timestamp of 5000, latency is 1, and
    time_proc returns 4990, then the desired output time will be when
    time_proc returns timestamp+latency = 5001. This will be 5001-4990
    = 11ms from now.

    Example 2: If I want to send at exactly 5010, and latency is 10, I
    should wait until 5000, compute the messages and provide a
    timestamp of 5000. As long as computation takes less than 10ms,
    the message will be delivered at time 5010.

    Example 3 (recommended): It is often convenient to ignore latency.
    E.g. if a sequence says to output at time 5010, just wait until
    5010, compute the message and use 5010 for the timestamp. Delivery
    will then be at 5010+latency, but unless you are synchronizing to
    something else, the absolute delay by latency will not matter.

    Any stream that is successfully opened should eventually be closed
    by calling Pm_Close().
*/
PMEXPORT PmError Pm_OpenOutput(PortMidiStream** stream,
                PmDeviceID outputDevice,
                void *outputSysDepInfo,
                int32_t bufferSize,
                PmTimeProcPtr time_proc,
                void *time_info,
                int32_t latency);

/** Create  a virtual input device.

    @param name gives the virtual device name, which is visible to
    other applications.

    @param interf is the interface (System API) used to create the
    device Default interfaces are "MMSystem", "CoreMIDI" and
    "ALSA". Currently, these are the only ones implemented, but future
    implementations could support DirectMusic, Jack, sndio, or others.

    @param sysDepInfo contains interface-dependent additional
    information (a #PmSysDepInfo struct), e.g., hints or options. This
    parameter is never required for correct operation. If not used,
    specify NULL. Declared `void *` here for backward compatibility.

    @return a device ID or #pmNameConflict (\p name is invalid or
    already exists) or #pmInterfaceNotSupported (\p interf is does not
    match a supported interface).

    The created virtual device appears to other applications as if it
    is an output device. The device must be opened to obtain a stream
    and read from it.

    Virtual devices are not supported by Windows (Multimedia API). Calls
    on Windows do nothing except return #pmNotImplemented.
*/
PMEXPORT PmError Pm_CreateVirtualInput(const char *name,
                                       const char *interf,
                                       void *sysDepInfo);

/** Create a virtual output device.

    @param name gives the virtual device name, which is visible to
    other applications.

    @param interf is the interface (System API) used to create the
    device Default interfaces are "MMSystem", "CoreMIDI" and
    "ALSA". Currently, these are the only ones implemented, but future
    implementations could support DirectMusic, Jack, sndio, or others.

    @param sysDepInfo contains interface-dependent additional
    information (a #PmSysDepInfo struct), e.g., hints or options. This
    parameter is never required for correct operation. If not used,
    specify NULL. Declared `void *` here for backward compatibility.

    @return a device ID or #pmInvalidDeviceId (\p name is invalid or
    already exists) or #pmInterfaceNotSupported (\p interf is does not
    match a supported interface).

    The created virtual device appears to other applications as if it
    is an input device. The device must be opened to obtain a stream
    and write to it.

    Virtual devices are not supported by Windows (Multimedia API). Calls
    on Windows do nothing except return #pmNotImplemented.
*/
PMEXPORT PmError Pm_CreateVirtualOutput(const char *name,
                                        const char *interf,
                                        void *sysDepInfo);

/** Remove a virtual device.

   @param device a device ID (small integer) designating the device.

   The device is removed; other applications can no longer see or open
   this virtual device, which may be either for input or output. The
   device must not be open. The device ID may be reused, but existing
   devices are not renumbered. This means that the device ID could be
   in the range from 0 to #Pm_CountDevices(), yet the device ID does
   not designate a device. In that case, passing the ID to
   #Pm_GetDeviceInfo() will return NULL.

   @return #pmNoError if the device was deleted or #pmInvalidDeviceId
   if the device is open, already deleted, or \p device is out of
   range.
*/
PMEXPORT PmError Pm_DeleteVirtualDevice(PmDeviceID device);
  /** @} */

/**
   @defgroup grp_events_filters Events and Filters Handling
   @{
*/

/* Filter bit-mask definitions */
/** filter active sensing messages (0xFE): */
#define PM_FILT_ACTIVE (1 << 0x0E)
/** filter system exclusive messages (0xF0): */
#define PM_FILT_SYSEX (1 << 0x00)
/** filter MIDI clock message (0xF8) */
#define PM_FILT_CLOCK (1 << 0x08)
/** filter play messages (start 0xFA, stop 0xFC, continue 0xFB) */
#define PM_FILT_PLAY ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B))
/** filter tick messages (0xF9) */
#define PM_FILT_TICK (1 << 0x09)
/** filter undefined FD messages */
#define PM_FILT_FD (1 << 0x0D)
/** filter undefined real-time messages */
#define PM_FILT_UNDEFINED PM_FILT_FD
/** filter reset messages (0xFF) */
#define PM_FILT_RESET (1 << 0x0F)
/** filter all real-time messages */
#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)
/** filter note-on and note-off (0x90-0x9F and 0x80-0x8F */
#define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18))
/** filter channel aftertouch (most midi controllers use this) (0xD0-0xDF)*/
#define PM_FILT_CHANNEL_AFTERTOUCH (1 << 0x1D)
/** per-note aftertouch (0xA0-0xAF) */
#define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A)
/** filter both channel and poly aftertouch */
#define PM_FILT_AFTERTOUCH (PM_FILT_CHANNEL_AFTERTOUCH | \
                            PM_FILT_POLY_AFTERTOUCH)
/** Program changes (0xC0-0xCF) */
#define PM_FILT_PROGRAM (1 << 0x1C)
/** Control Changes (CC's) (0xB0-0xBF)*/
#define PM_FILT_CONTROL (1 << 0x1B)
/** Pitch Bender (0xE0-0xEF*/
#define PM_FILT_PITCHBEND (1 << 0x1E)
/** MIDI Time Code (0xF1)*/
#define PM_FILT_MTC (1 << 0x01)
/** Song Position (0xF2) */
#define PM_FILT_SONG_POSITION (1 << 0x02)
/** Song Select (0xF3)*/
#define PM_FILT_SONG_SELECT (1 << 0x03)
/** Tuning request (0xF6) */
#define PM_FILT_TUNE (1 << 0x06)
/** All System Common messages (mtc, song position, song select, tune request) */
#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);

/** Create a mask that filters one channel. */
#define Pm_Channel(channel) (1<<(channel))

/** Filter incoming messages based on channel.

    @param stream an open MIDI input stream.

    @param mask indicates channels to be received.

    @return #pmNoError or an error code.

    The \p mask is a 16-bit bitfield corresponding to appropriate channels.
    The #Pm_Channel macro can assist in calling this function.
    I.e. to receive only input on channel 1, call with
    Pm_SetChannelMask(Pm_Channel(1));
    Multiple channels should be OR'd together, like
    Pm_SetChannelMask(Pm_Channel(10) | Pm_Channel(11))

    Note that channels are numbered 0 to 15 (not 1 to 16). Most 
    synthesizer and interfaces number channels starting at 1, but
    PortMidi numbers channels starting at 0.

    All channels are allowed by default
*/
PMEXPORT PmError Pm_SetChannelMask(PortMidiStream *stream, int mask);

/** Terminate outgoing messages immediately.

    @param stream an open MIDI output stream.

    @result #pmNoError or an error code.

    The caller should immediately close the output port; this call may
    result in transmission of a partial MIDI message.  There is no
    abort for Midi input because the user can simply ignore messages
    in the buffer and close an input device at any time. If the
    specified behavior cannot be achieved through the system-level
    interface (ALSA, CoreMIDI, etc.), the behavior may be that of 
    Pm_Close().
 */
PMEXPORT PmError Pm_Abort(PortMidiStream* stream);
     
/** Close a midi stream, flush any pending buffers if possible.

    @param stream an open MIDI input or output stream.

    @result #pmNoError or an error code.

    If the system-level interface (ALSA, CoreMIDI, etc.) does not
    support flushing remaining messages, the behavior may be one of
    the following (most preferred first): block until all pending
    timestamped messages are delivered; deliver messages to a server
    or kernel process for later delivery but return immediately; drop
    messages (as in Pm_Abort()).  Therefore, to be safe, applications
    should wait until the output queue is empty before calling
    Pm_Close(). E.g. calling Pt_Sleep(100 + latency); will give a
    100ms "cushion" beyond latency (if any) before closing.
*/
PMEXPORT PmError Pm_Close(PortMidiStream* stream);

/** (re)synchronize to the time_proc passed when the stream was opened.

    @param stream an open MIDI input or output stream.

    @result #pmNoError or an error code.

    Typically, this is used when the stream must be opened before the
    time_proc reference is actually advancing. In this case, message
    timing may be erratic, but since timestamps of zero mean "send
    immediately," initialization messages with zero timestamps can be
    written without a functioning time reference and without
    problems. Before the first MIDI message with a non-zero timestamp
    is written to the stream, the time reference must begin to advance
    (for example, if the time_proc computes time based on audio
    samples, time might begin to advance when an audio stream becomes
    active). After time_proc return values become valid, and BEFORE
    writing the first non-zero timestamped MIDI message, call
    Pm_Synchronize() so that PortMidi can observe the difference
    between the current time_proc value and its MIDI stream time.
    
    In the more normal case where time_proc values advance
    continuously, there is no need to call #Pm_Synchronize. PortMidi
    will always synchronize at the first output message and
    periodically thereafter.
*/
PMEXPORT PmError Pm_Synchronize(PortMidiStream* stream);


/** Encode a short Midi message into a 32-bit word. If data1
    and/or data2 are not present, use zero.
*/
#define Pm_Message(status, data1, data2) \
         ((((data2) << 16) & 0xFF0000) | \
          (((data1) << 8) & 0xFF00) | \
          ((status) & 0xFF))
/** Extract the status field from a 32-bit midi message. */
#define Pm_MessageStatus(msg) ((msg) & 0xFF)
/** Extract the 1st data field (e.g., pitch) from a 32-bit midi message. */
#define Pm_MessageData1(msg) (((msg) >> 8) & 0xFF)
/** Extract the 2nd data field (e.g., velocity) from a 32-bit midi message. */
#define Pm_MessageData2(msg) (((msg) >> 16) & 0xFF)

typedef uint32_t PmMessage; /**< @brief see #PmEvent */
/**
   All MIDI data comes in the form of PmEvent structures. A sysex
   message is encoded as a sequence of PmEvent structures, with each
   structure carrying 4 bytes of the message, i.e. only the first
   PmEvent carries the status byte.

   All other MIDI messages take 1 to 3 bytes and are encoded in a whole
   PmMessage with status in the low-order byte and remaining bytes 
   unused, i.e., a 3-byte note-on message will occupy 3 low-order bytes
   of PmMessage, leaving the high-order byte unused.

   Note that MIDI allows nested messages: the so-called "real-time" MIDI 
   messages can be inserted into the MIDI byte stream at any location, 
   including within a sysex message. MIDI real-time messages are one-byte
   messages used mainly for timing (see the MIDI spec). PortMidi retains 
   the order of non-real-time MIDI messages on both input and output, but 
   it does not specify exactly how real-time messages are processed. This
   is particulary problematic for MIDI input, because the input parser 
   must either prepare to buffer an unlimited number of sysex message 
   bytes or to buffer an unlimited number of real-time messages that 
   arrive embedded in a long sysex message. To simplify things, the input
   parser is allowed to pass real-time MIDI messages embedded within a 
   sysex message, and it is up to the client to detect, process, and 
   remove these messages as they arrive.

   When receiving sysex messages, the sysex message is terminated
   by either an EOX status byte (anywhere in the 4 byte messages) or
   by a non-real-time status byte in the low order byte of the message.
   If you get a non-real-time status byte but there was no EOX byte, it 
   means the sysex message was somehow truncated. This is not
   considered an error; e.g., a missing EOX can result from the user
   disconnecting a MIDI cable during sysex transmission.

   A real-time message can occur within a sysex message. A real-time 
   message will always occupy a full PmEvent with the status byte in 
   the low-order byte of the PmEvent message field. (This implies that
   the byte-order of sysex bytes and real-time message bytes may not
   be preserved -- for example, if a real-time message arrives after
   3 bytes of a sysex message, the real-time message will be delivered
   first. The first word of the sysex message will be delivered only
   after the 4th byte arrives, filling the 4-byte PmEvent message field.
   
   The timestamp field is observed when the output port is opened with
   a non-zero latency. A timestamp of zero means "use the current time",
   which in turn means to deliver the message with a delay of
   latency (the latency parameter used when opening the output port.)
   Do not expect PortMidi to sort data according to timestamps -- 
   messages should be sent in the correct order, and timestamps MUST 
   be non-decreasing. See also "Example" for Pm_OpenOutput() above.

   A sysex message will generally fill many #PmEvent structures. On 
   output to a #PortMidiStream with non-zero latency, the first timestamp
   on sysex message data will determine the time to begin sending the 
   message. PortMidi implementations may ignore timestamps for the 
   remainder of the sysex message. 
   
   On input, the timestamp ideally denotes the arrival time of the 
   status byte of the message. The first timestamp on sysex message 
   data will be valid. Subsequent timestamps may denote 
   when message bytes were actually received, or they may be simply 
   copies of the first timestamp.

   Timestamps for nested messages: If a real-time message arrives in 
   the middle of some other message, it is enqueued immediately with 
   the timestamp corresponding to its arrival time. The interrupted 
   non-real-time message or 4-byte packet of sysex data will be enqueued 
   later. The timestamp of interrupted data will be equal to that of
   the interrupting real-time message to insure that timestamps are
   non-decreasing.
 */
typedef struct {
    PmMessage      message;
    PmTimestamp    timestamp;
} PmEvent;

/** @} */

/** \defgroup grp_io Reading and Writing Midi Messages
    @{
*/
/** Retrieve midi data into a buffer. 

    @param stream the open input stream.

    @return the number of events read, or, if the result is negative,
    a #PmError value will be returned.

    The Buffer Overflow Problem

    The problem: if an input overflow occurs, data will be lost,
    ultimately because there is no flow control all the way back to
    the data source.  When data is lost, the receiver should be
    notified and some sort of graceful recovery should take place,
    e.g. you shouldn't resume receiving in the middle of a long sysex
    message.

    With a lock-free fifo, which is pretty much what we're stuck with
    to enable portability to the Mac, it's tricky for the producer and
    consumer to synchronously reset the buffer and resume normal
    operation.

    Solution: the entire buffer managed by PortMidi will be flushed
    when an overflow occurs. The consumer (Pm_Read()) gets an error
    message (#pmBufferOverflow) and ordinary processing resumes as
    soon as a new message arrives. The remainder of a partial sysex
    message is not considered to be a "new message" and will be
    flushed as well.
*/
PMEXPORT int Pm_Read(PortMidiStream *stream, PmEvent *buffer, int32_t length);

/** Test whether input is available.

    @param stream an open input stream.

    @return TRUE, FALSE, or an error value. 

    If there was an asynchronous error, pmHostError is returned and you must
    call again to determine if input is (also) available.

    You should probably *not* use this function. Call Pm_Read()
    instead. If it returns 0, then there is no data available. It is
    possible for Pm_Poll() to return TRUE before the complete message
    is available, so Pm_Read() could return 0 even after Pm_Poll()
    returns TRUE. Only call Pm_Poll() if you want to know that data is
    probably available even though you are not ready to receive data.
*/
PMEXPORT PmError Pm_Poll(PortMidiStream *stream);

/** Write MIDI data from a buffer. 

    @param stream an open output stream.

    @param buffer (address of) an array of MIDI event data.

    @param length the length of the \p buffer.

    @return TRUE, FALSE, or an error value.

    \b buffer may contain:
        - short messages 
        - sysex messages that are converted into a sequence of PmEvent
          structures, e.g. sending data from a file or forwarding them
          from midi input, with 4 SysEx bytes per PmEvent message,
          low-order byte first, until the last message, which may
          contain from 1 to 4 bytes ending in MIDI EOX (0xF7).
        - PortMidi allows 1-byte real-time messages to be embedded
          within SysEx messages, but only on 4-byte boundaries so
          that SysEx data always uses a full 4 bytes (except possibly
          at the end). Each real-time message always occupies a full
          PmEvent (3 of the 4 bytes in the PmEvent's message are
          ignored) even when embedded in a SysEx message.

    Use Pm_WriteSysEx() to write a sysex message stored as a contiguous 
    array of bytes.

    Sysex data may contain embedded real-time messages.

    \p buffer is managed by the caller. The buffer may be destroyed
    as soon as this call returns.
*/
PMEXPORT PmError Pm_Write(PortMidiStream *stream, PmEvent *buffer,
                          int32_t length);

/** Write a timestamped non-system-exclusive midi message.

    @param stream an open output stream.

    @param when timestamp for the event.

    @param msg the data for the event.

    @result #pmNoError or an error code.

    Messages are delivered in order, and timestamps must be
    non-decreasing. (But timestamps are ignored if the stream was
    opened with latency = 0, and otherwise, non-decreasing timestamps
    are "corrected" to the lowest valid value.)
*/
PMEXPORT PmError Pm_WriteShort(PortMidiStream *stream, PmTimestamp when,
                               PmMessage msg);

/** Write a timestamped system-exclusive midi message.

    @param stream an open output stream.

    @param when timestamp for the event.

    @param msg the sysex message, terminated with an EOX status byte.

    @result #pmNoError or an error code.

    \p msg is managed by the caller and may be destroyed when this
    call returns.
*/
PMEXPORT PmError Pm_WriteSysEx(PortMidiStream *stream, PmTimestamp when, 
                               unsigned char *msg);

/** @} */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* PORTMIDI_PORTMIDI_H */