diff --git a/include/clap/events.h b/include/clap/events.h index a6e97513..ff6bfbec 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -297,11 +297,25 @@ typedef struct clap_event_midi { uint8_t data[3]; } clap_event_midi_t; +// clap_event_midi_sysex contains a pointer to a sysex contents buffer. +// The lifetime of this buffer is (from host->plugin) only the process +// call in which the event is delivered or (from plugin->host) only the +// duration of a try_push call. +// +// Since `clap_output_events.try_push` requires you to make a copy of +// an event, host implementers receiving sysex messages from plugin need +// to take care to both copy the event (so header, size, etc...) but +// also allocate and memcpy the sysex pointer. Similarly plugins retaining +// the sysex outside the lifetime of a single process call must copy the +// sysex buffer to memory owned by the plugin. +// +// As a result, the data structure pointed to by the sysex buffer +// must be contiguous and copyably with `memcpy` of `size` bytes. typedef struct clap_event_midi_sysex { clap_event_header_t header; uint16_t port_index; - const uint8_t *buffer; // midi buffer + const uint8_t *buffer; // midi buffer. See lifetime comment above. uint32_t size; } clap_event_midi_sysex_t;