diff options
| -rw-r--r-- | lib/experiment-reader/experiment-reader.c | 72 | ||||
| -rw-r--r-- | lib/experiment-reader/experiment-reader.h | 29 |
2 files changed, 87 insertions, 14 deletions
diff --git a/lib/experiment-reader/experiment-reader.c b/lib/experiment-reader/experiment-reader.c index d651c54..5559a56 100644 --- a/lib/experiment-reader/experiment-reader.c +++ b/lib/experiment-reader/experiment-reader.c @@ -1,3 +1,9 @@ +/** + * @file + * Auxiliary class to handle "session" XML files (augmented Folker). + * It is a GObject that must be freed using \e g_object_unref. + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -23,13 +29,16 @@ static gboolean generic_foreach_topic(xmlDoc *doc, xmlNodeSet *nodes, ExperimentReaderTopicCallback callback, gpointer data); +/** @private */ #define EXPERIMENT_READER_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), EXPERIMENT_TYPE_READER, ExperimentReaderPrivate)) +/** @private */ struct _ExperimentReaderPrivate { xmlDoc *doc; }; +/** @private */ GType experiment_reader_get_type(void) { @@ -150,6 +159,12 @@ generic_foreach_topic(xmlDoc *doc, xmlNodeSet *nodes, * API */ +/** + * Constructs a new ExperimentReader object. + * + * @param filename Filename of XML file to open + * @return A new \e ExperimentReader object. Free with \e g_object_unref. + */ ExperimentReader * experiment_reader_new(const gchar *filename) { @@ -162,15 +177,23 @@ experiment_reader_new(const gchar *filename) return NULL; } - /* TODO: validate against session.dtd */ + /** @todo validate against session.dtd */ return reader; } +/** + * Calls \e callback with \e userdata for each \b topic in the \b greetings + * section of the experiment. + * + * @param reader \e ExperimentReader instance + * @param callback Function to invoke + * @param userdata User data to pass to \e callback + */ void experiment_reader_foreach_greeting_topic(ExperimentReader *reader, ExperimentReaderTopicCallback callback, - gpointer data) + gpointer userdata) { xmlXPathContext *xpathCtx; xmlXPathObject *xpathObj; @@ -180,17 +203,26 @@ experiment_reader_foreach_greeting_topic(ExperimentReader *reader, xpathCtx); generic_foreach_topic(reader->priv->doc, xpathObj->nodesetval, - callback, data); + callback, userdata); xmlXPathFreeObject(xpathObj); xmlXPathFreeContext(xpathCtx); } +/** + * Calls \e callback with \e userdata for each \b topic in the + * \b initial-narrative subsection of the \b experiment section of + * the experiment. + * + * @param reader \e ExperimentReader instance + * @param callback Function to invoke + * @param userdata User data to pass to \e callback + */ void -experiment_reader_foreach_exp_initial_narrative_topic(reader, callback, data) +experiment_reader_foreach_exp_initial_narrative_topic(reader, callback, userdata) ExperimentReader *reader; ExperimentReaderTopicCallback callback; - gpointer data; + gpointer userdata; { xmlXPathContext *xpathCtx; xmlXPathObject *xpathObj; @@ -201,18 +233,28 @@ experiment_reader_foreach_exp_initial_narrative_topic(reader, callback, data) xpathCtx); generic_foreach_topic(reader->priv->doc, xpathObj->nodesetval, - callback, data); + callback, userdata); xmlXPathFreeObject(xpathObj); xmlXPathFreeContext(xpathCtx); } +/** + * Calls \e callback with \e userdata for each \b topic in a \b phase of + * the \b last-minute subsection of the \b experiment section of + * the experiment. + * + * @param reader \e ExperimentReader instance + * @param phase \b Phase section (integer between 1 and 6) + * @param callback Function to invoke + * @param userdata User data to pass to \e callback + */ void -experiment_reader_foreach_exp_last_minute_phase_topic(reader, phase, callback, data) +experiment_reader_foreach_exp_last_minute_phase_topic(reader, phase, callback, userdata) ExperimentReader *reader; gint phase; ExperimentReaderTopicCallback callback; - gpointer data; + gpointer userdata; { xmlXPathContext *xpathCtx; xmlXPathObject *xpathObj; @@ -229,16 +271,24 @@ experiment_reader_foreach_exp_last_minute_phase_topic(reader, phase, callback, d xpathObj = xmlXPathEvalExpression(expr, xpathCtx); generic_foreach_topic(reader->priv->doc, xpathObj->nodesetval, - callback, data); + callback, userdata); xmlXPathFreeObject(xpathObj); xmlXPathFreeContext(xpathCtx); } +/** + * Calls \e callback with \e userdata for each \b topic in the \b farewell + * section of the experiment. + * + * @param reader \e ExperimentReader instance + * @param callback Function to invoke + * @param userdata User data to pass to \e callback + */ void experiment_reader_foreach_farewell_topic(ExperimentReader *reader, ExperimentReaderTopicCallback callback, - gpointer data) + gpointer userdata) { xmlXPathContext *xpathCtx; xmlXPathObject *xpathObj; @@ -248,7 +298,7 @@ experiment_reader_foreach_farewell_topic(ExperimentReader *reader, xpathCtx); generic_foreach_topic(reader->priv->doc, xpathObj->nodesetval, - callback, data); + callback, userdata); xmlXPathFreeObject(xpathObj); xmlXPathFreeContext(xpathCtx); diff --git a/lib/experiment-reader/experiment-reader.h b/lib/experiment-reader/experiment-reader.h index 6a0cc85..99c5018 100644 --- a/lib/experiment-reader/experiment-reader.h +++ b/lib/experiment-reader/experiment-reader.h @@ -1,3 +1,8 @@ +/** + * @file + * Header file to include when using the \e ExperimentReader class. + */ + #ifndef __EXPERIMENT_READER_H #define __EXPERIMENT_READER_H @@ -8,6 +13,11 @@ G_BEGIN_DECLS #define EXPERIMENT_TYPE_READER \ (experiment_reader_get_type()) +/** + * Cast instance pointer to \e ExperimentReader + * + * @param obj Object to cast to \e ExperimentReader + */ #define EXPERIMENT_READER(obj) \ (G_TYPE_CHECK_INSTANCE_CAST((obj), EXPERIMENT_TYPE_READER, ExperimentReader)) #define EXPERIMENT_READER_CLASS(klass) \ @@ -19,16 +29,23 @@ G_BEGIN_DECLS #define EXPERIMENT_READER_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS((obj), EXPERIMENT_TYPE_READER, ExperimentReaderClass)) +/** @private */ typedef struct _ExperimentReaderPrivate ExperimentReaderPrivate; +/** + * \e ExperimentReader instance structure + */ typedef struct _ExperimentReader { - GObject parent_instance; + GObject parent_instance; /**< Parent instance structure */ - ExperimentReaderPrivate *priv; /** private */ + ExperimentReaderPrivate *priv; /**< @private */ } ExperimentReader; +/** + * \e ExperimentReader class structure + */ typedef struct _ExperimentReaderClass { - GObjectClass parent_class; + GObjectClass parent_class; /**< Parent class structure */ } ExperimentReaderClass; GType experiment_reader_get_type(void); @@ -36,6 +53,12 @@ GType experiment_reader_get_type(void); /* * Callbacks */ +/** + * Type of function to use for \b topic callbacks. + * + * @param topic_id Symbolic identifier of experiment \b topic + * @param start_time Beginning of first \b contribution in \e topic (milliseconds) + */ typedef void (*ExperimentReaderTopicCallback)(const gchar *topic_id, gint64 start_time, gpointer data); |