Java example source code file (PlatformMidi.h)

This example Java source code file (PlatformMidi.h) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

int32, int64, mididevicehandle, midimessage, midimessagequeue, midimessagetype, platform_midi_included, true, ubyte, uint32, use_midi_queue, use_platform_midi_in, use_platform_midi_out, x_platform

The PlatformMidi.h Java example source code

/*
 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

#ifndef PLATFORM_MIDI_INCLUDED
#define PLATFORM_MIDI_INCLUDED


#include "SoundDefs.h"
#include "Configure.h" // put flags for debug msgs etc. here
#include "Utilities.h"


/* do we need the queue ? */
#if (USE_PLATFORM_MIDI_IN == TRUE) || (USE_PLATFORM_MIDI_OUT == TRUE)
 #if X_PLATFORM == X_WINDOWS || X_PLATFORM == X_MACOSX
  #define USE_MIDI_QUEUE TRUE
 #endif
#endif

/* *********************** MIDI TYPES (for all platforms) ******************************* */

/* return value for functions to denote successful completion */
#define MIDI_SUCCESS 0
/* code if function is not supported */
#define MIDI_NOT_SUPPORTED -11111
/* return code for invalid handle */
#define MIDI_INVALID_DEVICEID -11112
/* return code for invalid handle */
#define MIDI_INVALID_HANDLE -11113
/* return code for invalid argument */
#define MIDI_INVALID_ARGUMENT -11114
/* return code for out of memory */
#define MIDI_OUT_OF_MEMORY -11115

// MIDI message types
typedef enum {
    SHORT_MESSAGE = 0,
    LONG_MESSAGE = 1
} MidiMessageType;

// MIDI message object
typedef struct tag_MidiMessage {
    INT64 timestamp;  // in microseconds
    INT32 locked;     // TRUE when event is currently being read
    MidiMessageType type;
    union {
        struct {
            // platform-endianness packed message:
            // status | data1<<8 | data2<<16
            UINT32 packedMsg;
        } s; // short message
        struct {
            UINT32  size;
            // this buffer is read only. It must not be freed.
            UBYTE* data;
            INT32 index; // sysex buffer number
        } l; // long message
    } data;
} MidiMessage;

/* error handling. Implemented in PlatformMidi.c */
char* MIDI_IN_InternalGetErrorString(INT32 err);
char* MIDI_OUT_InternalGetErrorString(INT32 err);


#if USE_MIDI_QUEUE == TRUE
/*
 * Native MIDI message circular buffer
 */
typedef struct tag_MidiQueue {
    void* lock;
    INT32 size;
    INT32 capacity;
    INT32 readIndex;
    INT32 writeIndex;
    MidiMessage queue[1];
} MidiMessageQueue;
#endif

// device handle, to be created and filled in MIDI_IN_OpenDevice() and MIDI_OUT_OpenDevice()
typedef struct tag_MidiDeviceHandle {
    void* deviceHandle;      // handle to the device
    void* longBuffers;       // contains platform-specific data for long buffers, e.g. list of MIDIHDR
    void* platformData;      // contains platform specific data, e.g. an Event object
    INT32 isWaiting;         // if TRUE, then waiting for new events
    INT64 startTime;         // start time
#if USE_MIDI_QUEUE == TRUE
    MidiMessageQueue* queue; // may be NULL if no queue is used
#endif
} MidiDeviceHandle;


#if USE_MIDI_QUEUE == TRUE

/*
 * Native Locking support
 */
void* MIDI_CreateLock();
void MIDI_DestroyLock(void* lock);

/* Blocks until this lock can be gotten.
 * Nop if lock is NULL */
void MIDI_Lock(void* lock);

/* Releases this lock */
void MIDI_Unlock(void* lock);

MidiMessageQueue* MIDI_CreateQueue(int capacity);
void MIDI_DestroyQueue(MidiMessageQueue* queue);
// if overwrite is true, oldest messages will be overwritten when the queue is full
// returns true, if message has been added
int MIDI_QueueAddShort(MidiMessageQueue* queue, UINT32 packedMsg, INT64 timestamp, int overwrite);
int MIDI_QueueAddLong(MidiMessageQueue* queue, UBYTE* data, UINT32 size,
                      INT32 sysexIndex, INT64 timestamp, int overwrite);

// returns NULL if no messages in queue.
MidiMessage* MIDI_QueueRead(MidiMessageQueue* queue);
// message will be removed from queue.
void MIDI_QueueRemove(MidiMessageQueue* queue, INT32 onlyLocked);
void MIDI_QueueClear(MidiMessageQueue* queue);

#endif /* USE_MIDI_QUEUE */


/*
 * Platform MIDI IN support.
 * deviceId:            device-by-number
 * deviceHandle:        native device handle
 */

#if USE_PLATFORM_MIDI_IN == TRUE

// number of messages to be buffered
#define MIDI_IN_MESSAGE_QUEUE_SIZE 64
// number of sysex to be buffered
#define MIDI_IN_LONG_QUEUE_SIZE 20
// maximum number of bytes in one sys ex message
#define MIDI_IN_LONG_MESSAGE_SIZE 1024


/*
 * Return an error message for the error code
 */
char* MIDI_IN_GetErrorStr(INT32 err);


/*
 * Get the number of MIDI IN devices on the system.
 */
INT32 MIDI_IN_GetNumDevices();

/*
 * Get the name of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_GetDeviceName(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Get the vendor of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_GetDeviceVendor(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Get the description of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_GetDeviceDescription(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Get the version of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_GetDeviceVersion(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Open the device with this id.
 * Returns a device handle in handle*.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_OpenDevice(INT32 deviceID, MidiDeviceHandle** handle);

/*
 * Close the device handle.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_CloseDevice(MidiDeviceHandle* handle);

/*
 * Start the device with this handle.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_StartDevice(MidiDeviceHandle* handle);

/*
 * Stop the device with this handle.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_IN_StopDevice(MidiDeviceHandle* handle);

/*
 * Return the current time stamp in microseconds.
 * If not supported, or problem occurred, returns -1
 */
INT64 MIDI_IN_GetTimeStamp(MidiDeviceHandle* handle);

/*
 * Get the next message from the queue.
 * This call blocks until the device is stopped
 * or a message is received.
 * The returned message is READ ONLY.
 * The message will be returned into the message
 * queue by calling MIDI_IN_ReleaseMessage.
 */
MidiMessage* MIDI_IN_GetMessage(MidiDeviceHandle* handle);

/*
 * Put a message, which was taken
 * out of the queue, back into the queue.
 */
void MIDI_IN_ReleaseMessage(MidiDeviceHandle* handle, MidiMessage* msg);

#endif // USE_PLATFORM_MIDI_IN


/*
 * Platform MIDI OUT support.
 * deviceId:            device-by-number
 * deviceHandle:        native device handle
 */

#if USE_PLATFORM_MIDI_OUT == TRUE

// number of messages to be buffered
#define MIDI_OUT_MESSAGE_QUEUE_SIZE 32
// number of sysex to be buffered
#define MIDI_OUT_LONG_QUEUE_SIZE 16
// maximum number of bytes in one sys ex message
#define MIDI_OUT_LONG_MESSAGE_SIZE 1024

/*
 * Return an error message for the error code
 */
char* MIDI_OUT_GetErrorStr(INT32 err);


/*
 * Get the number of MIDI OUT devices on the system.
 */
INT32 MIDI_OUT_GetNumDevices();

/*
 * Get the name of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_GetDeviceName(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Get the vendor of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_GetDeviceVendor(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Get the description of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_GetDeviceDescription(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Get the version of the device with this id
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_GetDeviceVersion(INT32 deviceID, char *name, UINT32 nameLength);

/*
 * Open the device with this id.
 * Returns a device handle in handle*.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_OpenDevice(INT32 deviceID, MidiDeviceHandle** handle);

/*
 * Close the device handle.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_CloseDevice(MidiDeviceHandle* handle);

/*
 * Return the current time stamp in microseconds (the time since the device
 * was opened).
 * If not supported, or problem occurred, returns -1
 */
INT64 MIDI_OUT_GetTimeStamp(MidiDeviceHandle* handle);

/*
 * Send a short message to the hardware.
 * packedMsg: (status | data1<<8 | data2<<16) in platform-endianness
 * Timestamp is in microseconds.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_SendShortMessage(MidiDeviceHandle* handle, UINT32 packedMsg, UINT32 timestamp);

/*
 * Send a long message to the hardware.  Timestamp is in microseconds.
 * This blocks until a slot to send a message is free.
 * Returns MIDI_SUCCESS or an error code
 */
INT32 MIDI_OUT_SendLongMessage(MidiDeviceHandle* handle, UBYTE* data, UINT32 size, UINT32 timestamp);

#endif // USE_PLATFORM_MIDI_OUT

#endif // PLATFORM_MIDI_INCLUDED