src/output/output.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #include <string.h>
  21 #include "libsigrok.h"
  22 #include "libsigrok-internal.h"
  23
  24 #define LOG_PREFIX "output"
  25
  26 /**
  27  * @file
  28  *
  29  * Output module handling.
  30  */
  31
  32 /**
  33  * @defgroup grp_output Output modules
  34  *
  35  * Output module handling.
  36  *
  37  * libsigrok supports several output modules for file formats such as binary,
  38  * VCD, gnuplot, and so on. It provides an output API that frontends can use.
  39  * New output modules can be added/implemented in libsigrok without having
  40  * to change the frontends at all.
  41  *
  42  * All output modules are fed data in a stream. Devices that can stream data
  43  * into libsigrok, instead of storing and then transferring the whole buffer,
  44  * can thus generate output live.
  45  *
  46  * Output modules generate a newly allocated GString. The caller is then
  47  * expected to free this with g_string_free() when finished with it.
  48  *
  49  * @{
  50  */
  51
  52 /** @cond PRIVATE */
  53 extern SR_PRIV struct sr_output_module output_bits;
  54 extern SR_PRIV struct sr_output_module output_hex;
  55 extern SR_PRIV struct sr_output_module output_ascii;
  56 extern SR_PRIV struct sr_output_module output_binary;
  57 extern SR_PRIV struct sr_output_module output_vcd;
  58 extern SR_PRIV struct sr_output_module output_ols;
  59 extern SR_PRIV struct sr_output_module output_gnuplot;
  60 extern SR_PRIV struct sr_output_module output_chronovu_la8;
  61 extern SR_PRIV struct sr_output_module output_csv;
  62 extern SR_PRIV struct sr_output_module output_analog;
  63 /* @endcond */
  64
  65 static const struct sr_output_module *output_module_list[] = {
  66         &output_ascii,
  67         &output_binary,
  68         &output_bits,
  69         &output_csv,
  70         &output_gnuplot,
  71         &output_hex,
  72         &output_ols,
  73         &output_vcd,
  74         &output_chronovu_la8,
  75         &output_analog,
  76         NULL,
  77 };
  78
  79 /**
  80  * Returns a NULL-terminated list of all the available output modules.
  81  *
  82  * @since 0.4.0
  83  */
  84 SR_API const struct sr_output_module **sr_output_list(void)
  85 {
  86         return output_module_list;
  87 }
  88
  89 /**
  90  * Returns the specified output module's ID.
  91  *
  92  * @since 0.4.0
  93  */
  94 SR_API const char *sr_output_id_get(const struct sr_output_module *o)
  95 {
  96         if (!o) {
  97                 sr_err("Invalid output module NULL!");
  98                 return NULL;
  99         }
 100
 101         return o->id;
 102 }
 103
 104 /**
 105  * Returns the specified output module's name.
 106  *
 107  * @since 0.4.0
 108  */
 109 SR_API const char *sr_output_name_get(const struct sr_output_module *o)
 110 {
 111         if (!o) {
 112                 sr_err("Invalid output module NULL!");
 113                 return NULL;
 114         }
 115
 116         return o->name;
 117 }
 118
 119 /**
 120  * Returns the specified output module's description.
 121  *
 122  * @since 0.4.0
 123  */
 124 SR_API const char *sr_output_description_get(const struct sr_output_module *o)
 125 {
 126         if (!o) {
 127                 sr_err("Invalid output module NULL!");
 128                 return NULL;
 129         }
 130
 131         return o->desc;
 132 }
 133
 134 /**
 135  * Return the output module with the specified ID, or NULL if no module
 136  * with that id is found.
 137  *
 138  * @since 0.4.0
 139  */
 140 SR_API const struct sr_output_module *sr_output_find(char *id)
 141 {
 142         int i;
 143
 144         for (i = 0; output_module_list[i]; i++) {
 145                 if (!strcmp(output_module_list[i]->id, id))
 146                         return output_module_list[i];
 147         }
 148
 149         return NULL;
 150 }
 151
 152 /**
 153  * Returns a NULL-terminated array of struct sr_option, or NULL if the
 154  * module takes no options.
 155  *
 156  * Each call to this function must be followed by a call to
 157  * sr_output_options_free().
 158  *
 159  * @since 0.4.0
 160  */
 161 SR_API const struct sr_option *sr_output_options_get(const struct sr_output_module *o)
 162 {
 163
 164         if (!o || !o->options)
 165                 return NULL;
 166
 167         return o->options(FALSE);
 168 }
 169
 170 /**
 171  * After a call to sr_output_options_get(), this function cleans up all
 172  * the resources allocated by that call.
 173  *
 174  * @since 0.4.0
 175  */
 176 SR_API void sr_output_options_free(const struct sr_output_module *o)
 177 {
 178         struct sr_option *opt;
 179
 180         if (!o || !o->options)
 181                 return;
 182
 183         for (opt = o->options(TRUE); opt->id; opt++) {
 184                 if (opt->def) {
 185                         g_variant_unref(opt->def);
 186                         opt->def = NULL;
 187                 }
 188
 189                 if (opt->values) {
 190                         g_slist_free_full(opt->values, (GDestroyNotify)g_variant_unref);
 191                         opt->values = NULL;
 192                 }
 193         }
 194 }
 195
 196 /**
 197  * Create a new output instance using the specified output module.
 198  *
 199  * <code>options</code> is a *HashTable with the keys corresponding with
 200  * the module options' <code>id</code> field. The values should be GVariant
 201  * pointers with sunk * references, of the same GVariantType as the option's
 202  * default value.
 203  *
 204  * The sr_dev_inst passed in can be used by the instance to determine
 205  * channel names, samplerate, and so on.
 206  *
 207  * @since 0.4.0
 208  */
 209 SR_API const struct sr_output *sr_output_new(const struct sr_output_module *o,
 210                 GHashTable *options, const struct sr_dev_inst *sdi)
 211 {
 212         struct sr_output *op;
 213
 214         op = g_malloc(sizeof(struct sr_output));
 215         op->module = o;
 216         op->sdi = sdi;
 217         if (op->module->init && op->module->init(op, options) != SR_OK) {
 218                 g_free(op);
 219                 op = NULL;
 220         }
 221
 222         return op;
 223 }
 224
 225 /**
 226  * Send a packet to the specified output instance.
 227  *
 228  * The instance's output is returned as a newly allocated GString,
 229  * which must be freed by the caller.
 230  *
 231  * @since 0.4.0
 232  */
 233 SR_API int sr_output_send(const struct sr_output *o,
 234                 const struct sr_datafeed_packet *packet, GString **out)
 235 {
 236         return o->module->receive(o, packet, out);
 237 }
 238
 239 /**
 240  * Free the specified output instance and all associated resources.
 241  *
 242  * @since 0.4.0
 243  */
 244 SR_API int sr_output_free(const struct sr_output *o)
 245 {
 246         int ret;
 247
 248         if (!o)
 249                 return SR_ERR_ARG;
 250
 251         ret = SR_OK;
 252         if (o->module->cleanup)
 253                 ret = o->module->cleanup((struct sr_output *)o);
 254         g_free((gpointer)o);
 255
 256         return ret;
 257 }
 258
 259 /** @} */