/*
* This file is part of the libsigrok project.
*
- * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
+ * Copyright (C) 2014 Bert Vermeulen <bert@biot.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
-#include "libsigrok.h"
+#include <config.h>
+#include <string.h>
+#include <libsigrok/libsigrok.h>
#include "libsigrok-internal.h"
+/** @cond PRIVATE */
+#define LOG_PREFIX "output"
+/** @endcond */
+
/**
* @file
*
- * Output file/data format handling.
+ * Output module handling.
*/
/**
- * @defgroup grp_output Output formats
+ * @defgroup grp_output Output modules
*
- * Output file/data format handling.
+ * Output module handling.
*
- * libsigrok supports several output (file) formats, e.g. binary, VCD,
- * gnuplot, and so on. It provides an output API that frontends can use.
- * New output formats can be added/implemented in libsigrok without having
+ * libsigrok supports several output modules for file formats such as binary,
+ * VCD, csv, and so on. It provides an output API that frontends can use.
+ * New output modules can be added/implemented in libsigrok without having
* to change the frontends at all.
*
* All output modules are fed data in a stream. Devices that can stream data
*/
/** @cond PRIVATE */
-extern SR_PRIV struct sr_output_format output_bits;
-extern SR_PRIV struct sr_output_format output_hex;
-extern SR_PRIV struct sr_output_format output_ascii;
-extern SR_PRIV struct sr_output_format output_binary;
-extern SR_PRIV struct sr_output_format output_vcd;
-extern SR_PRIV struct sr_output_format output_ols;
-extern SR_PRIV struct sr_output_format output_gnuplot;
-extern SR_PRIV struct sr_output_format output_chronovu_la8;
-extern SR_PRIV struct sr_output_format output_csv;
-extern SR_PRIV struct sr_output_format output_analog;
+extern SR_PRIV struct sr_output_module output_bits;
+extern SR_PRIV struct sr_output_module output_hex;
+extern SR_PRIV struct sr_output_module output_ascii;
+extern SR_PRIV struct sr_output_module output_binary;
+extern SR_PRIV struct sr_output_module output_vcd;
+extern SR_PRIV struct sr_output_module output_ols;
+extern SR_PRIV struct sr_output_module output_chronovu_la8;
+extern SR_PRIV struct sr_output_module output_csv;
+extern SR_PRIV struct sr_output_module output_analog;
+extern SR_PRIV struct sr_output_module output_srzip;
+extern SR_PRIV struct sr_output_module output_wav;
+extern SR_PRIV struct sr_output_module output_null;
/* @endcond */
-static struct sr_output_format *output_module_list[] = {
+static const struct sr_output_module *output_module_list[] = {
&output_ascii,
&output_binary,
&output_bits,
&output_csv,
- &output_gnuplot,
&output_hex,
&output_ols,
&output_vcd,
&output_chronovu_la8,
&output_analog,
+ &output_srzip,
+ &output_wav,
+ &output_null,
NULL,
};
-/** @since 0.1.0 */
-SR_API struct sr_output_format **sr_output_list(void)
+/**
+ * Returns a NULL-terminated list of all available output modules.
+ *
+ * @since 0.4.0
+ */
+SR_API const struct sr_output_module **sr_output_list(void)
{
return output_module_list;
}
-/** @since 0.3.0 */
-SR_API struct sr_output *sr_output_new(struct sr_output_format *of,
- GHashTable *params, const struct sr_dev_inst *sdi)
+/**
+ * Returns the specified output module's ID.
+ *
+ * @since 0.4.0
+ */
+SR_API const char *sr_output_id_get(const struct sr_output_module *omod)
+{
+ if (!omod) {
+ sr_err("Invalid output module NULL!");
+ return NULL;
+ }
+
+ return omod->id;
+}
+
+/**
+ * Returns the specified output module's name.
+ *
+ * @since 0.4.0
+ */
+SR_API const char *sr_output_name_get(const struct sr_output_module *omod)
+{
+ if (!omod) {
+ sr_err("Invalid output module NULL!");
+ return NULL;
+ }
+
+ return omod->name;
+}
+
+/**
+ * Returns the specified output module's description.
+ *
+ * @since 0.4.0
+ */
+SR_API const char *sr_output_description_get(const struct sr_output_module *omod)
+{
+ if (!omod) {
+ sr_err("Invalid output module NULL!");
+ return NULL;
+ }
+
+ return omod->desc;
+}
+
+/**
+ * Returns the specified output module's file extensions typical for the file
+ * format, as a NULL terminated array, or returns a NULL pointer if there is
+ * no preferred extension.
+ * @note these are a suggestions only.
+ *
+ * @since 0.4.0
+ */
+SR_API const char *const *sr_output_extensions_get(
+ const struct sr_output_module *omod)
+{
+ if (!omod) {
+ sr_err("Invalid output module NULL!");
+ return NULL;
+ }
+
+ return omod->exts;
+}
+
+/*
+ * Checks whether a given flag is set.
+ *
+ * @see sr_output_flag
+ * @since 0.4.0
+ */
+SR_API gboolean sr_output_test_flag(const struct sr_output_module *omod,
+ uint64_t flag)
+{
+ return (flag & omod->flags);
+}
+
+/**
+ * Return the output module with the specified ID, or NULL if no module
+ * with that id is found.
+ *
+ * @since 0.4.0
+ */
+SR_API const struct sr_output_module *sr_output_find(char *id)
+{
+ int i;
+
+ for (i = 0; output_module_list[i]; i++) {
+ if (!strcmp(output_module_list[i]->id, id))
+ return output_module_list[i];
+ }
+
+ return NULL;
+}
+
+/**
+ * Returns a NULL-terminated array of struct sr_option, or NULL if the
+ * module takes no options.
+ *
+ * Each call to this function must be followed by a call to
+ * sr_output_options_free().
+ *
+ * @since 0.4.0
+ */
+SR_API const struct sr_option **sr_output_options_get(const struct sr_output_module *omod)
+{
+ const struct sr_option *mod_opts, **opts;
+ int size, i;
+
+ if (!omod || !omod->options)
+ return NULL;
+
+ mod_opts = omod->options();
+
+ for (size = 0; mod_opts[size].id; size++)
+ ;
+ opts = g_malloc((size + 1) * sizeof(struct sr_option *));
+
+ for (i = 0; i < size; i++)
+ opts[i] = &mod_opts[i];
+ opts[i] = NULL;
+
+ return opts;
+}
+
+/**
+ * After a call to sr_output_options_get(), this function cleans up all
+ * resources returned by that call.
+ *
+ * @since 0.4.0
+ */
+SR_API void sr_output_options_free(const struct sr_option **options)
+{
+ int i;
+
+ if (!options)
+ return;
+
+ for (i = 0; options[i]; i++) {
+ if (options[i]->def) {
+ g_variant_unref(options[i]->def);
+ ((struct sr_option *)options[i])->def = NULL;
+ }
+
+ if (options[i]->values) {
+ g_slist_free_full(options[i]->values, (GDestroyNotify)g_variant_unref);
+ ((struct sr_option *)options[i])->values = NULL;
+ }
+ }
+ g_free(options);
+}
+
+/**
+ * Create a new output instance using the specified output module.
+ *
+ * <code>options</code> is a *HashTable with the keys corresponding with
+ * the module options' <code>id</code> field. The values should be GVariant
+ * pointers with sunk * references, of the same GVariantType as the option's
+ * default value.
+ *
+ * The sr_dev_inst passed in can be used by the instance to determine
+ * channel names, samplerate, and so on.
+ *
+ * @since 0.4.0
+ */
+SR_API const struct sr_output *sr_output_new(const struct sr_output_module *omod,
+ GHashTable *options, const struct sr_dev_inst *sdi,
+ const char *filename)
{
- struct sr_output *o;
-
- o = g_malloc(sizeof(struct sr_output));
- o->format = of;
- o->sdi = sdi;
- o->params = params;
- if (o->format->init && o->format->init(o) != SR_OK) {
- g_free(o);
- o = NULL;
+ struct sr_output *op;
+ const struct sr_option *mod_opts;
+ const GVariantType *gvt;
+ GHashTable *new_opts;
+ GHashTableIter iter;
+ gpointer key, value;
+ int i;
+
+ op = g_malloc(sizeof(struct sr_output));
+ op->module = omod;
+ op->sdi = sdi;
+ op->filename = g_strdup(filename);
+
+ new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
+ (GDestroyNotify)g_variant_unref);
+ if (omod->options) {
+ mod_opts = omod->options();
+ for (i = 0; mod_opts[i].id; i++) {
+ if (options && g_hash_table_lookup_extended(options,
+ mod_opts[i].id, &key, &value)) {
+ /* Pass option along. */
+ gvt = g_variant_get_type(mod_opts[i].def);
+ if (!g_variant_is_of_type(value, gvt)) {
+ sr_err("Invalid type for '%s' option.",
+ (char *)key);
+ g_free(op);
+ return NULL;
+ }
+ g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
+ g_variant_ref(value));
+ } else {
+ /* Option not given: insert the default value. */
+ g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
+ g_variant_ref(mod_opts[i].def));
+ }
+ }
+
+ /* Make sure no invalid options were given. */
+ if (options) {
+ g_hash_table_iter_init(&iter, options);
+ while (g_hash_table_iter_next(&iter, &key, &value)) {
+ if (!g_hash_table_lookup(new_opts, key)) {
+ sr_err("Output module '%s' has no option '%s'",
+ omod->id, (char *)key);
+ g_hash_table_destroy(new_opts);
+ g_free(op);
+ return NULL;
+ }
+ }
+ }
+ }
+
+ if (op->module->init && op->module->init(op, new_opts) != SR_OK) {
+ g_free(op);
+ op = NULL;
}
+ if (new_opts)
+ g_hash_table_destroy(new_opts);
- return o;
+ return op;
}
-/** @since 0.3.0 */
-SR_API int sr_output_send(struct sr_output *o,
+/**
+ * Send a packet to the specified output instance.
+ *
+ * The instance's output is returned as a newly allocated GString,
+ * which must be freed by the caller.
+ *
+ * @since 0.4.0
+ */
+SR_API int sr_output_send(const struct sr_output *o,
const struct sr_datafeed_packet *packet, GString **out)
{
- return o->format->receive(o, packet, out);
+ return o->module->receive(o, packet, out);
}
-/** @since 0.3.0 */
-SR_API int sr_output_free(struct sr_output *o)
+/**
+ * Free the specified output instance and all associated resources.
+ *
+ * @since 0.4.0
+ */
+SR_API int sr_output_free(const struct sr_output *o)
{
int ret;
+ if (!o)
+ return SR_ERR_ARG;
+
ret = SR_OK;
- if (o->format->cleanup)
- ret = o->format->cleanup(o);
- g_free(o);
+ if (o->module->cleanup)
+ ret = o->module->cleanup((struct sr_output *)o);
+ g_free((char *)o->filename);
+ g_free((gpointer)o);
return ret;
}
projects / libsigrok.git / blobdiff