X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=src%2Flibsigrok-internal.h;h=642277ebfd47d5c1e1a95076ad841ef62a20eb03;hb=cb41a838a7da85f897b7ddd401b35a243a81bf1f;hp=8c58bd9f1e53e61c49985207cca5b2472321f699;hpb=155b680da482cea2381becb73c51cfb838bff31e;p=libsigrok.git

diff --git a/src/libsigrok-internal.h b/src/libsigrok-internal.h
index 8c58bd9f..642277eb 100644
--- 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 *priv;
+};
+
+/** 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 {