jack_midi_event_get(): Add note about SysEx messages

See https://github.com/jackaudio/jack2/issues/413

1 files changed, 11 insertions, 0 deletions

diff --git a/common/jack/midiport.h b/common/jack/midiport.h
index 130bdc2c..f064d754 100644
--- a/common/jack/midiport.h
+++ b/common/jack/midiport.h
@@ -63,6 +63,17 @@ jack_midi_get_event_count(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
  * guaranteed to be a complete MIDI event (the status byte will always be
  * present, and no realtime events will interspered with the event).
  *
+ * This rule does not apply to System Exclusive MIDI messages
+ * since they can be of arbitrary length.
+ * To maintain smooth realtime operation such events CAN be deliverd
+ * as multiple, non-normalised events.
+ * The maximum size of one event "chunk" depends on the MIDI backend in use.
+ * For example the midiseq driver will create chunks of 256 bytes.
+ * The first SysEx "chunked" event starts with 0xF0 and the last
+ * delivered chunk ends with 0xF7.
+ * To receive the full SysEx message, a caller of jack_midi_event_get()
+ * must concatenate chunks until a chunk ends with 0xF7.
+ *
  * @param event Event structure to store retrieved event in.
  * @param port_buffer Port buffer from which to retrieve event.
  * @param event_index Index of event to retrieve.