Add API for and default handler for debug messages.

[libserialport.git] / libserialport.h.in

diff --git a/libserialport.h.in b/libserialport.h.in
index 0e3dc1b1968f67324b83785fe13afd0bf42953ac..3de68a9830cc325918e5bc64985705cbe544c467 100644 (file)
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -615,6 +615,29 @@ char *sp_last_error_message(void);
  */
 void sp_free_error_message(char *message);
 
+/**
+ * Set the handler function for library debugging messages.
+ *
+ * Debugging messages are generated by the library during each operation,
+ * to help in diagnosing problems. The handler will be called for each
+ * message. The handler can be set to NULL to ignore all debug messages.
+ *
+ * The handler function should accept a format string and variable length
+ * argument list, in the same manner as e.g. printf().
+ *
+ * The default handler is sp_default_debug_handler().
+ */
+void sp_set_debug_handler(void (*handler)(const char *format, ...));
+
+/**
+ * Default handler function for library debugging messages.
+ *
+ * This function prints debug messages to the standard error stream if the
+ * environment variable LIBSERIALPORT_DEBUG is set. Otherwise, they are
+ * ignored.
+ */
+void sp_default_debug_handler(const char *format, ...);
+
 /** @} */
 
 #ifdef __cplusplus