src/transform/transform.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2014 Bert Vermeulen <bert@biot.com>
   5  * Copyright (C) 2015 Uwe Hermann <uwe@hermann-uwe.de>
   6  *
   7  * This program is free software: you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation, either version 3 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #include <string.h>
  22 #include "libsigrok.h"
  23 #include "libsigrok-internal.h"
  24
  25 #define LOG_PREFIX "transform"
  26
  27 /**
  28  * @file
  29  *
  30  * Transform module handling.
  31  */
  32
  33 /**
  34  * @defgroup grp_transform Transform modules
  35  *
  36  * Transform module handling.
  37  *
  38  * @{
  39  */
  40
  41 /** @cond PRIVATE */
  42 /* @endcond */
  43
  44 static const struct sr_transform_module *transform_module_list[] = {
  45         NULL,
  46 };
  47
  48 /**
  49  * Returns a NULL-terminated list of all available transform modules.
  50  *
  51  * @since 0.4.0
  52  */
  53 SR_API const struct sr_transform_module **sr_transform_list(void)
  54 {
  55         return transform_module_list;
  56 }
  57
  58 /**
  59  * Returns the specified transform module's ID.
  60  *
  61  * @since 0.4.0
  62  */
  63 SR_API const char *sr_transform_id_get(const struct sr_transform_module *tmod)
  64 {
  65         if (!tmod) {
  66                 sr_err("Invalid transform module NULL!");
  67                 return NULL;
  68         }
  69
  70         return tmod->id;
  71 }
  72
  73 /**
  74  * Returns the specified transform module's name.
  75  *
  76  * @since 0.4.0
  77  */
  78 SR_API const char *sr_transform_name_get(const struct sr_transform_module *tmod)
  79 {
  80         if (!tmod) {
  81                 sr_err("Invalid transform module NULL!");
  82                 return NULL;
  83         }
  84
  85         return tmod->name;
  86 }
  87
  88 /**
  89  * Returns the specified transform module's description.
  90  *
  91  * @since 0.4.0
  92  */
  93 SR_API const char *sr_transform_description_get(const struct sr_transform_module *tmod)
  94 {
  95         if (!tmod) {
  96                 sr_err("Invalid transform module NULL!");
  97                 return NULL;
  98         }
  99
 100         return tmod->desc;
 101 }
 102
 103 /**
 104  * Return the transform module with the specified ID, or NULL if no module
 105  * with that ID is found.
 106  *
 107  * @since 0.4.0
 108  */
 109 SR_API const struct sr_transform_module *sr_transform_find(const char *id)
 110 {
 111         int i;
 112
 113         for (i = 0; transform_module_list[i]; i++) {
 114                 if (!strcmp(transform_module_list[i]->id, id))
 115                         return transform_module_list[i];
 116         }
 117
 118         return NULL;
 119 }
 120
 121 /**
 122  * Returns a NULL-terminated array of struct sr_option, or NULL if the
 123  * module takes no options.
 124  *
 125  * Each call to this function must be followed by a call to
 126  * sr_transform_options_free().
 127  *
 128  * @since 0.4.0
 129  */
 130 SR_API const struct sr_option **sr_transform_options_get(const struct sr_transform_module *tmod)
 131 {
 132         const struct sr_option *mod_opts, **opts;
 133         int size, i;
 134
 135         if (!tmod || !tmod->options)
 136                 return NULL;
 137
 138         mod_opts = tmod->options();
 139
 140         for (size = 0; mod_opts[size].id; size++)
 141                 ;
 142         opts = g_malloc((size + 1) * sizeof(struct sr_option *));
 143
 144         for (i = 0; i < size; i++)
 145                 opts[i] = &mod_opts[i];
 146         opts[i] = NULL;
 147
 148         return opts;
 149 }
 150
 151 /**
 152  * After a call to sr_transform_options_get(), this function cleans up all
 153  * resources returned by that call.
 154  *
 155  * @since 0.4.0
 156  */
 157 SR_API void sr_transform_options_free(const struct sr_option **options)
 158 {
 159         int i;
 160
 161         if (!options)
 162                 return;
 163
 164         for (i = 0; options[i]; i++) {
 165                 if (options[i]->def) {
 166                         g_variant_unref(options[i]->def);
 167                         ((struct sr_option *)options[i])->def = NULL;
 168                 }
 169
 170                 if (options[i]->values) {
 171                         g_slist_free_full(options[i]->values, (GDestroyNotify)g_variant_unref);
 172                         ((struct sr_option *)options[i])->values = NULL;
 173                 }
 174         }
 175         g_free(options);
 176 }
 177
 178 /**
 179  * Create a new transform instance using the specified transform module.
 180  *
 181  * <code>options</code> is a *GHashTable with the keys corresponding with
 182  * the module options' <code>id</code> field. The values should be GVariant
 183  * pointers with sunk * references, of the same GVariantType as the option's
 184  * default value.
 185  *
 186  * The sr_dev_inst passed in can be used by the instance to determine
 187  * channel names, samplerate, and so on.
 188  *
 189  * @since 0.4.0
 190  */
 191 SR_API const struct sr_transform *sr_transform_new(const struct sr_transform_module *tmod,
 192                 GHashTable *options, const struct sr_dev_inst *sdi)
 193 {
 194         struct sr_transform *t;
 195         const struct sr_option *mod_opts;
 196         const GVariantType *gvt;
 197         GHashTable *new_opts;
 198         GHashTableIter iter;
 199         gpointer key, value;
 200         int i;
 201
 202         t = g_malloc(sizeof(struct sr_transform));
 203         t->module = tmod;
 204         t->sdi = sdi;
 205
 206         new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
 207                         (GDestroyNotify)g_variant_unref);
 208         if (tmod->options) {
 209                 mod_opts = tmod->options();
 210                 for (i = 0; mod_opts[i].id; i++) {
 211                         if (options && g_hash_table_lookup_extended(options,
 212                                         mod_opts[i].id, &key, &value)) {
 213                                 /* Pass option along. */
 214                                 gvt = g_variant_get_type(mod_opts[i].def);
 215                                 if (!g_variant_is_of_type(value, gvt)) {
 216                                         sr_err("Invalid type for '%s' option.", key);
 217                                         g_free(t);
 218                                         return NULL;
 219                                 }
 220                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 221                                                 g_variant_ref(value));
 222                         } else {
 223                                 /* Option not given: insert the default value. */
 224                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 225                                                 g_variant_ref(mod_opts[i].def));
 226                         }
 227                 }
 228
 229                 /* Make sure no invalid options were given. */
 230                 if (options) {
 231                         g_hash_table_iter_init(&iter, options);
 232                         while (g_hash_table_iter_next(&iter, &key, &value)) {
 233                                 if (!g_hash_table_lookup(new_opts, key)) {
 234                                         sr_err("Transform module '%s' has no option '%s'.", tmod->id, key);
 235                                         g_hash_table_destroy(new_opts);
 236                                         g_free(t);
 237                                         return NULL;
 238                                 }
 239                         }
 240                 }
 241         }
 242
 243         if (t->module->init && t->module->init(t, new_opts) != SR_OK) {
 244                 g_free(t);
 245                 t = NULL;
 246         }
 247         if (new_opts)
 248                 g_hash_table_destroy(new_opts);
 249
 250         return t;
 251 }
 252
 253 /**
 254  * Free the specified transform instance and all associated resources.
 255  *
 256  * @since 0.4.0
 257  */
 258 SR_API int sr_transform_free(const struct sr_transform *t)
 259 {
 260         int ret;
 261
 262         if (!t)
 263                 return SR_ERR_ARG;
 264
 265         ret = SR_OK;
 266         if (t->module->cleanup)
 267                 ret = t->module->cleanup((struct sr_transform *)t);
 268         g_free((gpointer)t);
 269
 270         return ret;
 271 }
 272
 273 /** @} */