aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/log
diff options
context:
space:
mode:
Diffstat (limited to 'lv2/log')
-rw-r--r--lv2/log/log.h109
-rw-r--r--lv2/log/log.ttl68
-rw-r--r--lv2/log/logger.h160
-rw-r--r--lv2/log/lv2-log.doap.ttl52
-rw-r--r--lv2/log/manifest.ttl9
5 files changed, 398 insertions, 0 deletions
diff --git a/lv2/log/log.h b/lv2/log/log.h
new file mode 100644
index 0000000..11bb35a
--- /dev/null
+++ b/lv2/log/log.h
@@ -0,0 +1,109 @@
+/*
+ Copyright 2012-2016 David Robillard <http://drobilla.net>
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted, provided that the above
+ copyright notice and this permission notice appear in all copies.
+
+ THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/**
+ @defgroup log Log
+
+ Interface for plugins to log via the host; see
+ <http://lv2plug.in/ns/ext/log> for details.
+
+ @{
+*/
+
+#ifndef LV2_LOG_H
+#define LV2_LOG_H
+
+#define LV2_LOG_URI "http://lv2plug.in/ns/ext/log" ///< http://lv2plug.in/ns/ext/log
+#define LV2_LOG_PREFIX LV2_LOG_URI "#" ///< http://lv2plug.in/ns/ext/log#
+
+#define LV2_LOG__Entry LV2_LOG_PREFIX "Entry" ///< http://lv2plug.in/ns/ext/log#Entry
+#define LV2_LOG__Error LV2_LOG_PREFIX "Error" ///< http://lv2plug.in/ns/ext/log#Error
+#define LV2_LOG__Note LV2_LOG_PREFIX "Note" ///< http://lv2plug.in/ns/ext/log#Note
+#define LV2_LOG__Trace LV2_LOG_PREFIX "Trace" ///< http://lv2plug.in/ns/ext/log#Trace
+#define LV2_LOG__Warning LV2_LOG_PREFIX "Warning" ///< http://lv2plug.in/ns/ext/log#Warning
+#define LV2_LOG__log LV2_LOG_PREFIX "log" ///< http://lv2plug.in/ns/ext/log#log
+
+#include <stdarg.h>
+
+#include "lv2/urid/urid.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @cond */
+#ifdef __GNUC__
+/** Allow type checking of printf-like functions. */
+# define LV2_LOG_FUNC(fmt, arg1) __attribute__((format(printf, fmt, arg1)))
+#else
+# define LV2_LOG_FUNC(fmt, arg1)
+#endif
+/** @endcond */
+
+/**
+ Opaque data to host data for LV2_Log_Log.
+*/
+typedef void* LV2_Log_Handle;
+
+/**
+ Log feature (LV2_LOG__log)
+*/
+typedef struct _LV2_Log {
+ /**
+ Opaque pointer to host data.
+
+ This MUST be passed to methods in this struct whenever they are called.
+ Otherwise, it must not be interpreted in any way.
+ */
+ LV2_Log_Handle handle;
+
+ /**
+ Log a message, passing format parameters directly.
+
+ The API of this function matches that of the standard C printf function,
+ except for the addition of the first two parameters. This function may
+ be called from any non-realtime context, or from any context if `type`
+ is @ref LV2_LOG__Trace.
+ */
+ LV2_LOG_FUNC(3, 4)
+ int (*printf)(LV2_Log_Handle handle,
+ LV2_URID type,
+ const char* fmt, ...);
+
+ /**
+ Log a message, passing format parameters in a va_list.
+
+ The API of this function matches that of the standard C vprintf
+ function, except for the addition of the first two parameters. This
+ function may be called from any non-realtime context, or from any
+ context if `type` is @ref LV2_LOG__Trace.
+ */
+ LV2_LOG_FUNC(3, 0)
+ int (*vprintf)(LV2_Log_Handle handle,
+ LV2_URID type,
+ const char* fmt,
+ va_list ap);
+} LV2_Log_Log;
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* LV2_LOG_H */
+
+/**
+ @}
+*/
diff --git a/lv2/log/log.ttl b/lv2/log/log.ttl
new file mode 100644
index 0000000..60e1d3f
--- /dev/null
+++ b/lv2/log/log.ttl
@@ -0,0 +1,68 @@
+@prefix log: <http://lv2plug.in/ns/ext/log#> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<http://lv2plug.in/ns/ext/log>
+ a lv2:Specification ;
+ rdfs:seeAlso <log.h> ,
+ <lv2-log.doap.ttl> ;
+ lv2:documentation """
+<p>This extension defines a feature, log:log, which allows plugins to print log
+messages with an API much like the standard C printf functions. This allows,
+for example, plugin logs to be nicely presented to the user in a graphical user
+interface.</p>
+
+<p>Different log levels (e.g. <q>error</q> or <q>information</q>) are defined
+by URI and passed as an LV2_URID. This document defines the typical levels
+which should be sufficient, but implementations may define and use additional
+levels to suit their needs.</p>
+""" .
+
+log:Entry
+ a rdfs:Class ;
+ rdfs:label "Log Entry" ;
+ lv2:documentation """
+<p>A log entry. Subclasses of this class can be passed to LV2_Log_Log methods
+to describe the nature of the log message.</p>""" .
+
+log:Error
+ a rdfs:Class ;
+ rdfs:label "Error" ;
+ rdfs:subClassOf log:Entry ;
+ rdfs:comment "An error message." .
+
+log:Note
+ a rdfs:Class ;
+ rdfs:label "Note" ;
+ rdfs:subClassOf log:Entry ;
+ rdfs:comment "An informative message." .
+
+log:Warning
+ a rdfs:Class ;
+ rdfs:label "Warning" ;
+ rdfs:subClassOf log:Entry ;
+ rdfs:comment "A warning message." .
+
+log:Trace
+ a rdfs:Class ;
+ rdfs:label "Trace" ;
+ rdfs:subClassOf log:Entry ;
+ lv2:documentation """
+<p>A debugging trace. These entries should not be displayed during normal
+operation, but the host may implement an option to display them for debugging
+purposes.</p>
+
+<p>This entry type is special in that it may be written to in a real-time
+thread. It is assumed that if debug tracing is enabled, real-time
+considerations are not a concern.</p>
+""" .
+
+log:log
+ a lv2:Feature ;
+ lv2:documentation """
+<p>A feature which plugins may use to log messages. To support this feature,
+the host must pass an LV2_Feature to LV2_Descriptor::instantiate() with URI
+LV2_LOG__log and data pointed to an instance of LV2_Log_Log.</p>
+""" .
diff --git a/lv2/log/logger.h b/lv2/log/logger.h
new file mode 100644
index 0000000..0c608a6
--- /dev/null
+++ b/lv2/log/logger.h
@@ -0,0 +1,160 @@
+/*
+ Copyright 2012-2016 David Robillard <http://drobilla.net>
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted, provided that the above
+ copyright notice and this permission notice appear in all copies.
+
+ THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/**
+ @defgroup logger Logger
+ @ingroup log
+
+ Convenience API for easy logging in plugin code. This API provides simple
+ wrappers for logging from a plugin, which automatically fall back to
+ printing to stderr if host support is unavailabe.
+
+ @{
+*/
+
+#ifndef LV2_ATOM_LOGGER_H
+#define LV2_ATOM_LOGGER_H
+
+#include <stdio.h>
+#include <string.h>
+
+#include "lv2/log/log.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ Logger convenience API state.
+*/
+typedef struct {
+ LV2_Log_Log* log;
+
+ LV2_URID Error;
+ LV2_URID Note;
+ LV2_URID Trace;
+ LV2_URID Warning;
+} LV2_Log_Logger;
+
+/**
+ Set `map` as the URI map for `logger`.
+
+ This affects the message type URIDs (Error, Warning, etc) which are passed
+ to the log's print functions.
+*/
+static inline void
+lv2_log_logger_set_map(LV2_Log_Logger* logger, LV2_URID_Map* map)
+{
+ if (map) {
+ logger->Error = map->map(map->handle, LV2_LOG__Error);
+ logger->Note = map->map(map->handle, LV2_LOG__Note);
+ logger->Trace = map->map(map->handle, LV2_LOG__Trace);
+ logger->Warning = map->map(map->handle, LV2_LOG__Warning);
+ } else {
+ logger->Error = logger->Note = logger->Trace = logger->Warning = 0;
+ }
+}
+
+/**
+ Initialise `logger`.
+
+ URIs will be mapped using `map` and stored, a reference to `map` itself is
+ not held. Both `map` and `log` may be NULL when unsupported by the host,
+ in which case the implementation will fall back to printing to stderr.
+*/
+static inline void
+lv2_log_logger_init(LV2_Log_Logger* logger,
+ LV2_URID_Map* map,
+ LV2_Log_Log* log)
+{
+ logger->log = log;
+ lv2_log_logger_set_map(logger, map);
+}
+
+/**
+ Log a message to the host, or stderr if support is unavailable.
+*/
+LV2_LOG_FUNC(3, 0)
+static inline int
+lv2_log_vprintf(LV2_Log_Logger* logger,
+ LV2_URID type,
+ const char* fmt,
+ va_list args)
+{
+ if (logger && logger->log) {
+ return logger->log->vprintf(logger->log->handle, type, fmt, args);
+ } else {
+ return vfprintf(stderr, fmt, args);
+ }
+}
+
+/** Log an error via lv2_log_vprintf(). */
+LV2_LOG_FUNC(2, 3)
+static inline int
+lv2_log_error(LV2_Log_Logger* logger, const char* fmt, ...)
+{
+ va_list args;
+ va_start(args, fmt);
+ const int ret = lv2_log_vprintf(logger, logger->Error, fmt, args);
+ va_end(args);
+ return ret;
+}
+
+/** Log a note via lv2_log_vprintf(). */
+LV2_LOG_FUNC(2, 3)
+static inline int
+lv2_log_note(LV2_Log_Logger* logger, const char* fmt, ...)
+{
+ va_list args;
+ va_start(args, fmt);
+ const int ret = lv2_log_vprintf(logger, logger->Note, fmt, args);
+ va_end(args);
+ return ret;
+}
+
+/** Log a trace via lv2_log_vprintf(). */
+LV2_LOG_FUNC(2, 3)
+static inline int
+lv2_log_trace(LV2_Log_Logger* logger, const char* fmt, ...)
+{
+ va_list args;
+ va_start(args, fmt);
+ const int ret = lv2_log_vprintf(logger, logger->Trace, fmt, args);
+ va_end(args);
+ return ret;
+}
+
+/** Log a warning via lv2_log_vprintf(). */
+LV2_LOG_FUNC(2, 3)
+static inline int
+lv2_log_warning(LV2_Log_Logger* logger, const char* fmt, ...)
+{
+ va_list args;
+ va_start(args, fmt);
+ const int ret = lv2_log_vprintf(logger, logger->Warning, fmt, args);
+ va_end(args);
+ return ret;
+}
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* LV2_LOG_LOGGER_H */
+
+/**
+ @}
+*/
diff --git a/lv2/log/lv2-log.doap.ttl b/lv2/log/lv2-log.doap.ttl
new file mode 100644
index 0000000..d109809
--- /dev/null
+++ b/lv2/log/lv2-log.doap.ttl
@@ -0,0 +1,52 @@
+@prefix dcs: <http://ontologi.es/doap-changeset#> .
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/log>
+ a doap:Project ;
+ doap:name "LV2 Log" ;
+ doap:shortdesc "A feature for writing log messages." ;
+ doap:created "2012-01-12" ;
+ doap:developer <http://drobilla.net/drobilla#me> ;
+ doap:release [
+ doap:revision "2.4" ;
+ doap:created "2016-07-30" ;
+ doap:file-release <http://lv2plug.in/spec/lv2-1.14.0.tar.bz2> ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Add lv2_log_logger_set_map() for changing the URI map of an existing logger."
+ ]
+ ]
+ ] , [
+ doap:revision "2.2" ;
+ doap:created "2014-01-04" ;
+ doap:file-release <http://lv2plug.in/spec/lv2-1.8.0.tar.bz2> ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Add missing include string.h to logger.h for memset."
+ ]
+ ]
+ ] , [
+ doap:revision "2.0" ;
+ doap:created "2013-01-08" ;
+ doap:file-release <http://lv2plug.in/spec/lv2-1.4.0.tar.bz2> ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Add logger convenience API."
+ ]
+ ]
+ ] , [
+ doap:revision "1.0" ;
+ doap:created "2012-04-17" ;
+ doap:file-release <http://lv2plug.in/spec/lv2-1.0.0.tar.bz2> ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Initial release."
+ ]
+ ]
+ ] .
diff --git a/lv2/log/manifest.ttl b/lv2/log/manifest.ttl
new file mode 100644
index 0000000..afe7449
--- /dev/null
+++ b/lv2/log/manifest.ttl
@@ -0,0 +1,9 @@
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/log>
+ a lv2:Specification ;
+ lv2:minorVersion 2 ;
+ lv2:microVersion 4 ;
+ rdfs:seeAlso <log.ttl> .
+
generated by cgit v1.2.1 (git 2.18.0) at 2024-12-28 04:41:58 +0000