Lilv  0.5.0
lilv.h
00001 /*
00002   Copyright 2007-2011 David Robillard <http://drobilla.net>
00003 
00004   Permission to use, copy, modify, and/or distribute this software for any
00005   purpose with or without fee is hereby granted, provided that the above
00006   copyright notice and this permission notice appear in all copies.
00007 
00008   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
00009   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
00010   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
00011   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
00012   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
00013   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
00014   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
00015 */
00016 
00021 #ifndef LILV_LILV_H
00022 #define LILV_LILV_H
00023 
00024 #include <stdbool.h>
00025 #include <stddef.h>
00026 #include <stdint.h>
00027 #include <stdio.h>
00028 
00029 #include "lv2/lv2plug.in/ns/lv2core/lv2.h"
00030 
00031 #ifdef LILV_SHARED
00032 #    ifdef __WIN32__
00033 #        define LILV_LIB_IMPORT __declspec(dllimport)
00034 #        define LILV_LIB_EXPORT __declspec(dllexport)
00035 #    else
00036 #        define LILV_LIB_IMPORT __attribute__((visibility("default")))
00037 #        define LILV_LIB_EXPORT __attribute__((visibility("default")))
00038 #    endif
00039 #    ifdef LILV_INTERNAL
00040 #        define LILV_API LILV_LIB_EXPORT
00041 #    else
00042 #        define LILV_API LILV_LIB_IMPORT
00043 #    endif
00044 #else
00045 #    define LILV_API
00046 #endif
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 #define LILV_NS_DOAP "http://usefulinc.com/ns/doap#"
00053 #define LILV_NS_FOAF "http://xmlns.com/foaf/0.1/"
00054 #define LILV_NS_LILV "http://drobilla.net/ns/lilv#"
00055 #define LILV_NS_LV2  "http://lv2plug.in/ns/lv2core#"
00056 #define LILV_NS_OWL  "http://www.w3.org/2002/07/owl#"
00057 #define LILV_NS_RDF  "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
00058 #define LILV_NS_RDFS "http://www.w3.org/2000/01/rdf-schema#"
00059 #define LILV_NS_XSD  "http://www.w3.org/2001/XMLSchema#"
00060 
00061 #define LILV_URI_AUDIO_PORT   "http://lv2plug.in/ns/lv2core#AudioPort"
00062 #define LILV_URI_CONTROL_PORT "http://lv2plug.in/ns/lv2core#ControlPort"
00063 #define LILV_URI_EVENT_PORT   "http://lv2plug.in/ns/ext/event#EventPort"
00064 #define LILV_URI_INPUT_PORT   "http://lv2plug.in/ns/lv2core#InputPort"
00065 #define LILV_URI_MIDI_EVENT   "http://lv2plug.in/ns/ext/midi#MidiEvent"
00066 #define LILV_URI_OUTPUT_PORT  "http://lv2plug.in/ns/lv2core#OutputPort"
00067 #define LILV_URI_PORT         "http://lv2plug.in/ns/lv2core#Port"
00068 
00069 typedef struct LilvPluginImpl      LilvPlugin;       
00070 typedef struct LilvPluginClassImpl LilvPluginClass;  
00071 typedef struct LilvPortImpl        LilvPort;         
00072 typedef struct LilvScalePointImpl  LilvScalePoint;   
00073 typedef struct LilvUIImpl          LilvUI;           
00074 typedef struct LilvNodeImpl        LilvNode;         
00075 typedef struct LilvWorldImpl       LilvWorld;        
00076 typedef struct LilvInstanceImpl    LilvInstance;     
00078 typedef void LilvIter;           
00079 typedef void LilvPluginClasses;  
00080 typedef void LilvPlugins;        
00081 typedef void LilvScalePoints;    
00082 typedef void LilvUIs;            
00083 typedef void LilvNodes;          
00105 LILV_API
00106 const char*
00107 lilv_uri_to_path(const char* uri);
00108 
00113 LILV_API
00114 LilvNode*
00115 lilv_new_uri(LilvWorld* world, const char* uri);
00116 
00121 LILV_API
00122 LilvNode*
00123 lilv_new_string(LilvWorld* world, const char* str);
00124 
00129 LILV_API
00130 LilvNode*
00131 lilv_new_int(LilvWorld* world, int val);
00132 
00137 LILV_API
00138 LilvNode*
00139 lilv_new_float(LilvWorld* world, float val);
00140 
00145 LILV_API
00146 LilvNode*
00147 lilv_new_bool(LilvWorld* world, bool val);
00148 
00153 LILV_API
00154 void
00155 lilv_node_free(LilvNode* val);
00156 
00160 LILV_API
00161 LilvNode*
00162 lilv_node_duplicate(const LilvNode* val);
00163 
00167 LILV_API
00168 bool
00169 lilv_node_equals(const LilvNode* value, const LilvNode* other);
00170 
00184 LILV_API
00185 char*
00186 lilv_node_get_turtle_token(const LilvNode* value);
00187 
00191 LILV_API
00192 bool
00193 lilv_node_is_uri(const LilvNode* value);
00194 
00200 LILV_API
00201 const char*
00202 lilv_node_as_uri(const LilvNode* value);
00203 
00207 LILV_API
00208 bool
00209 lilv_node_is_blank(const LilvNode* value);
00210 
00216 LILV_API
00217 const char*
00218 lilv_node_as_blank(const LilvNode* value);
00219 
00224 LILV_API
00225 bool
00226 lilv_node_is_literal(const LilvNode* value);
00227 
00232 LILV_API
00233 bool
00234 lilv_node_is_string(const LilvNode* value);
00235 
00239 LILV_API
00240 const char*
00241 lilv_node_as_string(const LilvNode* value);
00242 
00246 LILV_API
00247 bool
00248 lilv_node_is_float(const LilvNode* value);
00249 
00255 LILV_API
00256 float
00257 lilv_node_as_float(const LilvNode* value);
00258 
00262 LILV_API
00263 bool
00264 lilv_node_is_int(const LilvNode* value);
00265 
00270 LILV_API
00271 int
00272 lilv_node_as_int(const LilvNode* value);
00273 
00277 LILV_API
00278 bool
00279 lilv_node_is_bool(const LilvNode* value);
00280 
00285 LILV_API
00286 bool
00287 lilv_node_as_bool(const LilvNode* value);
00288 
00310 /* Collections */
00311 
00321 #define LILV_FOREACH(colltype, iter, collection) \
00322     for (LilvIter* (iter) = lilv_ ## colltype ## _begin(collection); \
00323          !lilv_ ## colltype ## _is_end(collection, iter); \
00324          (iter) = lilv_ ## colltype ## _next(collection, iter))
00325 
00326 /* LilvPluginClasses */
00327 
00328 LILV_API
00329 void
00330 lilv_plugin_classes_free(LilvPluginClasses* collection);
00331 
00332 LILV_API
00333 unsigned
00334 lilv_plugin_classes_size(const LilvPluginClasses* collection);
00335 
00336 LILV_API
00337 LilvIter*
00338 lilv_plugin_classes_begin(const LilvPluginClasses* collection);
00339 
00340 LILV_API
00341 const LilvPluginClass*
00342 lilv_plugin_classes_get(const LilvPluginClasses* collection, LilvIter* i);
00343 
00344 LILV_API
00345 LilvIter*
00346 lilv_plugin_classes_next(const LilvPluginClasses* collection, LilvIter* i);
00347 
00348 LILV_API
00349 bool
00350 lilv_plugin_classes_is_end(const LilvPluginClasses* collection, LilvIter* i);
00351 
00358 LILV_API
00359 const LilvPluginClass*
00360 lilv_plugin_classes_get_by_uri(const LilvPluginClasses* classes,
00361                                const LilvNode*          uri);
00362 
00363 /* ScalePoints */
00364 
00365 LILV_API
00366 void
00367 lilv_scale_points_free(LilvScalePoints* collection);
00368 
00369 LILV_API
00370 unsigned
00371 lilv_scale_points_size(const LilvScalePoints* collection);
00372 
00373 LILV_API
00374 LilvIter*
00375 lilv_scale_points_begin(const LilvScalePoints* collection);
00376 
00377 LILV_API
00378 const LilvScalePoint*
00379 lilv_scale_points_get(const LilvScalePoints* collection, LilvIter* i);
00380 
00381 LILV_API
00382 LilvIter*
00383 lilv_scale_points_next(const LilvScalePoints* collection, LilvIter* i);
00384 
00385 LILV_API
00386 bool
00387 lilv_scale_points_is_end(const LilvScalePoints* collection, LilvIter* i);
00388 
00389 /* UIs */
00390 
00391 LILV_API
00392 void
00393 lilv_uis_free(LilvUIs* collection);
00394 
00395 LILV_API
00396 unsigned
00397 lilv_uis_size(const LilvUIs* collection);
00398 
00399 LILV_API
00400 LilvIter*
00401 lilv_uis_begin(const LilvUIs* collection);
00402 
00403 LILV_API
00404 const LilvUI*
00405 lilv_uis_get(const LilvUIs* collection, LilvIter* i);
00406 
00407 LILV_API
00408 LilvIter*
00409 lilv_uis_next(const LilvUIs* collection, LilvIter* i);
00410 
00411 LILV_API
00412 bool
00413 lilv_uis_is_end(const LilvUIs* collection, LilvIter* i);
00414 
00421 LILV_API
00422 const LilvUI*
00423 lilv_uis_get_by_uri(const LilvUIs*  uis,
00424                     const LilvNode* uri);
00425 
00426 /* Nodes */
00427 
00428 LILV_API
00429 void
00430 lilv_nodes_free(LilvNodes* collection);
00431 
00432 LILV_API
00433 unsigned
00434 lilv_nodes_size(const LilvNodes* collection);
00435 
00436 LILV_API
00437 LilvIter*
00438 lilv_nodes_begin(const LilvNodes* collection);
00439 
00440 LILV_API
00441 const LilvNode*
00442 lilv_nodes_get(const LilvNodes* collection, LilvIter* i);
00443 
00444 LILV_API
00445 LilvIter*
00446 lilv_nodes_next(const LilvNodes* collection, LilvIter* i);
00447 
00448 LILV_API
00449 bool
00450 lilv_nodes_is_end(const LilvNodes* collection, LilvIter* i);
00451 
00452 LILV_API
00453 LilvNode*
00454 lilv_nodes_get_first(const LilvNodes* collection);
00455 
00459 LILV_API
00460 bool
00461 lilv_nodes_contains(const LilvNodes* values, const LilvNode* value);
00462 
00463 /* Plugins */
00464 
00465 LILV_API
00466 unsigned
00467 lilv_plugins_size(const LilvPlugins* collection);
00468 
00469 LILV_API
00470 LilvIter*
00471 lilv_plugins_begin(const LilvPlugins* collection);
00472 
00473 LILV_API
00474 const LilvPlugin*
00475 lilv_plugins_get(const LilvPlugins* collection, LilvIter* i);
00476 
00477 LILV_API
00478 LilvIter*
00479 lilv_plugins_next(const LilvPlugins* collection, LilvIter* i);
00480 
00481 LILV_API
00482 bool
00483 lilv_plugins_is_end(const LilvPlugins* collection, LilvIter* i);
00484 
00491 LILV_API
00492 const LilvPlugin*
00493 lilv_plugins_get_by_uri(const LilvPlugins* plugins,
00494                         const LilvNode*    uri);
00495 
00510 LILV_API
00511 LilvWorld*
00512 lilv_world_new(void);
00513 
00521 #define LILV_OPTION_FILTER_LANG "http://drobilla.net/ns/lilv#filter-lang"
00522 
00527 #define LILV_OPTION_DYN_MANIFEST "http://drobilla.net/ns/lilv#dyn-manifest"
00528 
00536 LILV_API
00537 void
00538 lilv_world_set_option(LilvWorld*      world,
00539                       const char*     uri,
00540                       const LilvNode* value);
00541 
00549 LILV_API
00550 void
00551 lilv_world_free(LilvWorld* world);
00552 
00564 LILV_API
00565 void
00566 lilv_world_load_all(LilvWorld* world);
00567 
00580 LILV_API
00581 void
00582 lilv_world_load_bundle(LilvWorld* world,
00583                        LilvNode*  bundle_uri);
00584 
00588 LILV_API
00589 const LilvPluginClass*
00590 lilv_world_get_plugin_class(const LilvWorld* world);
00591 
00596 LILV_API
00597 const LilvPluginClasses*
00598 lilv_world_get_plugin_classes(const LilvWorld* world);
00599 
00611 LILV_API
00612 const LilvPlugins*
00613 lilv_world_get_all_plugins(const LilvWorld* world);
00614 
00620 LILV_API
00621 LilvNodes*
00622 lilv_world_find_nodes(LilvWorld*      world,
00623                       const LilvNode* subject,
00624                       const LilvNode* predicate,
00625                       const LilvNode* object);
00626 
00643 LILV_API
00644 bool
00645 lilv_plugin_verify(const LilvPlugin* plugin);
00646 
00661 LILV_API
00662 const LilvNode*
00663 lilv_plugin_get_uri(const LilvPlugin* plugin);
00664 
00676 LILV_API
00677 const LilvNode*
00678 lilv_plugin_get_bundle_uri(const LilvPlugin* plugin);
00679 
00688 LILV_API
00689 const LilvNodes*
00690 lilv_plugin_get_data_uris(const LilvPlugin* plugin);
00691 
00698 LILV_API
00699 const LilvNode*
00700 lilv_plugin_get_library_uri(const LilvPlugin* plugin);
00701 
00709 LILV_API
00710 LilvNode*
00711 lilv_plugin_get_name(const LilvPlugin* plugin);
00712 
00716 LILV_API
00717 const LilvPluginClass*
00718 lilv_plugin_get_class(const LilvPlugin* plugin);
00719 
00732 LILV_API
00733 LilvNodes*
00734 lilv_plugin_get_value(const LilvPlugin* p,
00735                       const LilvNode*   predicate);
00736 
00742 LILV_API
00743 bool
00744 lilv_plugin_has_feature(const LilvPlugin* p,
00745                         const LilvNode*   feature_uri);
00746 
00757 LILV_API
00758 LilvNodes*
00759 lilv_plugin_get_supported_features(const LilvPlugin* p);
00760 
00772 LILV_API
00773 LilvNodes*
00774 lilv_plugin_get_required_features(const LilvPlugin* p);
00775 
00784 LILV_API
00785 LilvNodes*
00786 lilv_plugin_get_optional_features(const LilvPlugin* p);
00787 
00791 LILV_API
00792 uint32_t
00793 lilv_plugin_get_num_ports(const LilvPlugin* p);
00794 
00809 LILV_API
00810 void
00811 lilv_plugin_get_port_ranges_float(const LilvPlugin* p,
00812                                   float*            min_values,
00813                                   float*            max_values,
00814                                   float*            def_values);
00815 
00822 LILV_API
00823 uint32_t
00824 lilv_plugin_get_num_ports_of_class(const LilvPlugin* p,
00825                                    const LilvNode*   class_1, ...);
00826 
00832 LILV_API
00833 bool
00834 lilv_plugin_has_latency(const LilvPlugin* p);
00835 
00845 LILV_API
00846 uint32_t
00847 lilv_plugin_get_latency_port_index(const LilvPlugin* p);
00848 
00852 LILV_API
00853 const LilvPort*
00854 lilv_plugin_get_port_by_index(const LilvPlugin* plugin,
00855                               uint32_t          index);
00856 
00862 LILV_API
00863 const LilvPort*
00864 lilv_plugin_get_port_by_symbol(const LilvPlugin* plugin,
00865                                const LilvNode*   symbol);
00866 
00872 LILV_API
00873 LilvNode*
00874 lilv_plugin_get_author_name(const LilvPlugin* plugin);
00875 
00881 LILV_API
00882 LilvNode*
00883 lilv_plugin_get_author_email(const LilvPlugin* plugin);
00884 
00890 LILV_API
00891 LilvNode*
00892 lilv_plugin_get_author_homepage(const LilvPlugin* plugin);
00893 
00900 LILV_API
00901 bool
00902 lilv_plugin_is_replaced(const LilvPlugin* plugin);
00903 
00910 LILV_API
00911 void
00912 lilv_plugin_write_description(LilvWorld*        world,
00913                               const LilvPlugin* plugin,
00914                               const LilvNode*   base_uri,
00915                               FILE*             plugin_file);
00916 
00917 LILV_API
00918 void
00919 lilv_plugin_write_manifest_entry(LilvWorld*        world,
00920                                  const LilvPlugin* plugin,
00921                                  const LilvNode*   base_uri,
00922                                  FILE*             manifest_file,
00923                                  const char*       plugin_file_path);
00924 
00934 LILV_API
00935 LilvNodes*
00936 lilv_port_get_value(const LilvPlugin* plugin,
00937                     const LilvPort*   port,
00938                     const LilvNode*   predicate);
00939 
00943 LILV_API
00944 LilvNodes*
00945 lilv_port_get_properties(const LilvPlugin* plugin,
00946                          const LilvPort*   port);
00947 
00951 LILV_API
00952 bool
00953 lilv_port_has_property(const LilvPlugin* p,
00954                        const LilvPort*   port,
00955                        const LilvNode*   property_uri);
00956 
00960 LILV_API
00961 bool
00962 lilv_port_supports_event(const LilvPlugin* p,
00963                          const LilvPort*   port,
00964                          const LilvNode*   event_uri);
00965 
00971 LILV_API
00972 const LilvNode*
00973 lilv_port_get_symbol(const LilvPlugin* plugin,
00974                      const LilvPort*   port);
00975 
00982 LILV_API
00983 LilvNode*
00984 lilv_port_get_name(const LilvPlugin* plugin,
00985                    const LilvPort*   port);
00986 
00994 LILV_API
00995 const LilvNodes*
00996 lilv_port_get_classes(const LilvPlugin* plugin,
00997                       const LilvPort*   port);
00998 
01007 LILV_API
01008 bool
01009 lilv_port_is_a(const LilvPlugin* plugin,
01010                const LilvPort*   port,
01011                const LilvNode*   port_class);
01012 
01021 LILV_API
01022 void
01023 lilv_port_get_range(const LilvPlugin* plugin,
01024                     const LilvPort*   port,
01025                     LilvNode**        deflt,
01026                     LilvNode**        min,
01027                     LilvNode**        max);
01028 
01036 LILV_API
01037 LilvScalePoints*
01038 lilv_port_get_scale_points(const LilvPlugin* plugin,
01039                            const LilvPort*   port);
01040 
01051 LILV_API
01052 const LilvNode*
01053 lilv_scale_point_get_label(const LilvScalePoint* point);
01054 
01059 LILV_API
01060 const LilvNode*
01061 lilv_scale_point_get_value(const LilvScalePoint* point);
01062 
01074 LILV_API
01075 const LilvNode*
01076 lilv_plugin_class_get_parent_uri(const LilvPluginClass* plugin_class);
01077 
01082 LILV_API
01083 const LilvNode*
01084 lilv_plugin_class_get_uri(const LilvPluginClass* plugin_class);
01085 
01090 LILV_API
01091 const LilvNode*
01092 lilv_plugin_class_get_label(const LilvPluginClass* plugin_class);
01093 
01098 LILV_API
01099 LilvPluginClasses*
01100 lilv_plugin_class_get_children(const LilvPluginClass* plugin_class);
01101 
01112 /* Instance of a plugin.
01113    This is exposed in the ABI to allow inlining of performance critical
01114    functions like lilv_instance_run (simple wrappers of functions in lv2.h).
01115    This is for performance reasons, user code should not use this definition
01116    in any way (which is why it is not machine documented).
01117    Truly private implementation details are hidden via @a ref pimpl.
01118 */
01119 struct LilvInstanceImpl {
01120     const LV2_Descriptor* lv2_descriptor;
01121     LV2_Handle            lv2_handle;
01122     void*                 pimpl;
01123 };
01124 
01138 LILV_API
01139 LilvInstance*
01140 lilv_plugin_instantiate(const LilvPlugin*        plugin,
01141                         double                   sample_rate,
01142                         const LV2_Feature*const* features);
01143 
01149 LILV_API
01150 void
01151 lilv_instance_free(LilvInstance* instance);
01152 
01153 #ifndef LILV_INTERNAL
01154 
01159 static inline const char*
01160 lilv_instance_get_uri(const LilvInstance* instance)
01161 {
01162     return instance->lv2_descriptor->URI;
01163 }
01164 
01170 static inline void
01171 lilv_instance_connect_port(LilvInstance* instance,
01172                            uint32_t      port_index,
01173                            void*         data_location)
01174 {
01175     instance->lv2_descriptor->connect_port
01176         (instance->lv2_handle, port_index, data_location);
01177 }
01178 
01185 static inline void
01186 lilv_instance_activate(LilvInstance* instance)
01187 {
01188     if (instance->lv2_descriptor->activate)
01189         instance->lv2_descriptor->activate(instance->lv2_handle);
01190 }
01191 
01197 static inline void
01198 lilv_instance_run(LilvInstance* instance,
01199                   uint32_t      sample_count)
01200 {
01201     instance->lv2_descriptor->run(instance->lv2_handle, sample_count);
01202 }
01203 
01209 static inline void
01210 lilv_instance_deactivate(LilvInstance* instance)
01211 {
01212     if (instance->lv2_descriptor->deactivate)
01213         instance->lv2_descriptor->deactivate(instance->lv2_handle);
01214 }
01215 
01221 static inline const void*
01222 lilv_instance_get_extension_data(const LilvInstance* instance,
01223                                  const char*         uri)
01224 {
01225     if (instance->lv2_descriptor->extension_data)
01226         return instance->lv2_descriptor->extension_data(uri);
01227     else
01228         return NULL;
01229 }
01230 
01238 static inline const LV2_Descriptor*
01239 lilv_instance_get_descriptor(const LilvInstance* instance)
01240 {
01241     return instance->lv2_descriptor;
01242 }
01243 
01251 static inline LV2_Handle
01252 lilv_instance_get_handle(const LilvInstance* instance)
01253 {
01254     return instance->lv2_handle;
01255 }
01256 
01257 #endif /* LILV_INTERNAL */
01258 
01269 LILV_API
01270 LilvUIs*
01271 lilv_plugin_get_uis(const LilvPlugin* plugin);
01272 
01278 LILV_API
01279 const LilvNode*
01280 lilv_ui_get_uri(const LilvUI* ui);
01281 
01290 LILV_API
01291 const LilvNodes*
01292 lilv_ui_get_classes(const LilvUI* ui);
01293 
01299 LILV_API
01300 bool
01301 lilv_ui_is_a(const LilvUI* ui, const LilvNode* class_uri);
01302 
01309 typedef unsigned (*LilvUISupportedFunc)(const char* container_type_uri,
01310                                         const char* ui_type_uri);
01311 
01321 LILV_API
01322 unsigned
01323 lilv_ui_is_supported(const LilvUI*       ui,
01324                      LilvUISupportedFunc supported_func,
01325                      const LilvNode*     container_type,
01326                      const LilvNode**    ui_type);
01327 
01333 LILV_API
01334 const LilvNode*
01335 lilv_ui_get_bundle_uri(const LilvUI* ui);
01336 
01342 LILV_API
01343 const LilvNode*
01344 lilv_ui_get_binary_uri(const LilvUI* ui);
01345 
01351 #ifdef __cplusplus
01352 } /* extern "C" */
01353 #endif
01354 
01355 #endif /* LILV_LILV_H */