native_midi_base.h

Overview

This file declares the basic data structure of the MIDI module. It defines the basic types, enumerations, structs, and callback functions of the MIDI APIs.

File to include: <midi/native_midi_base.h>

Library: libohmidi.so

System capability: SystemCapability.Multimedia.Audio.MIDI

Since: 24

Related module: OHMIDI

Summary

Structs

Name	typedef Keyword	Description
OH_MIDIEvent	OH_MIDIEvent	Describes a generic MIDI event structure, which is applicable to both raw byte stream (MIDI 1.0) and Universal MIDI Packet (UMP) data formats.
OH_MIDIDeviceInformation	OH_MIDIDeviceInformation	Describes the device information struct, such as the storage device ID.
OH_MIDIPortInformation	OH_MIDIPortInformation	Describes the port information struct, which is used to enumerate ports, including port names.
OH_MIDIPortDescriptor	OH_MIDIPortDescriptor	Describes the port descriptor struct, which is used to specify the port index and protocol behavior for opening a port.
OH_MIDICallbacks	OH_MIDICallbacks	Describes the client callback struct. Client callbacks include the device change callback and error handling callback.
OH_MIDIClientStruct	OH_MIDIClient	Declares a MIDI client.
OH_MIDIDeviceStruct	OH_MIDIDevice	Declares a MIDI device.

Enums

Name	typedef Keyword	Description
OH_MIDIStatusCode	OH_MIDIStatusCode	Enumerates MIDI status codes. It defines MIDI operation status codes, which are used to indicate operation success or failure causes.
OH_MIDIPortDirection	OH_MIDIPortDirection	Enumerates the port directions, which indicate MIDI ports' data transmission directions.
OH_MIDIProtocol	OH_MIDIProtocol	Enumerates the MIDI protocol versions, which are used to specify the MIDI protocols used by ports.
OH_MIDIDeviceType	OH_MIDIDeviceType	Enumerates MIDI device types, which define MIDI devices' connection types.
OH_MIDIDeviceChangeAction	OH_MIDIDeviceChangeAction	Enumerates the operations that cause device connection status changes, which are used to identify device connection and disconnection events.

Function

Name	typedef Keyword	Description
typedef void (OH_MIDICallback_OnDeviceChange)(void userData, OH_MIDIDeviceChangeAction action, OH_MIDIDeviceInformation deviceInfo)	OH_MIDICallback_OnDeviceChange	Callback for monitoring device connection and disconnection.
typedef void (OH_MIDICallback_OnError)(void userData, OH_MIDIStatusCode code)	OH_MIDICallback_OnError	Callback for handling client-level errors. It is called when a critical error (such as service crash) occurs in the MIDI service. In this case, an application may need to re-create the client.
typedef void (OH_MIDIDevice_OnReceived)(void userData, const OH_MIDIEvent *events, size_t eventCount)	OH_MIDIDevice_OnReceived	Callback for receiving MIDI data (batch processing).
typedef void (OH_MIDIClient_OnDeviceOpened)(void userData, bool opened, OH_MIDIDevice *device, OH_MIDIDeviceInformation info)	OH_MIDIClient_OnDeviceOpened	Callback for the result of asynchronously opening a BLE device.

Enum Description

OH_MIDIStatusCode

enum OH_MIDIStatusCode

Description

Enumerates MIDI status codes. It defines MIDI operation status codes, which are used to indicate operation success or failure causes.

Since: 24

Enum Item	Description
OH_MIDI_STATUS_OK = 0	The operation succeeded. Since: 24
OH_MIDI_STATUS_GENERIC_INVALID_ARGUMENT = 35500001	Invalid parameter (for example, a null pointer). Since: 24
OH_MIDI_STATUS_GENERIC_IPC_FAILURE = 35500002	IPC fails. Since: 24
OH_MIDI_STATUS_INVALID_CLIENT = 35500003	Invalid client handle. Since: 24
OH_MIDI_STATUS_INVALID_DEVICE_HANDLE = 35500004	Invalid device handle. Since: 24
OH_MIDI_STATUS_INVALID_PORT = 35500005	Invalid port index. Since: 24
OH_MIDI_STATUS_WOULD_BLOCK = 35500006	The send buffer is temporarily full, indicating that the shared memory buffer is currently out of space. This code is returned by a non-blocking send operation if messages cannot be placed into the buffer. In this case, you are advised to wait for about 10 ms and try again. Since: 24
OH_MIDI_STATUS_TIMEOUT = 35500007	The operation times out. Since: 24
OH_MIDI_STATUS_TOO_MANY_OPEN_DEVICES = 35500008	The number of devices that can be opened on the client has reached the maximum (16). To open a new device, you must first close an existing one. Since: 24
OH_MIDI_STATUS_TOO_MANY_OPEN_PORTS = 35500009	The number of ports opened on the client has reached the maximum (64). To open a new port, you must first close an existing one. Since: 24
OH_MIDI_STATUS_DEVICE_ALREADY_OPEN = 35500010	The device has already been opened on the client. A device cannot be opened repeatedly on the same client. Since: 24
OH_MIDI_STATUS_PORT_ALREADY_OPEN = 35500011	The port has already been opened on the client. A port cannot be opened repeatedly on the same client. Since: 24
OH_MIDI_STATUS_TOO_MANY_CLIENTS = 35500012	The maximum number of clients (8 system-level, or 2 application-level per UID) has been reached. The application should wait or release other resources and then try again. Since: 24
OH_MIDI_STATUS_PERMISSION_DENIED = 35500013	Permission denied. This code is returned when an application attempts to perform an operation without the required permission (for example, the Bluetooth permission for BLE devices). Since: 24
OH_MIDI_STATUS_SERVICE_DIED = 35500014	The MIDI system service has crashed or been disconnected. The client must be destroyed and re-created. Since: 24
OH_MIDI_STATUS_SYSTEM_ERROR = 35500100	Internal system error. An unexpected system-level error occurs. Since: 24

OH_MIDIPortDirection

enum OH_MIDIPortDirection

Description

Enumerates the port directions, which indicate MIDI ports' data transmission directions.

Since: 24

Enum Item	Description
OH_MIDI_PORT_DIRECTION_INPUT = 0	Input (device -> host). Since: 24
OH_MIDI_PORT_DIRECTION_OUTPUT = 1	Output (host -> device). Since: 24

OH_MIDIProtocol

enum OH_MIDIProtocol

Description

Enumerates the MIDI protocol versions, which are used to specify the MIDI protocols used by ports.

NOTE

The SDK always uses the UMP format for data transmission, regardless of which protocol is selected. This enum defines the data behavior and semantics of the connection, not the data structure. MT is the identifier for the message type within a UMP packet; different MT values correspond to different types of MIDI messages.

Since: 24

Enum Item	Description
OH_MIDI_PROTOCOL_1_0 = 1	Traditional MIDI 1.0 semantics. Under this protocol, the MIDI system service expects to receive the following types of UMP messages: - UMP packets that strictly comply with the MIDI 1.0 protocol specifications. - MT 0x0: utility messages (such as timestamps). - MT 0x1: system real-time and system common messages. - MT 0x2: MIDI 1.0 channel voice messages (32-bit). - MT 0x3: data messages (64-bit), used for SysEx (7-bit payload). - If the target hardware uses MIDI 1.0, the service converts UMP packets back to byte streams (F0...F7). - If the target hardware uses MIDI 2.0, the service directly sends the unconverted UMP packets (encapsulated based on MIDI 1.0). Since: 24
OH_MIDI_PROTOCOL_2_0 = 2	MIDI 2.0 semantics. Under this protocol, the MIDI system service expects to receive the following types of UMP messages: - UMP packets that utilize the features of MIDI 2.0. - MT 0x4: MIDI 2.0 channel voice messages (64-bit, high resolution). - MT 0x0: utility messages (timestamp). - MT 0xD: Flex data messages (128-bit, such as text and lyrics). - MT 0xF: UMP stream messages (128-bit, endpoint discovery and functional blocks). - MT 0x3/MT 0x5: data messages (64-bit or 128-bit). Since: 24

Enum Item

Description

OH_MIDI_PROTOCOL_1_0 = 1

Traditional MIDI 1.0 semantics.
Under this protocol, the MIDI system service expects to receive the following types of UMP messages:
- UMP packets that strictly comply with the MIDI 1.0 protocol specifications.
- MT 0x0: utility messages (such as timestamps).
- MT 0x1: system real-time and system common messages.
- MT 0x2: MIDI 1.0 channel voice messages (32-bit).
- MT 0x3: data messages (64-bit), used for SysEx (7-bit payload).
- If the target hardware uses MIDI 1.0, the service converts UMP packets back to byte streams (F0...F7).
- If the target hardware uses MIDI 2.0, the service directly sends the unconverted UMP packets (encapsulated based on MIDI 1.0).
Since: 24

OH_MIDI_PROTOCOL_2_0 = 2

MIDI 2.0 semantics.
Under this protocol, the MIDI system service expects to receive the following types of UMP messages:
- UMP packets that utilize the features of MIDI 2.0.
- MT 0x4: MIDI 2.0 channel voice messages (64-bit, high resolution).
- MT 0x0: utility messages (timestamp).
- MT 0xD: Flex data messages (128-bit, such as text and lyrics).
- MT 0xF: UMP stream messages (128-bit, endpoint discovery and functional blocks).
- MT 0x3/MT 0x5: data messages (64-bit or 128-bit).
Since: 24

OH_MIDIDeviceType

enum OH_MIDIDeviceType

Description

Enumerates MIDI device types, which define MIDI devices' connection types.

Since: 24

Enum Item	Description
OH_MIDI_DEVICE_TYPE_USB = 0	USB MIDI device.
OH_MIDI_DEVICE_TYPE_BLE = 1	Bluetooth Low Energy (BLE) MIDI device.

OH_MIDIDeviceChangeAction

enum OH_MIDIDeviceChangeAction

Description

Enumerates the operations that cause device connection status changes, which are used to identify device connection and disconnection events.

Since: 24

Enum Item	Description
OH_MIDI_DEVICE_CHANGE_ACTION_CONNECTED = 0	The device is connected. Since: 24
OH_MIDI_DEVICE_CHANGE_ACTION_DISCONNECTED = 1	The device is disconnected. Since: 24

Function Description

OH_MIDICallback_OnDeviceChange()

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

Description

Callback for monitoring device connection and disconnection.

Since: 24

Parameters

Name	Description
void *userData	Pointer to the custom data passed when OH_MIDIClient_Create is called.
OH_MIDIDeviceChangeAction action	Device change operation (connected/disconnected).
OH_MIDIDeviceInformation deviceInfo	Information about the device change.

OH_MIDICallback_OnError()

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

Description

Callback for handling client-level errors. It is called when a critical error (such as service crash) occurs in the MIDI service. In this case, an application may need to re-create the client.

Since: 24

Parameters

Name	Description
void *userData	Pointer to the custom data passed when OH_MIDIClient_Create is called.
OH_MIDIStatusCode code	Status code, indicating the cause of the error.

OH_MIDIDevice_OnReceived()

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

Description

Callback for receiving MIDI data (batch processing).

NOTE

Memory safety and thread safety precautions:

Memory safety: The events array and all data pointers within it are temporary and valid only during this callback. Accessing these pointers after the callback returns results in undefined behavior (crashes or memory corruption). Callers must copy any data that needs to be retained.

Thread safety: This callback is called on a high-priority system thread. Avoid blocking operations, heavy computation, or I/O operations in the callback.

Since: 24

Parameters

Name	Description
void *userData	Pointer to the custom data passed when OH_MIDIClient_Create is called.
const OH_MIDIEvent *events	Pointer to the array of received MIDI events.
size_t eventCount	Number of events in the array.

OH_MIDIClient_OnDeviceOpened()

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

Description

Callback for the result of asynchronously opening a BLE device.

Since: 24

Parameters

Name	Description
void *userData	Pointer to the custom data passed when OH_MIDIClient_OpenBLEDevice is called.
bool opened	Whether the device is successfully opened. The value true indicates that the device is successfully opened and the device handle is valid. The value false indicates that the device fails to be opened and the device handle is NULL.
OH_MIDIDevice *device	Handle to the opened device. If the value of opened is true, the application must call OH_MIDIClient_CloseDevice to close the handle when it is no longer needed. If the value of opened is false, the value of this parameter is NULL.
OH_MIDIDeviceInformation info	Information about the opened device. Note: This object is valid only within this callback. To persist specific properties (such as the ID or name), make a copy of the device information.