dynmanifest.h (5526B)
1 /* 2 Dynamic manifest specification for LV2 3 Copyright 2008-2011 Stefano D'Angelo <zanga.mail@gmail.com> 4 5 Permission to use, copy, modify, and/or distribute this software for any 6 purpose with or without fee is hereby granted, provided that the above 7 copyright notice and this permission notice appear in all copies. 8 9 THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18 /** 19 @defgroup dynmanifest Dynamic Manifest 20 21 Support for dynamic data generation, see 22 <http://lv2plug.in/ns/ext/dynmanifest> for details. 23 24 @{ 25 */ 26 27 #ifndef LV2_DYN_MANIFEST_H_INCLUDED 28 #define LV2_DYN_MANIFEST_H_INCLUDED 29 30 #include <stdio.h> 31 32 #include "lv2.h" 33 34 #define LV2_DYN_MANIFEST_URI "http://lv2plug.in/ns/ext/dynmanifest" ///< http://lv2plug.in/ns/ext/dynmanifest 35 #define LV2_DYN_MANIFEST_PREFIX LV2_DYN_MANIFEST_URI "#" ///< http://lv2plug.in/ns/ext/dynmanifest# 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /** 42 Dynamic manifest generator handle. 43 44 This handle indicates a particular status of a dynamic manifest generator. 45 The host MUST NOT attempt to interpret it and, unlikely LV2_Handle, it is 46 NOT even valid to compare this to NULL. The dynamic manifest generator MAY 47 use it to reference internal data. 48 */ 49 typedef void * LV2_Dyn_Manifest_Handle; 50 51 /** 52 Generate the dynamic manifest. 53 54 @param handle Pointer to an uninitialized dynamic manifest generator handle. 55 56 @param features NULL terminated array of LV2_Feature structs which represent 57 the features the host supports. The dynamic manifest generator may refuse to 58 (re)generate the dynamic manifest if required features are not found here 59 (however hosts SHOULD NOT use this as a discovery mechanism, instead of 60 reading the static manifest file). This array must always exist; if a host 61 has no features, it MUST pass a single element array containing NULL. 62 63 @return 0 on success, otherwise a non-zero error code. The host SHOULD 64 evaluate the result of the operation by examining the returned value and 65 MUST NOT try to interpret the value of handle. 66 */ 67 int lv2_dyn_manifest_open(LV2_Dyn_Manifest_Handle * handle, 68 const LV2_Feature *const * features); 69 70 /** 71 Fetch a "list" of subject URIs described in the dynamic manifest. 72 73 The dynamic manifest generator has to fill the resource only with the needed 74 triples to make the host aware of the "objects" it wants to expose. For 75 example, if the plugin library exposes a regular LV2 plugin, it should 76 output only a triple like the following: 77 78 <http://www.example.com/plugin/uri> a lv2:Plugin . 79 80 The objects that are elegible for exposure are those that would need to be 81 represented by a subject node in a static manifest. 82 83 @param handle Dynamic manifest generator handle. 84 85 @param fp FILE * identifying the resource the host has to set up for the 86 dynamic manifest generator. The host MUST pass a writable, empty resource to 87 this function, and the dynamic manifest generator MUST ONLY perform write 88 operations on it at the end of the stream (e.g., using only fprintf(), 89 fwrite() and similar). 90 91 @return 0 on success, otherwise a non-zero error code. 92 */ 93 int lv2_dyn_manifest_get_subjects(LV2_Dyn_Manifest_Handle handle, 94 FILE * fp); 95 96 /** 97 Function that fetches data related to a specific URI. 98 99 The dynamic manifest generator has to fill the resource with data related to 100 object represented by the given URI. For example, if the library exposes a 101 regular LV2 plugin whose URI, as retrieved by the host using 102 lv2_dyn_manifest_get_subjects() is http://www.example.com/plugin/uri, it 103 should output something like: 104 105 <pre> 106 <http://www.example.com/plugin/uri> 107 a lv2:Plugin ; 108 doap:name "My Plugin" ; 109 lv2:binary <mylib.so> ; 110 etc:etc "..." . 111 </pre> 112 113 @param handle Dynamic manifest generator handle. 114 115 @param fp FILE * identifying the resource the host has to set up for the 116 dynamic manifest generator. The host MUST pass a writable resource to this 117 function, and the dynamic manifest generator MUST ONLY perform write 118 operations on it at the current position of the stream (e.g. using only 119 fprintf(), fwrite() and similar). 120 121 @param uri URI to get data about (in the "plain" form, i.e., absolute URI 122 without Turtle prefixes). 123 124 @return 0 on success, otherwise a non-zero error code. 125 */ 126 int lv2_dyn_manifest_get_data(LV2_Dyn_Manifest_Handle handle, 127 FILE * fp, 128 const char * uri); 129 130 /** 131 Function that ends the operations on the dynamic manifest generator. 132 133 This function SHOULD be used by the dynamic manifest generator to perform 134 cleanup operations, etc. 135 136 Once this function is called, referring to handle will cause undefined 137 behavior. 138 139 @param handle Dynamic manifest generator handle. 140 */ 141 void lv2_dyn_manifest_close(LV2_Dyn_Manifest_Handle handle); 142 143 #ifdef __cplusplus 144 } 145 #endif 146 147 #endif /* LV2_DYN_MANIFEST_H_INCLUDED */ 148 149 /** 150 @} 151 */