1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 /** 17 * @addtogroup Midi 18 * @{ 19 */ 20 21 /** 22 * @file AMidi.h 23 */ 24 25 #ifndef ANDROID_MEDIA_AMIDI_H_ 26 #define ANDROID_MEDIA_AMIDI_H_ 27 28 #include <stdarg.h> 29 #include <stdint.h> 30 #include <sys/types.h> 31 32 #include <jni.h> 33 34 #include <media/NdkMediaError.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 #define AMIDI_API __attribute__((visibility("default"))) 41 42 typedef struct AMidiDevice AMidiDevice; 43 typedef struct AMidiInputPort AMidiInputPort; 44 typedef struct AMidiOutputPort AMidiOutputPort; 45 46 /* 47 * Message Op Codes. Used to parse MIDI data packets 48 */ 49 enum { 50 AMIDI_OPCODE_DATA = 1, /* The MIDI packet contains normal MIDI data */ 51 AMIDI_OPCODE_FLUSH = 2, /* The MIDI packet contains just a MIDI FLUSH command. */ 52 /* Forces the send of any pending MIDI data. */ 53 }; 54 55 /* 56 * Type IDs for various MIDI devices. 57 */ 58 enum { 59 AMIDI_DEVICE_TYPE_USB = 1, /* A MIDI device connected to the Android USB port */ 60 AMIDI_DEVICE_TYPE_VIRTUAL = 2, /* A software object implementing MidiDeviceService */ 61 AMIDI_DEVICE_TYPE_BLUETOOTH = 3 /* A MIDI device connected via BlueTooth */ 62 }; 63 64 /* 65 * Device API 66 */ 67 /** 68 * Connects a native Midi Device object to the associated Java MidiDevice object. Use this 69 * AMidiDevice to access the rest of the native MIDI API. Use AMidiDevice_release() to 70 * disconnect from the Java object when not being used any more. 71 * 72 * @param env Points to the Java Environment. 73 * @param midiDeviceObj The Java MidiDevice Object. 74 * @param outDevicePtrPtr Points to the pointer to receive the AMidiDevice 75 * 76 * @return AMEDIA_OK on success, or a negative error value: 77 * @see AMEDIA_ERROR_INVALID_OBJECT - the midiDeviceObj 78 * is null or already connected to a native AMidiDevice 79 * @see AMEDIA_ERROR_UNKNOWN - an unknown error occurred. 80 */ 81 media_status_t AMIDI_API AMidiDevice_fromJava( 82 JNIEnv *env, jobject midiDeviceObj, AMidiDevice **outDevicePtrPtr) __INTRODUCED_IN(29); 83 84 /** 85 * Disconnects the native Midi Device Object from the associated Java MidiDevice object. 86 * 87 * @param midiDevice Points to the native AMIDI_MidiDevice. 88 * 89 * @return AMEDIA_OK on success, 90 * or a negative error value: 91 * @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL. 92 * @see AMEDIA_ERROR_INVALID_OBJECT - the device is not consistent with the associated Java MidiDevice. 93 * @see AMEDIA_ERROR_INVALID_OBJECT - the JNI interface initialization to the associated java MidiDevice failed. 94 * @see AMEDIA_ERROR_UNKNOWN - couldn't retrieve the device info. 95 */ 96 media_status_t AMIDI_API AMidiDevice_release(const AMidiDevice *midiDevice) __INTRODUCED_IN(29); 97 98 /** 99 * Gets the MIDI device type. 100 * 101 * @param device Specifies the MIDI device. 102 * 103 * @return The identifier of the MIDI device type: 104 * AMIDI_DEVICE_TYPE_USB 105 * AMIDI_DEVICE_TYPE_VIRTUAL 106 * AMIDI_DEVICE_TYPE_BLUETOOTH 107 * or a negative error value: 108 * @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL. 109 * @see AMEDIA_ERROR_UNKNOWN - Unknown error. 110 */ 111 int32_t AMIDI_API AMidiDevice_getType(const AMidiDevice *device) __INTRODUCED_IN(29); 112 113 /** 114 * Gets the number of input (sending) ports available on the specified MIDI device. 115 * 116 * @param device Specifies the MIDI device. 117 * 118 * @return If successful, returns the number of MIDI input (sending) ports available on the 119 * device. If an error occurs, returns a negative value indicating the error: 120 * @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL. 121 * @see AMEDIA_ERROR_UNKNOWN - couldn't retrieve the device info. 122 */ 123 ssize_t AMIDI_API AMidiDevice_getNumInputPorts(const AMidiDevice *device) __INTRODUCED_IN(29); 124 125 /** 126 * Gets the number of output (receiving) ports available on the specified MIDI device. 127 * 128 * @param device Specifies the MIDI device. 129 * 130 * @return If successful, returns the number of MIDI output (receiving) ports available on the 131 * device. If an error occurs, returns a negative value indicating the error: 132 * @see AMEDIA_ERROR_INVALID_PARAMETER - the device parameter is NULL. 133 * @see AMEDIA_ERROR_UNKNOWN - couldn't retrieve the device info. 134 */ 135 ssize_t AMIDI_API AMidiDevice_getNumOutputPorts(const AMidiDevice *device) __INTRODUCED_IN(29); 136 137 /* 138 * API for receiving data from the Output port of a device. 139 */ 140 /** 141 * Opens the output port so that the client can receive data from it. The port remains open and 142 * valid until AMidiOutputPort_close() is called for the returned AMidiOutputPort. 143 * 144 * @param device Specifies the MIDI device. 145 * @param portNumber Specifies the zero-based port index on the device to open. This value ranges 146 * between 0 and one less than the number of output ports reported by the 147 * AMidiDevice_getNumOutputPorts function. 148 * @param outOutputPortPtr Receives the native API port identifier of the opened port. 149 * 150 * @return AMEDIA_OK, or a negative error code: 151 * @see AMEDIA_ERROR_UNKNOWN - Unknown Error. 152 */ 153 media_status_t AMIDI_API AMidiOutputPort_open(const AMidiDevice *device, int32_t portNumber, 154 AMidiOutputPort **outOutputPortPtr) __INTRODUCED_IN(29); 155 156 /** 157 * Closes the output port. 158 * 159 * @param outputPort The native API port identifier of the port. 160 */ 161 void AMIDI_API AMidiOutputPort_close(const AMidiOutputPort *outputPort) __INTRODUCED_IN(29); 162 163 /** 164 * Receives the next pending MIDI message. To retrieve all pending messages, the client should 165 * repeatedly call this method until it returns 0. 166 * 167 * Note that this is a non-blocking call. If there are no Midi messages are available, the function 168 * returns 0 immediately (for 0 messages received). 169 * 170 * @param outputPort Identifies the port to receive messages from. 171 * @param opcodePtr Receives the message Op Code. 172 * @param buffer Points to the buffer to receive the message data bytes. 173 * @param maxBytes Specifies the size of the buffer pointed to by the buffer parameter. 174 * @param numBytesReceivedPtr On exit, receives the actual number of bytes stored in buffer. 175 * @param outTimestampPtr If non-NULL, receives the timestamp associated with the message. 176 * (the current value of the running Java Virtual Machine's high-resolution time source, 177 * in nanoseconds) 178 * @return the number of messages received (either 0 or 1), or a negative error code: 179 * @see AMEDIA_ERROR_UNKNOWN - Unknown Error. 180 */ 181 ssize_t AMIDI_API AMidiOutputPort_receive(const AMidiOutputPort *outputPort, int32_t *opcodePtr, 182 uint8_t *buffer, size_t maxBytes, size_t* numBytesReceivedPtr, int64_t *outTimestampPtr) __INTRODUCED_IN(29); 183 184 /* 185 * API for sending data to the Input port of a device. 186 */ 187 /** 188 * Opens the input port so that the client can send data to it. The port remains open and 189 * valid until AMidiInputPort_close() is called for the returned AMidiInputPort. 190 * 191 * @param device Specifies the MIDI device. 192 * @param portNumber Specifies the zero-based port index on the device to open. This value ranges 193 * between 0 and one less than the number of input ports reported by the 194 * AMidiDevice_getNumInputPorts() function.. 195 * @param outInputPortPtr Receives the native API port identifier of the opened port. 196 * 197 * @return AMEDIA_OK, or a negative error code: 198 * @see AMEDIA_ERROR_UNKNOWN - Unknown Error. 199 */ 200 media_status_t AMIDI_API AMidiInputPort_open(const AMidiDevice *device, int32_t portNumber, 201 AMidiInputPort **outInputPortPtr) __INTRODUCED_IN(29); 202 203 /** 204 * Sends data to the specified input port. 205 * 206 * @param inputPort The identifier of the port to send data to. 207 * @param buffer Points to the array of bytes containing the data to send. 208 * @param numBytes Specifies the number of bytes to write. 209 * 210 * @return The number of bytes sent, which could be less than specified or a negative error code: 211 * @see AMEDIA_ERROR_INVALID_PARAMETER - The specified port was NULL, the specified buffer was NULL. 212 */ 213 ssize_t AMIDI_API AMidiInputPort_send(const AMidiInputPort *inputPort, const uint8_t *buffer, 214 size_t numBytes) __INTRODUCED_IN(29); 215 216 /** 217 * Sends data to the specified input port with a timestamp. 218 * 219 * @param inputPort The identifier of the port to send data to. 220 * @param buffer Points to the array of bytes containing the data to send. 221 * @param numBytes Specifies the number of bytes to write. 222 * @param timestamp The CLOCK_MONOTONIC time in nanoseconds to associate with the sent data. 223 * 224 * @return The number of bytes sent, which could be less than specified or a negative error code: 225 * @see AMEDIA_ERROR_INVALID_PARAMETER - The specified port was NULL, the specified buffer was NULL. 226 */ 227 ssize_t AMIDI_API AMidiInputPort_sendWithTimestamp(const AMidiInputPort *inputPort, 228 const uint8_t *buffer, size_t numBytes, int64_t timestamp) __INTRODUCED_IN(29); 229 230 /** 231 * Sends a message with a 'MIDI flush command code' to the specified port. This should cause 232 * a receiver to discard any pending MIDI data it may have accumulated and not processed. 233 * 234 * @param inputPort The identifier of the port to send the flush command to. 235 * 236 * @returns @see AMEDIA_OK if successful, otherwise a negative error code: 237 * @see AMEDIA_ERROR_INVALID_PARAMETER - The specified port was NULL 238 * @see AMEDIA_ERROR_UNSUPPORTED - The FLUSH command couldn't 239 * be sent. 240 */ 241 media_status_t AMIDI_API AMidiInputPort_sendFlush(const AMidiInputPort *inputPort) __INTRODUCED_IN(29); 242 243 /** 244 * Closes the input port. 245 * 246 * @param inputPort Identifies the input (sending) port to close. 247 */ 248 void AMIDI_API AMidiInputPort_close(const AMidiInputPort *inputPort) __INTRODUCED_IN(29); 249 250 #ifdef __cplusplus 251 } 252 #endif 253 254 #endif /* ANDROID_MEDIA_AMIDI_H_ */ 255 /** 256 @} 257 */ 258