sr_output_format Struct Reference

#include <libsigrok.h>

Collaboration diagram for sr_output_format:

Data Fields
char *	id
	A unique ID for this output format. More...
char *	description
	A short description of the output format. More...
int	df_type
int(*	init )(struct sr_output *o)
	This function is called once, at the beginning of an output stream. More...
int(*	data )(struct sr_output *o, const uint8_t *data_in, uint64_t length_in, uint8_t **data_out, uint64_t *length_out)
	Whenever a chunk of data comes in, it will be passed to the output module via this function. More...
int(*	event )(struct sr_output *o, int event_type, uint8_t **data_out, uint64_t *length_out)
	This function is called when an event occurs in the datafeed which the output module may need to be aware of. More...
int(*	receive )(struct sr_output *o, const struct sr_dev_inst *sdi, const struct sr_datafeed_packet *packet, GString **out)
	This function is passed a copy of every packed in the data feed. More...
int(*	cleanup )(struct sr_output *o)
	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. More...

Detailed Description

Definition at line 400 of file libsigrok.h.

Field Documentation

int(* sr_output_format::cleanup)(struct sr_output *o)

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.

Returns

SR_OK upon success, a negative error code otherwise.

Definition at line 528 of file libsigrok.h.

int(* sr_output_format::data)(struct sr_output *o, const uint8_t *data_in, uint64_t length_in, uint8_t **data_out, uint64_t *length_out)

Whenever a chunk of data comes in, it will be passed to the output module via this function.

The data_in and length_in values refers to this data; the module must not alter or g_free() this buffer.

The function must allocate a buffer for storing its output, and pass along a pointer to this buffer in the data_out parameter, as well as storing the length of the buffer in length_out. The calling frontend will g_free() this buffer when it's done with it.

IMPORTANT: The memory allocation much happen using a glib memory allocation call (not a "normal" malloc) since g_free() will be used to free the memory!

If there is no output, this function MUST store NULL in the data_out parameter, so the caller knows not to try and g_free() it.

Note: This API call is obsolete, use receive() instead.

Parameters

o	Pointer to the respective 'struct sr_output'.
data_in	Pointer to the input data buffer.
length_in	Length of the input.
data_out	Pointer to the allocated output buffer.
length_out	Length (in bytes) of the output.

Returns

SR_OK upon success, a negative error code otherwise.

Definition at line 467 of file libsigrok.h.

char* sr_output_format::description

A short description of the output format.

Must not be NULL.

This can be displayed by frontends, e.g. when selecting the output format for saving a file.

Definition at line 417 of file libsigrok.h.

int sr_output_format::df_type

Definition at line 419 of file libsigrok.h.

int(* sr_output_format::event)(struct sr_output *o, int event_type, uint8_t **data_out, uint64_t *length_out)

This function is called when an event occurs in the datafeed which the output module may need to be aware of.

No data is passed in, only the fact that the event occurs. The following events can currently be passed in:

• SR_DF_TRIGGER: At this point in the datafeed, the trigger matched. The output module may mark this in some way, e.g. by plotting a red line on a graph.
• SR_DF_END: This marks the end of the datafeed. No more calls into the output module will be done, so this is a good time to free up any memory used to keep state, for example.

Any output generated by this function must have a reference to it stored in the data_out and length_out parameters, or NULL if no output was generated.

Note: This API call is obsolete, use receive() instead.

Parameters

o	Pointer to the respective 'struct sr_output'.
event_type	Type of event that occured.
data_out	Pointer to the allocated output buffer.
length_out	Length (in bytes) of the output.

Returns

SR_OK upon success, a negative error code otherwise.

Definition at line 498 of file libsigrok.h.

char* sr_output_format::id

A unique ID for this output format.

Must not be NULL.

It can be used by frontends to select this output format for use.

For example, calling sigrok-cli with -O hex will select the hexadecimal text output format.

Definition at line 409 of file libsigrok.h.

int(* sr_output_format::init)(struct sr_output *o)

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 internal field.

Parameters

o	Pointer to the respective 'struct sr_output'.

Returns

SR_OK upon success, a negative error code otherwise.

Definition at line 435 of file libsigrok.h.

int(* sr_output_format::receive)(struct sr_output *o, const struct sr_dev_inst *sdi, const struct sr_datafeed_packet *packet, GString **out)

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 out, which will be freed by the caller.

Packets not of interest to the output module can just be ignored, and the out parameter set to NULL.

Parameters

o	Pointer to the respective 'struct sr_output'.
sdi	The device instance that generated the packet.
packet	The complete packet.
out	A pointer where a GString * should be stored if the module generates output, or NULL if not.

Returns

SR_OK upon success, a negative error code otherwise.

Definition at line 518 of file libsigrok.h.

---

The documentation for this struct was generated from the following file:

• libsigrok.h