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/libsigrok.h>
  23 #include "libsigrok-internal.h"
  24
  25 /** @cond PRIVATE */
  26 #define LOG_PREFIX "transform"
  27 /** @endcond */
  28
  29 /**
  30  * @file
  31  *
  32  * Transform module handling.
  33  */
  34
  35 /**
  36  * @defgroup grp_transform Transform modules
  37  *
  38  * Transform module handling.
  39  *
  40  * @{
  41  */
  42
  43 /** @cond PRIVATE */
  44 extern SR_PRIV struct sr_transform_module transform_nop;
  45 extern SR_PRIV struct sr_transform_module transform_scale;
  46 extern SR_PRIV struct sr_transform_module transform_invert;
  47 /* @endcond */
  48
  49 static const struct sr_transform_module *transform_module_list[] = {
  50         &transform_nop,
  51         &transform_scale,
  52         &transform_invert,
  53         NULL,
  54 };
  55
  56 /**
  57  * Returns a NULL-terminated list of all available transform modules.
  58  *
  59  * @since 0.4.0
  60  */
  61 SR_API const struct sr_transform_module **sr_transform_list(void)
  62 {
  63         return transform_module_list;
  64 }
  65
  66 /**
  67  * Returns the specified transform module's ID.
  68  *
  69  * @since 0.4.0
  70  */
  71 SR_API const char *sr_transform_id_get(const struct sr_transform_module *tmod)
  72 {
  73         if (!tmod) {
  74                 sr_err("Invalid transform module NULL!");
  75                 return NULL;
  76         }
  77
  78         return tmod->id;
  79 }
  80
  81 /**
  82  * Returns the specified transform module's name.
  83  *
  84  * @since 0.4.0
  85  */
  86 SR_API const char *sr_transform_name_get(const struct sr_transform_module *tmod)
  87 {
  88         if (!tmod) {
  89                 sr_err("Invalid transform module NULL!");
  90                 return NULL;
  91         }
  92
  93         return tmod->name;
  94 }
  95
  96 /**
  97  * Returns the specified transform module's description.
  98  *
  99  * @since 0.4.0
 100  */
 101 SR_API const char *sr_transform_description_get(const struct sr_transform_module *tmod)
 102 {
 103         if (!tmod) {
 104                 sr_err("Invalid transform module NULL!");
 105                 return NULL;
 106         }
 107
 108         return tmod->desc;
 109 }
 110
 111 /**
 112  * Return the transform module with the specified ID, or NULL if no module
 113  * with that ID is found.
 114  *
 115  * @since 0.4.0
 116  */
 117 SR_API const struct sr_transform_module *sr_transform_find(const char *id)
 118 {
 119         int i;
 120
 121         for (i = 0; transform_module_list[i]; i++) {
 122                 if (!strcmp(transform_module_list[i]->id, id))
 123                         return transform_module_list[i];
 124         }
 125
 126         return NULL;
 127 }
 128
 129 /**
 130  * Returns a NULL-terminated array of struct sr_option, or NULL if the
 131  * module takes no options.
 132  *
 133  * Each call to this function must be followed by a call to
 134  * sr_transform_options_free().
 135  *
 136  * @since 0.4.0
 137  */
 138 SR_API const struct sr_option **sr_transform_options_get(const struct sr_transform_module *tmod)
 139 {
 140         const struct sr_option *mod_opts, **opts;
 141         int size, i;
 142
 143         if (!tmod || !tmod->options)
 144                 return NULL;
 145
 146         mod_opts = tmod->options();
 147
 148         for (size = 0; mod_opts[size].id; size++)
 149                 ;
 150         opts = g_malloc((size + 1) * sizeof(struct sr_option *));
 151
 152         for (i = 0; i < size; i++)
 153                 opts[i] = &mod_opts[i];
 154         opts[i] = NULL;
 155
 156         return opts;
 157 }
 158
 159 /**
 160  * After a call to sr_transform_options_get(), this function cleans up all
 161  * resources returned by that call.
 162  *
 163  * @since 0.4.0
 164  */
 165 SR_API void sr_transform_options_free(const struct sr_option **options)
 166 {
 167         int i;
 168
 169         if (!options)
 170                 return;
 171
 172         for (i = 0; options[i]; i++) {
 173                 if (options[i]->def) {
 174                         g_variant_unref(options[i]->def);
 175                         ((struct sr_option *)options[i])->def = NULL;
 176                 }
 177
 178                 if (options[i]->values) {
 179                         g_slist_free_full(options[i]->values, (GDestroyNotify)g_variant_unref);
 180                         ((struct sr_option *)options[i])->values = NULL;
 181                 }
 182         }
 183         g_free(options);
 184 }
 185
 186 /**
 187  * Create a new transform instance using the specified transform module.
 188  *
 189  * <code>options</code> is a *GHashTable with the keys corresponding with
 190  * the module options' <code>id</code> field. The values should be GVariant
 191  * pointers with sunk * references, of the same GVariantType as the option's
 192  * default value.
 193  *
 194  * The sr_dev_inst passed in can be used by the instance to determine
 195  * channel names, samplerate, and so on.
 196  *
 197  * @since 0.4.0
 198  */
 199 SR_API const struct sr_transform *sr_transform_new(const struct sr_transform_module *tmod,
 200                 GHashTable *options, const struct sr_dev_inst *sdi)
 201 {
 202         struct sr_transform *t;
 203         const struct sr_option *mod_opts;
 204         const GVariantType *gvt;
 205         GHashTable *new_opts;
 206         GHashTableIter iter;
 207         gpointer key, value;
 208         int i;
 209
 210         t = g_malloc(sizeof(struct sr_transform));
 211         t->module = tmod;
 212         t->sdi = sdi;
 213
 214         new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
 215                         (GDestroyNotify)g_variant_unref);
 216         if (tmod->options) {
 217                 mod_opts = tmod->options();
 218                 for (i = 0; mod_opts[i].id; i++) {
 219                         if (options && g_hash_table_lookup_extended(options,
 220                                         mod_opts[i].id, &key, &value)) {
 221                                 /* Pass option along. */
 222                                 gvt = g_variant_get_type(mod_opts[i].def);
 223                                 if (!g_variant_is_of_type(value, gvt)) {
 224                                         sr_err("Invalid type for '%s' option.", key);
 225                                         g_free(t);
 226                                         return NULL;
 227                                 }
 228                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 229                                                 g_variant_ref(value));
 230                         } else {
 231                                 /* Option not given: insert the default value. */
 232                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 233                                                 g_variant_ref(mod_opts[i].def));
 234                         }
 235                 }
 236
 237                 /* Make sure no invalid options were given. */
 238                 if (options) {
 239                         g_hash_table_iter_init(&iter, options);
 240                         while (g_hash_table_iter_next(&iter, &key, &value)) {
 241                                 if (!g_hash_table_lookup(new_opts, key)) {
 242                                         sr_err("Transform module '%s' has no option '%s'.", tmod->id, key);
 243                                         g_hash_table_destroy(new_opts);
 244                                         g_free(t);
 245                                         return NULL;
 246                                 }
 247                         }
 248                 }
 249         }
 250
 251         if (t->module->init && t->module->init(t, new_opts) != SR_OK) {
 252                 g_free(t);
 253                 t = NULL;
 254         }
 255         if (new_opts)
 256                 g_hash_table_destroy(new_opts);
 257
 258         /* Add the transform to the session's list of transforms. */
 259         sdi->session->transforms = g_slist_append(sdi->session->transforms, t);
 260
 261         return t;
 262 }
 263
 264 /**
 265  * Free the specified transform instance and all associated resources.
 266  *
 267  * @since 0.4.0
 268  */
 269 SR_API int sr_transform_free(const struct sr_transform *t)
 270 {
 271         int ret;
 272
 273         if (!t)
 274                 return SR_ERR_ARG;
 275
 276         ret = SR_OK;
 277         if (t->module->cleanup)
 278                 ret = t->module->cleanup((struct sr_transform *)t);
 279         g_free((gpointer)t);
 280
 281         return ret;
 282 }
 283
 284 /** @} */