Document the special lifetime of clap_event_midi_sysex::buffer

per conversation on discord, oct 29

Author: baconpaul

include/clap/events.h

@@ -297,11 +297,27 @@ 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 hosts to make a copy of
+// an event, host implementers receiving sysex messages from plugins need
+// to take care to both copy the event (so header, size, etc...) but
+// also memcpy the contents of the sysex pointer to host-owned memory, and
+// not just copy the data pointer.
+//
+// Similarly plugins retaining the sysex outside the lifetime of a single
+// process call must copy the sysex buffer to plugin-owned memory.
+//
+// As a consequence, the data structure pointed to by the sysex buffer
+// must be contiguous and copyable 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;