midi.h revision c276c59eb5d0f36a1133ad718e5e1244390f4688 
1/*
2 * Copyright (C) 2017 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#ifndef ANDROID_MEDIA_MIDI_H_
18#define ANDROID_MEDIA_MIDI_H_
19
20#include <stdarg.h>
21#include <stdint.h>
22#include <sys/types.h>
23
24#include <utils/Errors.h>
25
26using android::status_t;
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32//typedef struct _AMIDI_Device;
33//typedef struct _AMIDI_InputPort;
34//typedef struct _AMIDI_OutputPort;
35//typedef _AMIDI_Device*      AMIDI_Device;
36//typedef _AMIDI_InputPort*   AMIDI_InputPort;
37//typedef _AMIDI_OutputPort*  AMIDI_OutputPort;
38
39typedef int32_t AMIDI_Device;
40typedef int32_t AMIDI_InputPort;
41typedef int32_t  AMIDI_OutputPort;
42
43//TODO - Do we want to wrap this stuff in namespace android { namespace media { namespace midi {?
44
45enum {
46    AMIDI_INVALID_HANDLE = -1
47};
48
49enum {
50    AMIDI_OPCODE_DATA = 1,
51    AMIDI_OPCODE_FLUSH = 2,
52    AMIDI_PACKET_SIZE = 1024,  /* !!! Currently MidiPortImpl.MAX_PACKET_SIZE !!! */
53    AMIDI_PACKET_OVERHEAD = 9,
54    AMIDI_BUFFER_SIZE = AMIDI_PACKET_SIZE - AMIDI_PACKET_OVERHEAD
55            /* !!! TBD, currently MidiPortImpl.MAX_PACKET_DATA_SIZE !!! */
56};
57
58typedef struct {
59    uint32_t opcode;
60    uint8_t buffer[AMIDI_BUFFER_SIZE];
61    size_t len;
62    int64_t timestamp;
63} AMIDI_Message;
64
65enum {
66    AMIDI_DEVICE_TYPE_USB = 1,
67    AMIDI_DEVICE_TYPE_VIRTUAL = 2,
68    AMIDI_DEVICE_TYPE_BLUETOOTH = 3
69};
70
71typedef struct {
72    int32_t type;
73    int32_t uid;
74    int32_t isPrivate;
75    int32_t inputPortCount;
76    int32_t outputPortCount;
77} AMIDI_DeviceInfo;
78
79/*
80 * Device API
81 */
82/*
83 * Retrieves the native API device token for the specified Java API device ID.
84 *
85 * uid          The Java API id of the device.
86 * devicePtr    Receives the associated native API token for the device.
87 *
88 * Returns OK or a (negative) error code.
89 */
90status_t AMIDI_getDeviceById(int32_t id, AMIDI_Device *devicePtr);
91
92/*
93 * Retrieves information for the native MIDI device.
94 *
95 * device           The Native API token for the device.
96 * deviceInfoPtr    Receives the associated device info.
97 *
98 * Returns OK or a (negative) error code.
99 */
100status_t AMIDI_getDeviceInfo(AMIDI_Device device, AMIDI_DeviceInfo *deviceInfoPtr);
101
102/*
103 * API for receiving data from the Output port of a device.
104 */
105/*
106 * Opens the output port.
107 *
108 * device           Identifies the device.
109 * portNumber       Specifies the zero-based port index on the device to open.
110 * outputPortPtr    Receives the native API port identifier of the opened port.
111 *
112 * Returns OK, or a (negative) error code.
113 */
114status_t AMIDI_openOutputPort(AMIDI_Device device, int portNumber, AMIDI_OutputPort *outputPortPtr);
115
116/*
117 * Receives any pending MIDI messages (up to the specified maximum number of messages).
118 *
119 * outputPort   Identifies the port to receive messages from.
120 * messages     Points to an array (size maxMessages) to receive the MIDI messages.
121 * maxMessages  The number of messages allocated in the messages array.
122 *
123 * Returns the number of messages received, or a (negative) error code.
124 */
125ssize_t AMIDI_receive(AMIDI_OutputPort outputPort, AMIDI_Message *messages, ssize_t maxMessages);
126
127/*
128 * Closes the output port.
129 *
130 * outputPort   The native API port identifier of the port.
131 *
132 * Returns OK, or a (negative) error code.
133 */
134status_t AMIDI_closeOutputPort(AMIDI_OutputPort outputPort);
135
136/*
137 * API for sending data to the Input port of a device.
138 */
139/*
140 * Opens the input port.
141 *
142 * device           Identifies the device.
143 * portNumber       Specifies the zero-based port index on the device to open.
144 * inputPortPtr     Receives the native API port identifier of the opened port.
145 *
146 * Returns OK, or a (negative) error code.
147 */
148status_t AMIDI_openInputPort(AMIDI_Device device, int portNumber, AMIDI_InputPort *inputPortPtr);
149
150/*
151 * Returns the maximum number of bytes that can be received in a single MIDI message.
152 */
153ssize_t AMIDI_getMaxMessageSizeInBytes(AMIDI_InputPort inputPort);
154
155/*
156 * Sends data to the specified input port.
157 *
158 * inputPort    The native API identifier of the port to send data to.
159 * buffer       Points to the array of bytes containing the data to send.
160 * numBytes     Specifies the number of bytes to write.
161 *
162 * Returns  The number of bytes sent or a (negative) error code.
163 */
164ssize_t AMIDI_send(AMIDI_InputPort inputPort, uint8_t *buffer, ssize_t numBytes);
165
166/*
167 * Sends data to the specified input port with a timestamp.
168 *
169 * inputPort    The native API identifier of the port to send data to.
170 * buffer       Points to the array of bytes containing the data to send.
171 * numBytes     Specifies the number of bytes to write.
172 * timestamp    The time stamp to associate with the sent data.
173 *
174 * Returns  The number of bytes sent or a (negative) error code.
175 */
176ssize_t AMIDI_sendWithTimestamp(AMIDI_InputPort inputPort, uint8_t *buffer,
177        ssize_t numBytes, int64_t timestamp);
178
179/*
180 * Sends a message with a 'MIDI flush command code' to the specified port.
181 *
182 * inputPort    The native API identifier of the port to send the flush message to.
183 *
184 * Returns OK, or a (negative) error code.
185 */
186status_t AMIDI_flush(AMIDI_InputPort inputPort);
187
188/*
189 * Closes the input port.
190 *
191 * inputPort   The native API port identifier of the port.
192 *
193 *
194 * Returns OK, or a (negative) error code.
195 */
196status_t AMIDI_closeInputPort(AMIDI_InputPort inputPort);
197
198#ifdef __cplusplus
199}
200#endif
201
202#endif /* ANDROID_MEDIA_MIDI_H_ */
203