Document plug-in interface

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/include/babeltrace/plugin/filter-internal.h b/include/babeltrace/plugin/filter-internal.h
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/include/babeltrace/plugin/filter.h b/include/babeltrace/plugin/filter.h
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/include/babeltrace/plugin/notification/iterator.h b/include/babeltrace/plugin/notification/iterator.h
index 47e8bae5b1f5116e3fe865e8cb17a8648c5f139b..0086a1a11ad16cb4f277d463a803032ef58bba62 100644 (file)
--- a/include/babeltrace/plugin/notification/iterator.h
+++ b/include/babeltrace/plugin/notification/iterator.h
@@ -36,13 +36,14 @@ extern "C" {
 struct bt_notification;
 struct bt_notification_iterator;
 
-int bt_notification_iterator_next(struct bt_notification_iterator *iterator);
+extern enum bt_notification_iterator_status
+bt_notification_iterator_next(struct bt_notification_iterator *iterator);
 
-struct bt_notification *bt_notification_iterator_get_notification(
+extern struct bt_notification *bt_notification_iterator_get_notification(
                struct bt_notification_iterator *iterator);
 
-void bt_notification_iterator_get(struct bt_notification_iterator *iterator);
-void bt_notification_iterator_put(struct bt_notification_iterator *iterator);
+extern void bt_notification_iterator_get(struct bt_notification_iterator *iterator);
+extern void bt_notification_iterator_put(struct bt_notification_iterator *iterator);
 
 /* API for plug-in authors */
 struct bt_notification_iterator *bt_notification_iterator_create(

diff --git a/include/babeltrace/plugin/plugin-internal.h b/include/babeltrace/plugin/plugin-internal.h
index 2a60ea1292edb6fbefc59618843108e29e42b1b6..93c9c525e98544ffa0bf84ad6ba43568f834bd78 100644 (file)
--- a/include/babeltrace/plugin/plugin-internal.h
+++ b/include/babeltrace/plugin/plugin-internal.h
@@ -27,7 +27,8 @@
  * SOFTWARE.
  */
 
-#include <stdint.h>
+#include <babeltrace/babeltrace-internal.h>
+#include <glib.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -36,7 +37,7 @@ extern "C" {
 struct bt_notification;
 
 struct bt_plugin {
-       const char * name;
+       GString *name;
        enum bt_plugin_type type;
 
        /* Plug-in specific callbacks */

diff --git a/include/babeltrace/plugin/plugin-lib.h b/include/babeltrace/plugin/plugin-lib.h
index 8bafd263ba6ec8949e840f849779269ff2d34e5d..4a741bd2a23eddb9da570699d2bdc548c264a7e3 100644 (file)
--- a/include/babeltrace/plugin/plugin-lib.h
+++ b/include/babeltrace/plugin/plugin-lib.h
@@ -28,6 +28,7 @@
  */
 
 #include <babeltrace/objects.h>
+#include <babeltrace/plugin.h>
 #include <stdint.h>
 
 #ifdef __cplusplus
@@ -37,16 +38,6 @@ extern "C" {
 struct bt_plugin;
 struct bt_notification;
 
-enum bt_plugin_type {
-       BT_PLUGIN_TYPE_UNKNOWN = -1,
-       /* A source plug-in is a notification generator. */
-       BT_PLUGIN_TYPE_SOURCE = 0,
-       /* A sink plug-in handles incoming notifications. */
-       BT_PLUGIN_TYPE_SINK = 1,
-       /* A filter plug-in implements both SOURCE and SINK interfaces. */
-       BT_PLUGIN_TYPE_FILTER = 2,
-};
-
 /**
  * Plug-in discovery functions.
  *
@@ -57,8 +48,8 @@ enum bt_plugin_type {
  * The functions marked as mandatory MUST be exported by the shared object
  * to be considered a valid plug-in.
  */
-enum bt_plugin_type bt_plugin_lib_get_type(void);
-const char *bt_plugin_lib_get_format_name(void);
+extern enum bt_plugin_type bt_plugin_lib_get_type(void);
+extern const char *bt_plugin_lib_get_format_name(void);
 
 /**
  * Create a plug-in instance configured with the provided parameters.
@@ -66,7 +57,7 @@ const char *bt_plugin_lib_get_format_name(void);
  * @param params       Map object of configuration parameters
  * @returns            An instance of the plug-in
  */
-struct bt_plugin *bt_plugin_lib_create(struct bt_object *params);
+extern struct bt_plugin *bt_plugin_lib_create(struct bt_object *params);
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace/plugin/plugin.h b/include/babeltrace/plugin/plugin.h
index 1c3c36d0ac734b5644735b16ccd90b9074a4fed6..1080e2bb2f2b1e93ac2bce1877f348897dc1bf7d 100644 (file)
--- a/include/babeltrace/plugin/plugin.h
+++ b/include/babeltrace/plugin/plugin.h
@@ -27,19 +27,102 @@
  * SOFTWARE.
  */
 
+#include <errno.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * Plug-in type.
+ */
+enum bt_plugin_type {
+       BT_PLUGIN_TYPE_UNKNOWN =        -1,
+
+       /* A source plug-in is a notification generator. */
+       BT_PLUGIN_TYPE_SOURCE =         0,
+
+       /* A sink plug-in handles incoming notifications. */
+       BT_PLUGIN_TYPE_SINK =           1,
+
+       /* A filter plug-in implements both Source and Sink interfaces. */
+       BT_PLUGIN_TYPE_FILTER =         2,
+};
+
+/**
+ * Status code. Errors are always negative.
+ */
+enum bt_plugin_status {
+       /* -12 for compatibility with -ENOMEM */
+       BT_PLUGIN_STATUS_NOMEM =        -12,
+
+       /* -22 for compatibility with -EINVAL */
+       BT_PLUGIN_STATUS_INVAL =        -22,
+
+       BT_PLUGIN_STATUS_UNSUPPORTED =  -2,
+
+       BT_PLUGIN_STATUS_ERROR =        -1,
+
+       BT_PLUGIN_STATUS_OK =           0,
+}
+
+/**
+ * Get plug-in instance name
+ *
+ * @param plugin       Plug-in instance of which to get the name
+ * @returns            Returns a pointer to the plug-in's name
+ */
+extern const char *bt_plugin_get_name(struct bt_plugin *plugin);
+
+/**
+ * Set plug-in instance name
+ *
+ * @param plugin       Plug-in instance of which to set the name
+ * @param name         New plug-in name (will be copied)
+ * @returns            One of #bt_plugin_status values
+ */
+extern enum bt_plugin_status bt_plugin_set_name(
+               struct bt_plugin *plugin, const char *name);
+
+/**
+ * Get plug-in instance type
+ *
+ * @param plugin       Plug-in instance of which to get the type
+ * @returns            One of #bt_plugin_type values
+ */
+extern enum bt_plugin_type bt_plugin_get_type(struct bt_plugin *plugin);
 
-int bt_plugin_set_error_stream(struct bt_plugin *plugin, FILE *error_stream);
+/**
+ * Set a plug-in instance's error stream
+ *
+ * @param plugin       Plug-in instance
+ * @param error_stream Error stream
+ * @returns            One of #bt_plugin_status values
+ */
+extern enum bt_plugin_status bt_plugin_set_error_stream(
+               struct bt_plugin *plugin, FILE *error_stream);
 
-/* Refcounting */
-void bt_plugin_get(struct bt_plugin *plugin);
-void bt_plugin_put(struct bt_plugin *plugin);
+/**
+ * Increments the reference count of \p plugin.
+ *
+ * @param plugin       Plug-in of which to increment the reference count
+ *
+ * @see bt_plugin_put()
+ */
+extern void bt_plugin_get(struct bt_plugin *plugin);
+
+/**
+ * Decrements the reference count of \p plugin, destroying it when this
+ * count reaches 0.
+ *
+ * @param plugin       Plug-in of which to decrement the reference count
+ *
+ * @see bt_plugin_get()
+ */
+extern void bt_plugin_put(struct bt_plugin *plugin);
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif /* BABELTRACE_PLUGIN_SYSTEM_H */
+#endif /* BABELTRACE_PLUGIN_H */

diff --git a/include/babeltrace/plugin/sink-internal.h b/include/babeltrace/plugin/sink-internal.h
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/include/babeltrace/plugin/source-internal.h b/include/babeltrace/plugin/source-internal.h
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/include/babeltrace/plugin/source.h b/include/babeltrace/plugin/source.h
index f5ff48a16195872b4300627b845f3ccc038d8290..1e2176a9805f3d7495d6a2a366244b256d842d6e 100644 (file)
--- a/include/babeltrace/plugin/source.h
+++ b/include/babeltrace/plugin/source.h
@@ -2,7 +2,7 @@
 #define BABELTRACE_PLUGIN_SOURCE_H
 
 /*
- * BabelTrace - Source Plug-in
+ * BabelTrace - Source Plug-in Interface
  *
  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
  *