354 lines
14 KiB
C
354 lines
14 KiB
C
/*
|
|
* Copyright (C) 2018 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
/**
|
|
* @addtogroup Midi
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @file AMidi.h
|
|
*/
|
|
|
|
#ifndef ANDROID_MEDIA_AMIDI_H_
|
|
#define ANDROID_MEDIA_AMIDI_H_
|
|
|
|
#include <stdarg.h>
|
|
#include <stdint.h>
|
|
#include <sys/types.h>
|
|
|
|
#include <jni.h>
|
|
|
|
#include <media/NdkMediaError.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#define AMIDI_API __attribute__((visibility("default")))
|
|
|
|
typedef struct AMidiDevice AMidiDevice;
|
|
typedef struct AMidiInputPort AMidiInputPort;
|
|
typedef struct AMidiOutputPort AMidiOutputPort;
|
|
|
|
/*
|
|
* Message Op Codes. Used to parse MIDI data packets
|
|
*/
|
|
enum {
|
|
AMIDI_OPCODE_DATA = 1, /* The MIDI packet contains normal MIDI data */
|
|
AMIDI_OPCODE_FLUSH = 2, /* The MIDI packet contains just a MIDI FLUSH command. */
|
|
/* Forces the send of any pending MIDI data. */
|
|
};
|
|
|
|
/*
|
|
* Type IDs for various MIDI devices.
|
|
*/
|
|
enum {
|
|
AMIDI_DEVICE_TYPE_USB = 1, /* A MIDI device connected to the Android USB port */
|
|
AMIDI_DEVICE_TYPE_VIRTUAL = 2, /* A software object implementing MidiDeviceService */
|
|
AMIDI_DEVICE_TYPE_BLUETOOTH = 3 /* A MIDI device connected via BlueTooth */
|
|
};
|
|
|
|
/*
|
|
* Protocol IDs for various MIDI devices.
|
|
*
|
|
* Introduced in API 33.
|
|
*/
|
|
enum AMidiDevice_Protocol : int32_t {
|
|
/**
|
|
* Constant representing a default protocol with Universal MIDI Packets (UMP).
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* All UMP data should be a multiple of 4 bytes.
|
|
* Use UMP to negotiate with the device with MIDI-CI.
|
|
* MIDI-CI is defined in "MIDI Capability Inquiry (MIDI-CI)" spec.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UMP_USE_MIDI_CI = 0,
|
|
|
|
/**
|
|
* Constant representing a default protocol with Universal MIDI Packets (UMP).
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* All UMP data should be a multiple of 4 bytes.
|
|
* Use MIDI 1.0 through UMP with packet sizes up to 64 bits.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_64_BITS = 1,
|
|
|
|
/**
|
|
* Constant representing a default protocol with Universal MIDI Packets (UMP).
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* All UMP data should be a multiple of 4 bytes.
|
|
* Use MIDI 1.0 through UMP with packet sizes up to 64 bits and jitter reduction timestamps.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_64_BITS_AND_JRTS = 2,
|
|
|
|
/**
|
|
* Constant representing a default protocol with Universal MIDI Packets (UMP).
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* All UMP data should be a multiple of 4 bytes.
|
|
* Use MIDI 1.0 through UMP with packet sizes up to 128 bits.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_128_BITS = 3,
|
|
|
|
/**
|
|
* Constant representing a default protocol with Universal MIDI Packets (UMP).
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* All UMP data should be a multiple of 4 bytes.
|
|
* Use MIDI 1.0 through UMP with packet sizes up to 128 bits and jitter reduction timestamps.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_128_BITS_AND_JRTS = 4,
|
|
|
|
/**
|
|
* Constant representing a default protocol with Universal MIDI Packets (UMP).
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* All UMP data should be a multiple of 4 bytes.
|
|
* Use MIDI 2.0 through UMP.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UMP_MIDI_2_0 = 17,
|
|
|
|
/**
|
|
* Constant representing a default protocol with Universal MIDI Packets (UMP).
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* All UMP data should be a multiple of 4 bytes.
|
|
* Use MIDI 2.0 through UMP and jitter reduction timestamps.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UMP_MIDI_2_0_AND_JRTS = 18,
|
|
|
|
/**
|
|
* Constant representing a device with an unknown default protocol.
|
|
* If Universal MIDI Packets (UMP) are needed, use MIDI-CI through MIDI 1.0.
|
|
* UMP is defined in "Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol" spec.
|
|
* MIDI-CI is defined in "MIDI Capability Inquiry (MIDI-CI)" spec.
|
|
*/
|
|
AMIDI_DEVICE_PROTOCOL_UNKNOWN = -1
|
|
};
|
|
|
|
/*
|
|
* Device API
|
|
*/
|
|
/**
|
|
* Connects a native Midi Device object to the associated Java MidiDevice object. Use this
|
|
* AMidiDevice to access the rest of the native MIDI API. Use AMidiDevice_release() to
|
|
* disconnect from the Java object when not being used any more.
|
|
*
|
|
* @param env Points to the Java Environment.
|
|
* @param midiDeviceObj The Java MidiDevice Object.
|
|
* @param outDevicePtrPtr Points to the pointer to receive the AMidiDevice
|
|
*
|
|
* @return AMEDIA_OK on success, or a negative error value:
|
|
* @see AMEDIA_ERROR_INVALID_OBJECT - the midiDeviceObj
|
|
* is null or already connected to a native AMidiDevice
|
|
* @see AMEDIA_ERROR_UNKNOWN - an unknown error occurred.
|
|
*/
|
|
media_status_t AMIDI_API AMidiDevice_fromJava(
|
|
JNIEnv *env, jobject midiDeviceObj, AMidiDevice **outDevicePtrPtr) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Disconnects the native Midi Device Object from the associated Java MidiDevice object.
|
|
*
|
|
* @param midiDevice Points to the native AMIDI_MidiDevice.
|
|
*
|
|
* @return AMEDIA_OK on success,
|
|
* or a negative error value:
|
|
* @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL.
|
|
* @see AMEDIA_ERROR_INVALID_OBJECT - the device is not consistent with the associated Java MidiDevice.
|
|
* @see AMEDIA_ERROR_INVALID_OBJECT - the JNI interface initialization to the associated java MidiDevice failed.
|
|
* @see AMEDIA_ERROR_UNKNOWN - couldn't retrieve the device info.
|
|
*/
|
|
media_status_t AMIDI_API AMidiDevice_release(const AMidiDevice *midiDevice) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Gets the MIDI device type.
|
|
*
|
|
* @param device Specifies the MIDI device.
|
|
*
|
|
* @return The identifier of the MIDI device type:
|
|
* AMIDI_DEVICE_TYPE_USB
|
|
* AMIDI_DEVICE_TYPE_VIRTUAL
|
|
* AMIDI_DEVICE_TYPE_BLUETOOTH
|
|
* or a negative error value:
|
|
* @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL.
|
|
* @see AMEDIA_ERROR_UNKNOWN - Unknown error.
|
|
*/
|
|
int32_t AMIDI_API AMidiDevice_getType(const AMidiDevice *device) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Gets the number of input (sending) ports available on the specified MIDI device.
|
|
*
|
|
* @param device Specifies the MIDI device.
|
|
*
|
|
* @return If successful, returns the number of MIDI input (sending) ports available on the
|
|
* device. If an error occurs, returns a negative value indicating the error:
|
|
* @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL.
|
|
* @see AMEDIA_ERROR_UNKNOWN - couldn't retrieve the device info.
|
|
*/
|
|
ssize_t AMIDI_API AMidiDevice_getNumInputPorts(const AMidiDevice *device) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Gets the number of output (receiving) ports available on the specified MIDI device.
|
|
*
|
|
* @param device Specifies the MIDI device.
|
|
*
|
|
* @return If successful, returns the number of MIDI output (receiving) ports available on the
|
|
* device. If an error occurs, returns a negative value indicating the error:
|
|
* @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL.
|
|
* @see AMEDIA_ERROR_UNKNOWN - couldn't retrieve the device info.
|
|
*/
|
|
ssize_t AMIDI_API AMidiDevice_getNumOutputPorts(const AMidiDevice *device) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Gets the MIDI device default protocol.
|
|
*
|
|
* @param device Specifies the MIDI device.
|
|
*
|
|
* @return The identifier of the MIDI device default protocol:
|
|
* AMIDI_DEVICE_PROTOCOL_UMP_USE_MIDI_CI
|
|
* AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_64_BITS
|
|
* AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_64_BITS_AND_JRTS
|
|
* AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_128_BITS
|
|
* AMIDI_DEVICE_PROTOCOL_UMP_MIDI_1_0_UP_TO_128_BITS_AND_JRTS
|
|
* AMIDI_DEVICE_PROTOCOL_UMP_MIDI_2_0
|
|
* AMIDI_DEVICE_PROTOCOL_UMP_MIDI_2_0_AND_JRTS
|
|
* AMIDI_DEVICE_PROTOCOL_UNKNOWN
|
|
*
|
|
* Most devices should return PROTOCOL_UNKNOWN (-1). This is intentional as devices
|
|
* with default UMP support are not backwards compatible. When the device is null,
|
|
* return AMIDI_DEVICE_PROTOCOL_UNKNOWN.
|
|
*
|
|
* Available since API 33.
|
|
*/
|
|
AMidiDevice_Protocol AMIDI_API AMidiDevice_getDefaultProtocol(const AMidiDevice *device)
|
|
__INTRODUCED_IN(33);
|
|
|
|
/*
|
|
* API for receiving data from the Output port of a device.
|
|
*/
|
|
/**
|
|
* Opens the output port so that the client can receive data from it. The port remains open and
|
|
* valid until AMidiOutputPort_close() is called for the returned AMidiOutputPort.
|
|
*
|
|
* @param device Specifies the MIDI device.
|
|
* @param portNumber Specifies the zero-based port index on the device to open. This value ranges
|
|
* between 0 and one less than the number of output ports reported by the
|
|
* AMidiDevice_getNumOutputPorts function.
|
|
* @param outOutputPortPtr Receives the native API port identifier of the opened port.
|
|
*
|
|
* @return AMEDIA_OK, or a negative error code:
|
|
* @see AMEDIA_ERROR_UNKNOWN - Unknown Error.
|
|
*/
|
|
media_status_t AMIDI_API AMidiOutputPort_open(const AMidiDevice *device, int32_t portNumber,
|
|
AMidiOutputPort **outOutputPortPtr) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Closes the output port.
|
|
*
|
|
* @param outputPort The native API port identifier of the port.
|
|
*/
|
|
void AMIDI_API AMidiOutputPort_close(const AMidiOutputPort *outputPort) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Receives the next pending MIDI message. To retrieve all pending messages, the client should
|
|
* repeatedly call this method until it returns 0.
|
|
*
|
|
* Note that this is a non-blocking call. If there are no Midi messages are available, the function
|
|
* returns 0 immediately (for 0 messages received).
|
|
*
|
|
* @param outputPort Identifies the port to receive messages from.
|
|
* @param opcodePtr Receives the message Op Code.
|
|
* @param buffer Points to the buffer to receive the message data bytes.
|
|
* @param maxBytes Specifies the size of the buffer pointed to by the buffer parameter.
|
|
* @param numBytesReceivedPtr On exit, receives the actual number of bytes stored in buffer.
|
|
* @param outTimestampPtr If non-NULL, receives the timestamp associated with the message.
|
|
* (the current value of the running Java Virtual Machine's high-resolution time source,
|
|
* in nanoseconds)
|
|
* @return the number of messages received (either 0 or 1), or a negative error code:
|
|
* @see AMEDIA_ERROR_UNKNOWN - Unknown Error.
|
|
*/
|
|
ssize_t AMIDI_API AMidiOutputPort_receive(const AMidiOutputPort *outputPort, int32_t *opcodePtr,
|
|
uint8_t *buffer, size_t maxBytes, size_t* numBytesReceivedPtr, int64_t *outTimestampPtr) __INTRODUCED_IN(29);
|
|
|
|
/*
|
|
* API for sending data to the Input port of a device.
|
|
*/
|
|
/**
|
|
* Opens the input port so that the client can send data to it. The port remains open and
|
|
* valid until AMidiInputPort_close() is called for the returned AMidiInputPort.
|
|
*
|
|
* @param device Specifies the MIDI device.
|
|
* @param portNumber Specifies the zero-based port index on the device to open. This value ranges
|
|
* between 0 and one less than the number of input ports reported by the
|
|
* AMidiDevice_getNumInputPorts() function..
|
|
* @param outInputPortPtr Receives the native API port identifier of the opened port.
|
|
*
|
|
* @return AMEDIA_OK, or a negative error code:
|
|
* @see AMEDIA_ERROR_UNKNOWN - Unknown Error.
|
|
*/
|
|
media_status_t AMIDI_API AMidiInputPort_open(const AMidiDevice *device, int32_t portNumber,
|
|
AMidiInputPort **outInputPortPtr) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Sends data to the specified input port.
|
|
*
|
|
* @param inputPort The identifier of the port to send data to.
|
|
* @param buffer Points to the array of bytes containing the data to send.
|
|
* @param numBytes Specifies the number of bytes to write.
|
|
*
|
|
* @return The number of bytes sent, which could be less than specified or a negative error code:
|
|
* @see AMEDIA_ERROR_INVALID_PARAMETER - The specified port was NULL, the specified buffer was NULL.
|
|
*/
|
|
ssize_t AMIDI_API AMidiInputPort_send(const AMidiInputPort *inputPort, const uint8_t *buffer,
|
|
size_t numBytes) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Sends data to the specified input port with a timestamp.
|
|
*
|
|
* @param inputPort The identifier of the port to send data to.
|
|
* @param buffer Points to the array of bytes containing the data to send.
|
|
* @param numBytes Specifies the number of bytes to write.
|
|
* @param timestamp The CLOCK_MONOTONIC time in nanoseconds to associate with the sent data.
|
|
*
|
|
* @return The number of bytes sent, which could be less than specified or a negative error code:
|
|
* @see AMEDIA_ERROR_INVALID_PARAMETER - The specified port was NULL, the specified buffer was NULL.
|
|
*/
|
|
ssize_t AMIDI_API AMidiInputPort_sendWithTimestamp(const AMidiInputPort *inputPort,
|
|
const uint8_t *buffer, size_t numBytes, int64_t timestamp) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Sends a message with a 'MIDI flush command code' to the specified port. This should cause
|
|
* a receiver to discard any pending MIDI data it may have accumulated and not processed.
|
|
*
|
|
* @param inputPort The identifier of the port to send the flush command to.
|
|
*
|
|
* @returns @see AMEDIA_OK if successful, otherwise a negative error code:
|
|
* @see AMEDIA_ERROR_INVALID_PARAMETER - The specified port was NULL
|
|
* @see AMEDIA_ERROR_UNSUPPORTED - The FLUSH command couldn't
|
|
* be sent.
|
|
*/
|
|
media_status_t AMIDI_API AMidiInputPort_sendFlush(const AMidiInputPort *inputPort) __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* Closes the input port.
|
|
*
|
|
* @param inputPort Identifies the input (sending) port to close.
|
|
*/
|
|
void AMIDI_API AMidiInputPort_close(const AMidiInputPort *inputPort) __INTRODUCED_IN(29);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* ANDROID_MEDIA_AMIDI_H_ */
|
|
/**
|
|
@}
|
|
*/
|