X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=src%2Finput%2Finput.c;h=8e51e3f96b7285d23611d77b8ac8d46083ce1593;hb=c1aae90038456a61d0f9313d34e6107c3440d3e7;hp=6bea92b5148c076b5a1feeb9b70ac1dfcf8c2c25;hpb=25f20faf0df4c2f124c4dea0786dc042fcd41ed3;p=libsigrok.git diff --git a/src/input/input.c b/src/input/input.c index 6bea92b5..8e51e3f9 100644 --- a/src/input/input.c +++ b/src/input/input.c @@ -23,10 +23,12 @@ #include #include #include -#include "libsigrok.h" +#include #include "libsigrok-internal.h" +/** @cond PRIVATE */ #define LOG_PREFIX "input" +/** @endcond */ /** * @file @@ -89,14 +91,14 @@ SR_API const struct sr_input_module **sr_input_list(void) * * @since 0.4.0 */ -SR_API const char *sr_input_id_get(const struct sr_input_module *o) +SR_API const char *sr_input_id_get(const struct sr_input_module *imod) { - if (!o) { + if (!imod) { sr_err("Invalid input module NULL!"); return NULL; } - return o->id; + return imod->id; } /** @@ -104,14 +106,14 @@ SR_API const char *sr_input_id_get(const struct sr_input_module *o) * * @since 0.4.0 */ -SR_API const char *sr_input_name_get(const struct sr_input_module *o) +SR_API const char *sr_input_name_get(const struct sr_input_module *imod) { - if (!o) { + if (!imod) { sr_err("Invalid input module NULL!"); return NULL; } - return o->name; + return imod->name; } /** @@ -119,14 +121,33 @@ SR_API const char *sr_input_name_get(const struct sr_input_module *o) * * @since 0.4.0 */ -SR_API const char *sr_input_description_get(const struct sr_input_module *o) +SR_API const char *sr_input_description_get(const struct sr_input_module *imod) +{ + if (!imod) { + sr_err("Invalid input module NULL!"); + return NULL; + } + + return imod->desc; +} + +/** + * Returns the specified input 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_input_extensions_get( + const struct sr_input_module *imod) { - if (!o) { + if (!imod) { sr_err("Invalid input module NULL!"); return NULL; } - return o->desc; + return imod->exts; } /** @@ -210,8 +231,9 @@ SR_API void sr_input_options_free(const struct sr_option **options) * This function is used when a client wants to use a specific input * module to parse a stream. No effort is made to identify the format. * + * @param imod The input module to use. Must not be NULL. * @param options GHashTable consisting of keys corresponding with - * the module options \c id field. The values should be GVariant + * the module options @c id field. The values should be GVariant * pointers with sunk references, of the same GVariantType as the option's * default value. * @@ -271,15 +293,17 @@ SR_API struct sr_input *sr_input_new(const struct sr_input_module *imod, if (in->module->init && in->module->init(in, new_opts) != SR_OK) { g_free(in); in = NULL; + } else { + in->buf = g_string_sized_new(128); } + if (new_opts) g_hash_table_destroy(new_opts); - in->buf = g_string_sized_new(128); return in; } -/* Returns TRUE is all required meta items are available. */ +/* Returns TRUE if all required meta items are available. */ static gboolean check_required_metadata(const uint8_t *metadata, uint8_t *avail) { int m, a; @@ -364,7 +388,7 @@ SR_API int sr_input_scan_buffer(GString *buf, const struct sr_input **in) /* Module didn't recognize this buffer. */ continue; } else if (ret != SR_OK) { - /* Can be SR_OK_CONTINUE. */ + /* Can be SR_ERR_NA. */ return ret; } @@ -477,7 +501,7 @@ SR_API int sr_input_scan_file(const char *filename, const struct sr_input **in) /* Module didn't recognize this buffer. */ continue; } else if (ret != SR_OK) { - /* Can be SR_OK_CONTINUE. */ + /* Can be SR_ERR_NA. */ return ret; } @@ -495,11 +519,18 @@ SR_API int sr_input_scan_file(const char *filename, const struct sr_input **in) * Return the input instance's (virtual) device instance. This can be * used to find out the number of channels and other information. * + * If the device instance has not yet been fully populated by the input + * module, NULL is returned. This indicates the module needs more data + * to identify the number of channels and so on. + * * @since 0.4.0 */ SR_API struct sr_dev_inst *sr_input_dev_inst_get(const struct sr_input *in) { - return in->sdi; + if (in->sdi_ready) + return in->sdi; + else + return NULL; } /** @@ -508,37 +539,55 @@ SR_API struct sr_dev_inst *sr_input_dev_inst_get(const struct sr_input *in) * When an input module instance is created with sr_input_new(), this * function is used to feed data to the instance. * + * As enough data gets fed into this function to completely populate + * the device instance associated with this input instance, this is + * guaranteed to return the moment it's ready. This gives the caller + * the chance to examine the device instance, attach session callbacks + * and so on. + * * @since 0.4.0 */ SR_API int sr_input_send(const struct sr_input *in, GString *buf) { sr_spew("Sending %d bytes to %s module.", buf->len, in->module->id); - return in->module->receive(in, buf); + return in->module->receive((struct sr_input *)in, buf); } /** - * Free the specified input instance and all associated resources. + * Signal the input module no more data will come. + * + * This will cause the module to process any data it may have buffered. + * The SR_DF_END packet will also typically be sent at this time. * * @since 0.4.0 */ -SR_API int sr_input_free(const struct sr_input *in) +SR_API int sr_input_end(const struct sr_input *in) { - int ret; + sr_spew("Calling end() on %s module.", in->module->id); + return in->module->end((struct sr_input *)in); +} +/** + * Free the specified input instance and all associated resources. + * + * @since 0.4.0 + */ +SR_API void sr_input_free(const struct sr_input *in) +{ if (!in) - return SR_ERR_ARG; + return; - ret = SR_OK; if (in->module->cleanup) - ret = in->module->cleanup((struct sr_input *)in); + in->module->cleanup((struct sr_input *)in); if (in->sdi) sr_dev_inst_free(in->sdi); - if (in->buf) - g_string_free(in->buf, TRUE); + if (in->buf->len > 64) { + /* That seems more than just some sub-unitsize leftover... */ + sr_warn("Found %d unprocessed bytes at free time.", in->buf->len); + } + g_string_free(in->buf, TRUE); + g_free(in->priv); g_free((gpointer)in); - - return ret; } - /** @} */