X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=log.c;h=228f3cc4d72b01a59d6b7da6a1d42a8ae6b3ba6e;hb=9fb5f2dfa6bcded8082677ed3b915ff6b880cfab;hp=e981c852aa285055bf7a59e84e9d7ee50502f67e;hpb=1f9813eb6cf2fa3b6511af46b19270feb9484c1e;p=libsigrok.git

diff --git a/log.c b/log.c
index e981c852..228f3cc4 100644
--- a/log.c
+++ b/log.c
@@ -20,8 +20,22 @@
 
 #include <stdarg.h>
 #include <stdio.h>
-#include "sigrok.h"
-#include "sigrok-internal.h"
+#include "libsigrok.h"
+#include "libsigrok-internal.h"
+
+/**
+ * @file
+ *
+ * Controlling the libsigrok message logging functionality.
+ */
+
+/**
+ * @defgroup grp_logging Logging
+ *
+ * Controlling the libsigrok message logging functionality.
+ *
+ * @{
+ */
 
 /* Currently selected libsigrok loglevel. Default: SR_LOG_WARN. */
 static int sr_loglevel = SR_LOG_WARN; /* Show errors+warnings per default. */
@@ -30,18 +44,20 @@ static int sr_loglevel = SR_LOG_WARN; /* Show errors+warnings per default. */
 static int sr_logv(void *cb_data, int loglevel, const char *format,
 		   va_list args);
 
-/* Pointer to the currently selected log handler. Default: sr_logv(). */
-static sr_log_handler_t sr_log_handler = sr_logv;
+/* Pointer to the currently selected log callback. Default: sr_logv(). */
+static sr_log_callback_t sr_log_callback = sr_logv;
 
 /*
- * Pointer to private data that can be passed to the log handler.
+ * Pointer to private data that can be passed to the log callback.
  * This can be used (for example) by C++ GUIs to pass a "this" pointer.
  */
-static void *sr_log_handler_data = NULL;
+static void *sr_log_callback_data = NULL;
 
 /* Log domain (a short string that is used as prefix for all messages). */
+/** @cond PRIVATE */
 #define LOGDOMAIN_MAXLEN 30
 #define LOGDOMAIN_DEFAULT "sr: "
+/** @endcond */
 static char sr_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
 
 /**
@@ -58,6 +74,8 @@ static char sr_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
  *                 SR_LOG_INFO, SR_LOG_DBG, or SR_LOG_SPEW).
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid loglevel.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_loglevel_set(int loglevel)
 {
@@ -77,6 +95,8 @@ SR_API int sr_log_loglevel_set(int loglevel)
  * Get the libsigrok loglevel.
  *
  * @return The currently configured libsigrok loglevel.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_loglevel_get(void)
 {
@@ -96,6 +116,8 @@ SR_API int sr_log_loglevel_get(void)
  *                  the caller does not need to keep it around.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid logdomain.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_logdomain_set(const char *logdomain)
 {
@@ -118,6 +140,8 @@ SR_API int sr_log_logdomain_set(const char *logdomain)
  * @return A copy of the currently configured libsigrok logdomain
  *         string. The caller is responsible for g_free()ing the string when
  *         it is no longer needed.
+ *
+ * @since 0.1.0
  */
 SR_API char *sr_log_logdomain_get(void)
 {
@@ -125,10 +149,10 @@ SR_API char *sr_log_logdomain_get(void)
 }
 
 /**
- * Set the libsigrok log handler to the specified function.
+ * Set the libsigrok log callback to the specified function.
  *
- * @param handler Function pointer to the log handler function to use.
- *                Must not be NULL.
+ * @param cb Function pointer to the log callback function to use.
+ *           Must not be NULL.
  * @param cb_data Pointer to private data to be passed on. This can be used by
  *                the caller to pass arbitrary data to the log functions. This
  *                pointer is only stored or passed on by libsigrok, and is
@@ -136,37 +160,41 @@ SR_API char *sr_log_logdomain_get(void)
  *                to be NULL if the caller doesn't need/want to pass any data.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
+ *
+ * @since 0.1.0
  */
-SR_API int sr_log_handler_set(sr_log_handler_t handler, void *cb_data)
+SR_API int sr_log_callback_set(sr_log_callback_t cb, void *cb_data)
 {
-	if (!handler) {
-		sr_err("log: %s: handler was NULL", __func__);
+	if (!cb) {
+		sr_err("log: %s: cb was NULL", __func__);
 		return SR_ERR_ARG;
 	}
 
 	/* Note: 'cb_data' is allowed to be NULL. */
 
-	sr_log_handler = handler;
-	sr_log_handler_data = cb_data;
+	sr_log_callback = cb;
+	sr_log_callback_data = cb_data;
 
 	return SR_OK;
 }
 
 /**
- * Set the libsigrok log handler to the default built-in one.
+ * Set the libsigrok log callback to the default built-in one.
  *
- * Additionally, the internal 'sr_log_handler_data' pointer is set to NULL.
+ * Additionally, the internal 'sr_log_callback_data' pointer is set to NULL.
  *
  * @return SR_OK upon success, a negative error code otherwise.
+ *
+ * @since 0.1.0
  */
-SR_API int sr_log_handler_set_default(void)
+SR_API int sr_log_callback_set_default(void)
 {
 	/*
 	 * Note: No log output in this function, as it should safely work
-	 * even if the currently set log handler is buggy/broken.
+	 * even if the currently set log callback is buggy/broken.
 	 */
-	sr_log_handler = sr_logv;
-	sr_log_handler_data = NULL;
+	sr_log_callback = sr_logv;
+	sr_log_callback_data = NULL;
 
 	return SR_OK;
 }
@@ -175,7 +203,7 @@ static int sr_logv(void *cb_data, int loglevel, const char *format, va_list args
 {
 	int ret;
 
-	/* This specific log handler doesn't need the void pointer data. */
+	/* This specific log callback doesn't need the void pointer data. */
 	(void)cb_data;
 
 	/* Only output messages of at least the selected loglevel(s). */
@@ -190,74 +218,82 @@ static int sr_logv(void *cb_data, int loglevel, const char *format, va_list args
 	return ret;
 }
 
+/** @private */
 SR_PRIV int sr_log(int loglevel, const char *format, ...)
 {
 	int ret;
 	va_list args;
 
 	va_start(args, format);
-	ret = sr_log_handler(sr_log_handler_data, loglevel, format, args);
+	ret = sr_log_callback(sr_log_callback_data, loglevel, format, args);
 	va_end(args);
 
 	return ret;
 }
 
+/** @private */
 SR_PRIV int sr_spew(const char *format, ...)
 {
 	int ret;
 	va_list args;
 
 	va_start(args, format);
-	ret = sr_log_handler(sr_log_handler_data, SR_LOG_SPEW, format, args);
+	ret = sr_log_callback(sr_log_callback_data, SR_LOG_SPEW, format, args);
 	va_end(args);
 
 	return ret;
 }
 
+/** @private */
 SR_PRIV int sr_dbg(const char *format, ...)
 {
 	int ret;
 	va_list args;
 
 	va_start(args, format);
-	ret = sr_log_handler(sr_log_handler_data, SR_LOG_DBG, format, args);
+	ret = sr_log_callback(sr_log_callback_data, SR_LOG_DBG, format, args);
 	va_end(args);
 
 	return ret;
 }
 
+/** @private */
 SR_PRIV int sr_info(const char *format, ...)
 {
 	int ret;
 	va_list args;
 
 	va_start(args, format);
-	ret = sr_log_handler(sr_log_handler_data, SR_LOG_INFO, format, args);
+	ret = sr_log_callback(sr_log_callback_data, SR_LOG_INFO, format, args);
 	va_end(args);
 
 	return ret;
 }
 
+/** @private */
 SR_PRIV int sr_warn(const char *format, ...)
 {
 	int ret;
 	va_list args;
 
 	va_start(args, format);
-	ret = sr_log_handler(sr_log_handler_data, SR_LOG_WARN, format, args);
+	ret = sr_log_callback(sr_log_callback_data, SR_LOG_WARN, format, args);
 	va_end(args);
 
 	return ret;
 }
 
+/** @private */
 SR_PRIV int sr_err(const char *format, ...)
 {
 	int ret;
 	va_list args;
 
 	va_start(args, format);
-	ret = sr_log_handler(sr_log_handler_data, SR_LOG_ERR, format, args);
+	ret = sr_log_callback(sr_log_callback_data, SR_LOG_ERR, format, args);
 	va_end(args);
 
 	return ret;
 }
+
+/** @} */