From 56417f7efa43827fe956d9e83c4d9fd7ed8ce0a2 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Wed, 30 Oct 2024 08:50:41 -0400 Subject: [PATCH] Document the special lifetime of clap_event_midi_sysex::buffer per conversation on discord, oct 29 --- include/clap/events.h | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) 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;