X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fplugin%2Fplugin.h;h=d0816261e90ebcdf93f4ac4abca279ab36a8c90a;hb=38d02a17cb959fe5cda3ef5c5522ebee3b9a50b3;hp=9c2c5f00606bb581b397e8a243bba9aeff30d7a6;hpb=90354d3a48e8659a3550bf6edf8d714323855a7d;p=babeltrace.git

diff --git a/include/babeltrace/plugin/plugin.h b/include/babeltrace/plugin/plugin.h
index 9c2c5f00..d0816261 100644
--- a/include/babeltrace/plugin/plugin.h
+++ b/include/babeltrace/plugin/plugin.h
@@ -2,7 +2,7 @@
 #define BABELTRACE_PLUGIN_H
 
 /*
- * BabelTrace - Plug-in
+ * BabelTrace - Babeltrace Plug-in Interface
  *
  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
  *
@@ -27,44 +27,106 @@
  * SOFTWARE.
  */
 
-#include <stdint.h>
+#include <stdio.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-struct bt_plugin;
-struct bt_notification;
-
+/**
+ * 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,
+	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 {
+	/** Memory allocation failure. */
+	/* -12 for compatibility with -ENOMEM */
+	BT_PLUGIN_STATUS_NOMEM =	-12,
+
+	/** Invalid arguments. */
+	/* -22 for compatibility with -EINVAL */
+	BT_PLUGIN_STATUS_INVAL =	-22,
+
+	/** Unsupported plug-in feature. */
+	BT_PLUGIN_STATUS_UNSUPPORTED =	-2,
+
+	/** General error. */
+	BT_PLUGIN_STATUS_ERROR =	-1,
+
+	/** No error, okay. */
+	BT_PLUGIN_STATUS_OK =		0,
 };
 
+struct bt_plugin;
+
+/**
+ * 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);
+
 /**
- * Plug-in discovery functions.
+ * Set plug-in instance name.
  *
- * The Babeltrace plug-in architecture mandates that a given plug-in shared
- * object only define one plug-in. These functions are used to query a about
- * shared object about its attributes.
+ * @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);
+
+/**
+ * Set a plug-in instance's error stream.
  *
- * The functions marked as mandatory MUST be exported by the shared object
- * to be considered a valid plug-in.
+ * @param plugin	Plug-in instance
+ * @param error_stream	Error stream
+ * @returns		One of #bt_plugin_status values
  */
-enum bt_plugin_type bt_plugin_get_type(void);
-const char *bt_plugin_get_name(void);
+extern enum bt_plugin_status bt_plugin_set_error_stream(
+		struct bt_plugin *plugin, FILE *error_stream);
 
-/* TODO: document mandatory fields and their expected types */
-int bt_plugin_set_parameters(struct bt_plugin *plugin,
-		struct bt_ctf_field *field);
+/**
+ * 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);
 
-void bt_plugin_get(struct bt_plugin *plugin);
-void bt_plugin_put(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
 }