output: Finish output module API wrappers.

[libsigrok.git] / src / libsigrok-internal.h

diff --git a/src/libsigrok-internal.h b/src/libsigrok-internal.h
index 8c58bd9f1e53e61c49985207cca5b2472321f699..2a4384c4b13047bb816fb9248d9ba558bdf3a07f 100644 (file)
--- a/src/libsigrok-internal.h
+++ b/src/libsigrok-internal.h
@@ -159,6 +159,107 @@ struct sr_context {
 #endif
 };
 
+/** Output module instance. */
+struct sr_output {
+       /** A pointer to this output's module.  */
+       const struct sr_output_module *module;
+
+       /**
+        * The device for which this output module is creating output. This
+        * can be used by the module to find out channel names and numbers.
+        */
+       const struct sr_dev_inst *sdi;
+
+       /**
+        * A generic pointer which can be used by the module to keep internal
+        * state between calls into its callback functions.
+        *
+        * For example, the module might store a pointer to a chunk of output
+        * there, and only flush it when it reaches a certain size.
+        */
+       void *internal;
+};
+
+/** Output module driver. */
+struct sr_output_module {
+       /**
+        * A unique ID for this output module, suitable for use in command-line
+        * clients, [a-z0-9-]. Must not be NULL.
+        */
+       char *id;
+
+       /**
+        * A unique name for this output module, suitable for use in GUI
+        * clients, can contain UTF-8. Must not be NULL.
+        */
+       const char *name;
+
+       /**
+        * A short description of the output module. Must not be NULL.
+        *
+        * This can be displayed by frontends, e.g. when selecting the output
+        * module for saving a file.
+        */
+       char *desc;
+
+       /**
+        * Returns a NULL-terminated list of options this module can take.
+        * Can be NULL, if the module has no options.
+        *
+        * If cached is TRUE, no new GVariants are created for the def and
+        * values fields; instead, the current values are returned.
+        */
+       struct sr_option *(*options) (gboolean cached);
+
+       /**
+        * This function is called once, at the beginning of an output stream.
+        *
+        * The device struct will be available in the output struct passed in,
+        * as well as the param field -- which may be NULL or an empty string,
+        * if no parameter was passed.
+        *
+        * The module can use this to initialize itself, create a struct for
+        * keeping state and storing it in the <code>internal</code> field.
+        *
+        * @param o Pointer to the respective 'struct sr_output'.
+        *
+        * @retval SR_OK Success
+        * @retval other Negative error code.
+        */
+       int (*init) (struct sr_output *o, GHashTable *options);
+
+       /**
+        * This function is passed a copy of every packed in the data feed.
+        * Any output generated by the output module in response to the
+        * packet should be returned in a newly allocated GString
+        * <code>out</code>, which will be freed by the caller.
+        *
+        * Packets not of interest to the output module can just be ignored,
+        * and the <code>out</code> parameter set to NULL.
+        *
+        * @param o Pointer to the respective 'struct sr_output'.
+        * @param sdi The device instance that generated the packet.
+        * @param packet The complete packet.
+        * @param out A pointer where a GString * should be stored if
+        * the module generates output, or NULL if not.
+        *
+        * @retval SR_OK Success
+        * @retval other Negative error code.
+        */
+       int (*receive) (const struct sr_output *o,
+                       const struct sr_datafeed_packet *packet, GString **out);
+
+       /**
+        * This function is called after the caller is finished using
+        * the output module, and can be used to free any internal
+        * resources the module may keep.
+        *
+        * @retval SR_OK Success
+        * @retval other Negative error code.
+        */
+       int (*cleanup) (struct sr_output *o);
+};
+
 #ifdef HAVE_LIBUSB_1_0
 /** USB device instance */
 struct sr_usb_dev_inst {