src/calf/lv2_string_port.h

   1 /* lv2_string_port.h - C header file for LV2 string port extension.
   2  * Draft version 3.
   3  *
   4  * Copyright (C) 2008 Krzysztof Foltman <wdev@foltman.com>
   5  *
   6  * This header is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published
   8  * by the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This header is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  14  * License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this header; if not, write to the Free Software Foundation,
  18  * Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA
  19  */
  20
  21 #ifndef LV2_STRING_PORT_H
  22 #define LV2_STRING_PORT_H
  23
  24 #include <stdint.h>
  25
  26 /** \file
  27 Input ports string value lifetime:
  28 If the port does not have a context specified (it runs in the default,
  29 realtime audio processing context), the values in the structure and
  30 the actual string data MUST remain unchanged for the time a run() function
  31 of a plugin is executed. However, if the port belongs to a different
  32 context, the same data MUST remain unchanged only for the time a run() or
  33 message_process() function of a given context is executed.
  34
  35 Output ports string value lifetime:
  36 The plugin may only change the string or length in a run() function (if
  37 the port belongs to default context) or in context-defined counterparts
  38 (if the port belongs to another context). Because of that, using default
  39 context output string ports is contraindicated for longer strings.
  40
  41 UI issues:
  42 When using port_event / write_port (and possible other communication
  43 mechanisms), the format parameter should contain the numeric value
  44 of URI LV2_STRING_PORT_URI (mapped with http://lv2plug.in/ns/extensions/ui
  45 specified as map URI).
  46
  47 It's probably possible to use ports belonging to message context
  48 <http://lv2plug.in/ns/dev/contexts#MessageContext> for transfer. However,
  49 contexts mechanism does not offer any way to notify the message recipient
  50 about which ports have been changed. To remedy that, this extension defines
  51 a flag LV2_STRING_DATA_CHANGED_FLAG that carries that information inside
  52 a port value structure.
  53
  54 Storage:
  55 The value of string port are assumed to be "persistent": if a host
  56 saves and restores a state of a plugin (e.g. control port values), the
  57 values of input string ports should also be assumed to belong to that
  58 state. This also applies to message context: if a session is being restored,
  59 the host MUST resend the last value that was sent to the port before session
  60 has been saved. In other words, string port values "stick" to message ports.
  61 */
  62
  63 /** URI for the string port transfer mechanism feature */
  64 #define LV2_STRING_PORT_URI "http://lv2plug.in/ns/dev/string-port#StringTransfer"
  65
  66 /** Flag: port data has been updated; for input ports, this flag is set by
  67 the host. For output ports, this flag is set by the plugin. */
  68 #define LV2_STRING_DATA_CHANGED_FLAG 1
  69
  70 /** structure for string port data */
  71 struct _LV2_String_Data
  72 {
  73     /** buffer for UTF-8 encoded zero-terminated string value; host-allocated */
  74     char *data;
  75     /** length in bytes (not characters), not including zero byte */
  76     size_t len;
  77     /** output ports: storage space in bytes; must be >= RDF-specified requirements */
  78     size_t storage;
  79     /** flags defined above */
  80     uint32_t flags;
  81     /** undefined yet, used for padding to 8 bytes */
  82     uint32_t pad;
  83 };
  84
  85 typedef struct _LV2_String_Data LV2_String_Data;
  86
  87 #endif