# native_midi_base.h

#### 概述

声明MIDI模块的基础数据结构。定义MIDI接口的基础类型、枚举、结构体和回调函数。

**引用文件：** <ohmidi/native\_midi\_base.h>

**库：** libohmidi.so

**系统能力：** SystemCapability.Multimedia.Audio.MIDI

**起始版本：** 24

**相关模块：** OHMIDI

#### 汇总

#### 结构体

| 名称 | typedef关键字 | 描述 |
| --- | --- | --- |
| OH_MIDIEvent | OH_MIDIEvent | MIDI事件结构体（通用）。事件数据以Universal MIDI Packets（UMP）格式传输。原始字节流（MIDI 1.0）数据需要先转换为UMP格式后再填充此结构体。 |
| OH_MIDIDeviceInformation | OH_MIDIDeviceInformation | 设备信息结构体。存储设备ID等相关信息。 |
| OH_MIDIPortInformation | OH_MIDIPortInformation | 端口信息结构体。用于枚举端口，包含可显示的端口名称。 |
| OH_MIDIPortDescriptor | OH_MIDIPortDescriptor | 端口描述符结构体，用于打开端口时指定端口索引和协议行为。 |
| OH_MIDICallbacks | OH_MIDICallbacks | 客户端回调结构体，包含设备变化和错误处理的回调函数。 |
| OH_MIDIClientStruct | OH_MIDIClient | 声明MIDI客户端。 |
| OH_MIDIDeviceStruct | OH_MIDIDevice | 声明MIDI设备。 |

#### 枚举

| 名称 | typedef关键字 | 描述 |
| --- | --- | --- |
| OH_MIDIStatusCode | OH_MIDIStatusCode | MIDI状态码枚举。定义MIDI操作的状态码，用于表示操作成功或失败的原因。 |
| OH_MIDIPortDirection | OH_MIDIPortDirection | 表示端口方向的枚举。定义MIDI端口的数据传输方向。 |
| OH_MIDIProtocol | OH_MIDIProtocol | MIDI协议版本枚举，用于指定端口使用的MIDI协议行为。 |
| OH_MIDIDeviceType | OH_MIDIDeviceType | MIDI设备类型枚举。定义MIDI设备的连接类型。 |
| OH_MIDIDeviceChangeAction | OH_MIDIDeviceChangeAction | 设备连接状态变化操作枚举。用于标识设备的连接和断开事件。 |

#### 函数

| 名称 | typedef关键字 | 描述 |
| --- | --- | --- |
| typedef void (*OH_MIDICallback_OnDeviceChange)(void *userData, OH_MIDIDeviceChangeAction action, OH_MIDIDeviceInformation deviceInfo) | OH_MIDICallback_OnDeviceChange | 监控设备连接/断开连接的回调。 |
| typedef void (*OH_MIDICallback_OnError)(void *userData, OH_MIDIStatusCode code) | OH_MIDICallback_OnError | 处理客户端级别错误的回调。当MIDI服务发生关键错误（如服务崩溃）时调用。应用可能需要重新创建客户端。 |
| typedef void (*OH_MIDIDevice_OnReceived)(void *userData, const OH_MIDIEvent *events, size_t eventCount) | OH_MIDIDevice_OnReceived | 接收MIDI数据的回调（批量处理）。 |
| typedef void (*OH_MIDIClient_OnDeviceOpened)(void *userData, bool opened, OH_MIDIDevice *device, OH_MIDIDeviceInformation info) | OH_MIDIClient_OnDeviceOpened | 异步打开BLE设备的结果回调。 |

#### 枚举类型说明

#### OH\_MIDIStatusCode

```
enum OH_MIDIStatusCode
```

**描述**

MIDI状态码枚举。定义MIDI操作的状态码，用于表示操作成功或失败的原因。

**起始版本：** 24

| 枚举项 | 描述 |
| --- | --- |
| OH_MIDI_STATUS_OK = 0 | 操作成功。 起始版本： 24 |
| OH_MIDI_STATUS_GENERIC_INVALID_ARGUMENT = 35500001 | 无效参数（例如：空指针）。 起始版本： 24 |
| OH_MIDI_STATUS_GENERIC_IPC_FAILURE = 35500002 | IPC通信失败。 起始版本： 24 |
| OH_MIDI_STATUS_INVALID_CLIENT = 35500003 | 无效的客户端句柄。 起始版本： 24 |
| OH_MIDI_STATUS_INVALID_DEVICE_HANDLE = 35500004 | 无效的设备句柄。 起始版本： 24 |
| OH_MIDI_STATUS_INVALID_PORT = 35500005 | 无效的端口索引。 起始版本： 24 |
| OH_MIDI_STATUS_WOULD_BLOCK = 35500006 | 发送缓冲区暂时已满。表示共享内存缓冲区当前空间不足。 当消息无法放入缓冲区时由非阻塞发送返回。建议等待约10ms后重试。 起始版本： 24 |
| OH_MIDI_STATUS_TIMEOUT = 35500007 | 操作超时。 起始版本： 24 |
| OH_MIDI_STATUS_TOO_MANY_OPEN_DEVICES = 35500008 | 客户端已达到允许打开的最大设备数量（16个）。 要打开新设备，必须先关闭现有设备。 起始版本： 24 |
| OH_MIDI_STATUS_TOO_MANY_OPEN_PORTS = 35500009 | 客户端已达到允许打开的最大端口数量（64个）。 要打开新端口，必须先关闭现有端口。 起始版本： 24 |
| OH_MIDI_STATUS_DEVICE_ALREADY_OPEN = 35500010 | 客户端已经打开此设备。同一设备在同一客户端中不允许重复打开。 起始版本： 24 |
| OH_MIDI_STATUS_PORT_ALREADY_OPEN = 35500011 | 客户端已经打开此端口。同一端口在同一客户端中不允许重复打开。 起始版本： 24 |
| OH_MIDI_STATUS_TOO_MANY_CLIENTS = 35500012 | 系统级（8个）或应用级（2个/UID）客户端数量已达上限。应用应等待或释放其他资源后重试。 起始版本： 24 |
| OH_MIDI_STATUS_PERMISSION_DENIED = 35500013 | 权限被拒绝。当应用尝试在未获得所需权限（例如BLE设备的蓝牙权限）的情况下执行操作时返回。 起始版本： 24 |
| OH_MIDI_STATUS_SERVICE_DIED = 35500014 | MIDI系统服务已崩溃或断开连接。必须销毁并重新创建客户端。 起始版本： 24 |
| OH_MIDI_STATUS_SYSTEM_ERROR = 35500100 | 系统内部错误。表示发生了未预期的系统级错误。 起始版本： 24 |

#### OH\_MIDIPortDirection

```
enum OH_MIDIPortDirection
```

**描述**

表示端口方向的枚举。定义MIDI端口的数据传输方向。

**起始版本：** 24

| 枚举项 | 描述 |
| --- | --- |
| OH_MIDI_PORT_DIRECTION_INPUT = 0 | 输入端口（设备->主机）。 起始版本： 24 |
| OH_MIDI_PORT_DIRECTION_OUTPUT = 1 | 输出端口（主机->设备）。 起始版本： 24 |

#### OH\_MIDIProtocol

```
enum OH_MIDIProtocol
```

**描述**

MIDI协议版本枚举，用于指定端口使用的MIDI协议行为。

SDK始终使用UMP（Universal MIDI Packet）格式进行数据传输，无论选择何种协议。此枚举定义连接的数据行为和语义，而不是数据结构。MT（Message Type，消息类型）是UMP数据包的消息类型标识，不同MT值对应不同类型的MIDI消息。

**起始版本：** 24

| 枚举项 | 描述 |
| --- | --- |
| OH_MIDI_PROTOCOL_1_0 = 1 | 传统MIDI 1.0语义。 在此协议下，MIDI系统服务期望接收以下UMP消息类型： - 严格遵循MIDI 1.0协议规范的UMP数据包。 - MT 0x0：实用消息（例如时间戳）。 - MT 0x1：系统实时和系统公共消息。 - MT 0x2：MIDI 1.0通道声音消息（32位）。 - MT 0x3：数据消息（64位），用于SysEx（7位载荷）。 - 如果目标硬件是MIDI 1.0：服务将UMP转换回字节流（F0...F7）。 - 如果目标硬件是MIDI 2.0：服务直接发送未经转换的UMP包（封装的MIDI 1.0）。 起始版本： 24 |
| OH_MIDI_PROTOCOL_2_0 = 2 | MIDI 2.0语义。 在此协议下，MIDI系统服务期望接收以下UMP消息类型： - 利用MIDI 2.0功能特性的UMP数据包。 - MT 0x4：MIDI 2.0通道声音消息（64位，高分辨率）。 - MT 0x0：实用消息（时间戳）。 - MT 0xD：Flex数据消息（128位，例如文本、歌词）。 - MT 0xF：UMP流消息（128位，端点发现、功能块）。 - MT 0x3 / MT 0x5：数据消息（64位或128位）。 起始版本： 24 |

#### OH\_MIDIDeviceType

```
enum OH_MIDIDeviceType
```

**描述**

MIDI设备类型枚举。定义MIDI设备的连接类型。

**起始版本：** 24

| 枚举项 | 描述 |
| --- | --- |
| OH_MIDI_DEVICE_TYPE_USB = 0 | USB MIDI设备。 |
| OH_MIDI_DEVICE_TYPE_BLE = 1 | BLE（蓝牙低功耗）MIDI设备。 |

#### OH\_MIDIDeviceChangeAction

```
enum OH_MIDIDeviceChangeAction
```

**描述**

设备连接状态变化操作枚举。用于标识设备的连接和断开事件。

**起始版本：** 24

| 枚举项 | 描述 |
| --- | --- |
| OH_MIDI_DEVICE_CHANGE_ACTION_CONNECTED = 0 | 设备已连接。 起始版本： 24 |
| OH_MIDI_DEVICE_CHANGE_ACTION_DISCONNECTED = 1 | 设备已断开。 起始版本： 24 |

#### 函数说明

#### OH\_MIDICallback\_OnDeviceChange()

```
typedef void (*OH_MIDICallback_OnDeviceChange)(void *userData, OH_MIDIDeviceChangeAction action, OH_MIDIDeviceInformation deviceInfo)
```

**描述**

监控设备连接/断开连接的回调。

**起始版本：** 24

**参数：**

| 参数项 | 描述 |
| --- | --- |
| void *userData | 调用OH_MIDIClient_Create时传入的用户自定义数据指针。 |
| OH_MIDIDeviceChangeAction action | 设备变化操作（已连接/已断开）。 |
| OH_MIDIDeviceInformation deviceInfo | 变化设备的信息。 |

#### OH\_MIDICallback\_OnError()

```
typedef void (*OH_MIDICallback_OnError)(void *userData, OH_MIDIStatusCode code)
```

**描述**

处理客户端级别错误的回调。当MIDI服务发生关键错误（如服务崩溃）时调用。应用可能需要重新创建客户端。

**起始版本：** 24

**参数：**

| 参数项 | 描述 |
| --- | --- |
| void *userData | 调用OH_MIDIClient_Create时传入的用户自定义数据指针。 |
| OH_MIDIStatusCode code | 错误状态码，指示错误原因。 |

#### OH\_MIDIDevice\_OnReceived()

```
typedef void (*OH_MIDIDevice_OnReceived)(void *userData, const OH_MIDIEvent *events, size_t eventCount)
```

**描述**

接收MIDI数据的回调（批量处理）。

内存安全与线程安全注意事项：

*   内存安全：events数组及其中所有数据指针是临时的，仅在此回调期间有效。在回调返回后访问这些指针会导致未定义行为（崩溃、内存损坏）。调用方必须复制任何需要保留的数据。
*   线程安全：此回调在高优先级系统线程上调用。不要执行阻塞操作、大量计算或I/O操作。

**起始版本：** 24

**参数：**

| 参数项 | 描述 |
| --- | --- |
| void *userData | 调用OH_MIDIClient_Create时传入的用户自定义数据指针。 |
| const OH_MIDIEvent *events | 指向接收到的MIDI事件数组的指针。 |
| size_t eventCount | 数组中的事件数。 |

#### OH\_MIDIClient\_OnDeviceOpened()

```
typedef void (*OH_MIDIClient_OnDeviceOpened)(void *userData, bool opened, OH_MIDIDevice *device, OH_MIDIDeviceInformation info)
```

**描述**

异步打开BLE设备的结果回调。

**起始版本：** 24

**参数：**

| 参数项 | 描述 |
| --- | --- |
| void *userData | 调用OH_MIDIClient_OpenBLEDevice时传入的用户自定义数据指针。 |
| bool opened | 设备是否成功打开。 true表示设备成功打开，设备句柄有效；false表示设备打开失败，设备句柄为NULL。 |
| OH_MIDIDevice *device | 已打开设备的句柄。 如果opened为true，应用必须在不再需要时调用OH_MIDIClient_CloseDevice关闭此句柄。 如果opened为false，此参数为NULL。 |
| OH_MIDIDeviceInformation info | 已打开设备的信息。 注意： 此对象仅在此回调范围内有效。如需持久化特定属性（如ID或名称），请对该设备信息进行复制。 |