From 0db5ca2cef921923e43f3c10e1a6a803e4e5df0d Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Wed, 13 May 2015 17:47:23 -0400 Subject: [PATCH] Document plug-in interface MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérémie Galarneau --- include/babeltrace/plugin/filter-internal.h | 0 include/babeltrace/plugin/filter.h | 0 .../babeltrace/plugin/notification/iterator.h | 9 +- include/babeltrace/plugin/plugin-internal.h | 5 +- include/babeltrace/plugin/plugin-lib.h | 17 +--- include/babeltrace/plugin/plugin.h | 93 ++++++++++++++++++- include/babeltrace/plugin/sink-internal.h | 0 include/babeltrace/plugin/source-internal.h | 0 include/babeltrace/plugin/source.h | 2 +- 9 files changed, 101 insertions(+), 25 deletions(-) create mode 100644 include/babeltrace/plugin/filter-internal.h create mode 100644 include/babeltrace/plugin/filter.h create mode 100644 include/babeltrace/plugin/sink-internal.h create mode 100644 include/babeltrace/plugin/source-internal.h diff --git a/include/babeltrace/plugin/filter-internal.h b/include/babeltrace/plugin/filter-internal.h new file mode 100644 index 00000000..e69de29b diff --git a/include/babeltrace/plugin/filter.h b/include/babeltrace/plugin/filter.h new file mode 100644 index 00000000..e69de29b diff --git a/include/babeltrace/plugin/notification/iterator.h b/include/babeltrace/plugin/notification/iterator.h index 47e8bae5..0086a1a1 100644 --- 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 2a60ea12..93c9c525 100644 --- a/include/babeltrace/plugin/plugin-internal.h +++ b/include/babeltrace/plugin/plugin-internal.h @@ -27,7 +27,8 @@ * SOFTWARE. */ -#include +#include +#include #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 8bafd263..4a741bd2 100644 --- a/include/babeltrace/plugin/plugin-lib.h +++ b/include/babeltrace/plugin/plugin-lib.h @@ -28,6 +28,7 @@ */ #include +#include #include #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 1c3c36d0..1080e2bb 100644 --- a/include/babeltrace/plugin/plugin.h +++ b/include/babeltrace/plugin/plugin.h @@ -27,19 +27,102 @@ * SOFTWARE. */ +#include + #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 index 00000000..e69de29b diff --git a/include/babeltrace/plugin/source-internal.h b/include/babeltrace/plugin/source-internal.h new file mode 100644 index 00000000..e69de29b diff --git a/include/babeltrace/plugin/source.h b/include/babeltrace/plugin/source.h index f5ff48a1..1e2176a9 100644 --- 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 * -- 2.34.1