diff options
Diffstat (limited to 'media/native/midi/include/midi.h')
| -rw-r--r-- | media/native/midi/include/midi.h | 255 |
1 files changed, 255 insertions, 0 deletions
diff --git a/media/native/midi/include/midi.h b/media/native/midi/include/midi.h new file mode 100644 index 000000000000..780d8a7bfd40 --- /dev/null +++ b/media/native/midi/include/midi.h @@ -0,0 +1,255 @@ +/* + * 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. + */ + +#ifndef ANDROID_MEDIA_MIDI_H_ +#define ANDROID_MEDIA_MIDI_H_ + +#include <stdarg.h> +#include <stdint.h> +#include <sys/types.h> + +#include <jni.h> + +#include <media/NdkMediaError.h> + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct AMidiDevice AMidiDevice; +typedef struct AMidiInputPort AMidiInputPort; +typedef struct AMidiOutputPort AMidiOutputPort; + +#define AMIDI_API __attribute__((visibility("default"))) + +/* + * 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 */ +}; + +/* + * 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 {@link AMEDIA_ERROR_INVALID_OBJECT} - the midiDeviceObj + * is null or already connected to a native AMidiDevice + * @see AMEDIA_ERROR_UNKNOWN {@link AMEDIA_ERROR_UNKNOWN} - an unknown error occurred. + */ +media_status_t AMIDI_API AMidiDevice_fromJava( + JNIEnv *env, jobject midiDeviceObj, AMidiDevice **outDevicePtrPtr); + +/** + * 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 {@link AMEDIA_ERROR_INVALID_PARAMETER} + * - the device parameter is NULL. + * @see AMEDIA_ERROR_INVALID_OBJECT {@link AMEDIA_ERROR_INVALID_OBJECT} + * - the device is not consistent with the associated Java MidiDevice. + * @see AMEDIA_ERROR_INVALID_OBJECT {@link AMEDIA_ERROR_INVALID_OBJECT} + * - the JNI interface initialization to the associated java MidiDevice failed. + * @see AMEDIA_ERROR_UNKNOWN {@link AMEDIA_ERROR_UNKNOWN} - couldn't retrieve the device info. + */ +media_status_t AMIDI_API AMidiDevice_release(const AMidiDevice *midiDevice); + +/** + * 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 {@link AMEDIA_ERROR_INVALID_PARAMETER} - the device + * parameter is NULL. + * @see AMEDIA_ERROR_UNKNOWN {@link AMEDIA_ERROR_UNKNOWN} - Unknown error. + */ +int32_t AMIDI_API AMidiDevice_getType(const AMidiDevice *device); + +/** + * 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 {@link AMEDIA_ERROR_INVALID_PARAMETER} - the device + * parameter is NULL. + * @see AMEDIA_ERROR_UNKNOWN {@link AMEDIA_ERROR_UNKNOWN} - couldn't retrieve the device info. + */ +ssize_t AMIDI_API AMidiDevice_getNumInputPorts(const AMidiDevice *device); + +/** + * 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 {@link AMEDIA_ERROR_INVALID_PARAMETER} - the device + * parameter is NULL. + * @see AMEDIA_ERROR_UNKNOWN {@link AMEDIA_ERROR_UNKNOWN}- couldn't retrieve the device info. + */ +ssize_t AMIDI_API AMidiDevice_getNumOutputPorts(const AMidiDevice *device); + +/* + * 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 {@link AMEDIA_ERROR_UNKNOWN} - Unknown Error. + */ +media_status_t AMIDI_API AMidiOutputPort_open(const AMidiDevice *device, int32_t portNumber, + AMidiOutputPort **outOutputPortPtr); + +/** + * Closes the output port. + * + * @param outputPort The native API port identifier of the port. + */ +void AMIDI_API AMidiOutputPort_close(const AMidiOutputPort *outputPort); + +/** + * 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 {@link 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); + +/* + * 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 {@link AMEDIA_ERROR_UNKNOWN} - Unknown Error. + */ +media_status_t AMIDI_API AMidiInputPort_open(const AMidiDevice *device, int32_t portNumber, + AMidiInputPort **outInputPortPtr); + +/** + * 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 {@link 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); + +/** + * 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 {@link 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); + +/** + * 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 {@link AMEDIA_OK} if successful, otherwise a negative error code: + * @see AMEDIA_ERROR_INVALID_PARAMETER {@link AMEDIA_ERROR_INVALID_PARAMETER} The specified port + * was NULL + * @see AMEDIA_ERROR_UNSUPPORTED {@link AMEDIA_ERROR_UNSUPPORTED} The FLUSH command couldn't + * be sent. + */ +media_status_t AMIDI_API AMidiInputPort_sendFlush(const AMidiInputPort *inputPort); + +/** + * Closes the input port. + * + * @param inputPort Identifies the input (sending) port to close. + */ +void AMIDI_API AMidiInputPort_close(const AMidiInputPort *inputPort); + +#ifdef __cplusplus +} +#endif + +#endif /* ANDROID_MEDIA_MIDI_H_ */ |