Session handling

Creating, using, or destroying libsigrok sessions. More...

Functions
int	sr_session_new (struct sr_context *ctx, struct sr_session **new_session)
	Create a new session. More...
int	sr_session_destroy (struct sr_session *session)
	Destroy a session. More...
int	sr_session_dev_remove_all (struct sr_session *session)
	Remove all the devices from a session. More...
int	sr_session_dev_add (struct sr_session *session, struct sr_dev_inst *sdi)
	Add a device instance to a session. More...
int	sr_session_dev_list (struct sr_session *session, GSList **devlist)
	List all device instances attached to a session. More...
int	sr_session_dev_remove (struct sr_session *session, struct sr_dev_inst *sdi)
	Remove a device instance from a session. More...
int	sr_session_datafeed_callback_remove_all (struct sr_session *session)
	Remove all datafeed callbacks in a session. More...
int	sr_session_datafeed_callback_add (struct sr_session *session, sr_datafeed_callback cb, void *cb_data)
	Add a datafeed callback to a session. More...
struct sr_trigger *	sr_session_trigger_get (struct sr_session *session)
	Get the trigger assigned to this session. More...
int	sr_session_trigger_set (struct sr_session *session, struct sr_trigger *trig)
	Set the trigger of this session. More...
int	sr_session_start (struct sr_session *session)
	Start a session. More...
int	sr_session_run (struct sr_session *session)
	Block until the running session stops. More...
int	sr_session_stop (struct sr_session *session)
	Stop a session. More...
int	sr_session_is_running (struct sr_session *session)
	Return whether the session is currently running. More...
int	sr_session_stopped_callback_set (struct sr_session *session, sr_session_stopped_callback cb, void *cb_data)
	Set the callback to be invoked after a session stopped running. More...
SR_PRIV int	sr_session_fd_source_add (struct sr_session *session, void *key, gintptr fd, int events, int timeout, sr_receive_data_callback cb, void *cb_data)
SR_PRIV int	sr_packet_copy (const struct sr_datafeed_packet *packet, struct sr_datafeed_packet **copy)
void	sr_packet_free (struct sr_datafeed_packet *packet)
SR_PRIV void	sr_zip_discard (struct zip *archive)
SR_PRIV GKeyFile *	sr_sessionfile_read_metadata (struct zip *archive, const struct zip_stat *entry)
	Read metadata entries from a session archive. More...
int	sr_session_load (struct sr_context *ctx, const char *filename, struct sr_session **session)
	Load the session from the specified filename. More...

Variables
SR_PRIV struct sr_dev_driver	session_driver

Detailed Description

Creating, using, or destroying libsigrok sessions.

Function Documentation

SR_PRIV int sr_packet_copy	(	const struct sr_datafeed_packet *	packet,
		struct sr_datafeed_packet **	copy
	)

Definition at line 1494 of file session.c.

References sr_datafeed_analog_old::channels, sr_analog_meaning::channels, sr_datafeed_meta::config, sr_datafeed_logic::data, sr_datafeed_analog_old::data, sr_datafeed_analog::data, sr_datafeed_analog::encoding, sr_datafeed_logic::length, sr_datafeed_analog::meaning, sr_datafeed_analog_old::mq, sr_datafeed_analog_old::mqflags, sr_datafeed_analog_old::num_samples, sr_datafeed_analog::num_samples, sr_datafeed_packet::payload, sr_datafeed_analog::spec, SR_DF_ANALOG, SR_DF_ANALOG_OLD, SR_DF_END, SR_DF_HEADER, SR_DF_LOGIC, SR_DF_META, SR_DF_TRIGGER, SR_ERR, SR_OK, sr_datafeed_packet::type, sr_datafeed_analog_old::unit, sr_datafeed_logic::unitsize, and sr_analog_encoding::unitsize.

void sr_packet_free

(

struct sr_datafeed_packet *

packet

)

Definition at line 1573 of file session.c.

References sr_datafeed_analog_old::channels, sr_analog_meaning::channels, sr_datafeed_meta::config, sr_datafeed_logic::data, sr_datafeed_analog_old::data, sr_datafeed_analog::data, sr_config::data, sr_datafeed_analog::encoding, sr_datafeed_analog::meaning, sr_datafeed_packet::payload, sr_datafeed_analog::spec, SR_DF_ANALOG, SR_DF_ANALOG_OLD, SR_DF_END, SR_DF_HEADER, SR_DF_LOGIC, SR_DF_META, SR_DF_TRIGGER, and sr_datafeed_packet::type.

int sr_session_datafeed_callback_add	(	struct sr_session *	session,
		sr_datafeed_callback	cb,
		void *	cb_data
	)

Add a datafeed callback to a session.

Parameters

session	The session to use. Must not be NULL.
cb	Function to call when a chunk of data is received. Must not be NULL.
cb_data	Opaque pointer passed in by the caller.

Return values

SR_OK	Success.
SR_ERR_BUG	No session exists.

Since

0.3.0

Definition at line 483 of file session.c.

References SR_ERR_ARG, SR_ERR_BUG, and SR_OK.

int sr_session_datafeed_callback_remove_all

(

struct sr_session *

session

)

Remove all datafeed callbacks in a session.

Parameters

session

The session to use. Must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid session passed.

Since

0.4.0

Definition at line 457 of file session.c.

References SR_ERR_ARG, and SR_OK.

Referenced by sr_session_destroy().

Here is the caller graph for this function:

int sr_session_destroy

(

struct sr_session *

session

)

Destroy a session.

This frees up all memory used by the session.

Parameters

session

The session to destroy. Must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid session passed.

Since

0.4.0

Definition at line 249 of file session.c.

References SR_ERR_ARG, SR_OK, sr_session_datafeed_callback_remove_all(), and sr_session_dev_remove_all().

Here is the call graph for this function:

int sr_session_dev_add	(	struct sr_session *	session,
		struct sr_dev_inst *	sdi
	)

Add a device instance to a session.

Parameters

session	The session to add to. Must not be NULL.
sdi	The device instance to add to a session. Must not be NULL. Also, sdi->driver and sdi->driver->dev_open must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid argument.

Since

0.4.0

Definition at line 317 of file session.c.

References sr_config_commit(), SR_ERR_ARG, SR_ERR_BUG, SR_OK, and sr_strerror().

Referenced by sr_session_load().

Here is the call graph for this function:

Here is the caller graph for this function:

int sr_session_dev_list	(	struct sr_session *	session,
		GSList **	devlist
	)

List all device instances attached to a session.

Parameters

session	The session to use. Must not be NULL.
devlist	A pointer where the device instance list will be stored on return. If no devices are in the session, this will be NULL. Each element in the list points to a struct sr_dev_inst *. The list must be freed by the caller, but not the elements pointed to.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid argument.

Since

0.4.0

Definition at line 395 of file session.c.

References SR_ERR_ARG, and SR_OK.

int sr_session_dev_remove	(	struct sr_session *	session,
		struct sr_dev_inst *	sdi
	)

Remove a device instance from a session.

Parameters

session	The session to remove from. Must not be NULL.
sdi	The device instance to remove from a session. Must not be NULL. Also, sdi->driver and sdi->driver->dev_open must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid argument.

Since

0.4.0

Definition at line 421 of file session.c.

References SR_ERR_ARG, and SR_OK.

int sr_session_dev_remove_all

(

struct sr_session *

session

)

Remove all the devices from a session.

The session itself (i.e., the struct sr_session) is not free'd and still exists after this function returns.

Parameters

session

The session to use. Must not be NULL.

Return values

SR_OK	Success.
SR_ERR_BUG	Invalid session passed.

Since

0.4.0

Definition at line 283 of file session.c.

References SR_ERR_ARG, and SR_OK.

Referenced by sr_session_destroy().

Here is the caller graph for this function:

SR_PRIV int sr_session_fd_source_add	(	struct sr_session *	session,
		void *	key,
		gintptr	fd,
		int	events,
		int	timeout,
		sr_receive_data_callback	cb,
		void *	cb_data
	)

Definition at line 1233 of file session.c.

References SR_ERR.

int sr_session_is_running

(

struct sr_session *

session

)

Return whether the session is currently running.

Note that this function should be called from the same thread the session was started in.

Parameters

session

The session to use. Must not be NULL.

Return values

TRUE	Session is running.
FALSE	Session is not running.
SR_ERR_ARG	Invalid session passed.

Since

0.4.0

Definition at line 986 of file session.c.

References SR_ERR_ARG.

int sr_session_load	(	struct sr_context *	ctx,
		const char *	filename,
		struct sr_session **	session
	)

Load the session from the specified filename.

Parameters

ctx	The context in which to load the session.
filename	The name of the session file to load.
session	The session to load the file into.

Return values

SR_OK	Success
SR_ERR_MALLOC	Memory allocation error
SR_ERR_DATA	Malformed session file
SR_ERR	This is not a session file

Definition at line 178 of file session_file.c.

References session_driver, SR_CHANNEL_LOGIC, SR_CONF_CAPTURE_UNITSIZE, SR_CONF_CAPTUREFILE, SR_CONF_NUM_LOGIC_CHANNELS, SR_CONF_SAMPLERATE, SR_CONF_SESSIONFILE, sr_config_set(), sr_dev_channel_enable(), sr_dev_channel_name_set(), sr_dev_open(), SR_ERR, SR_ERR_DATA, SR_MAX_CHANNELNAME_LEN, SR_OK, sr_parse_sizestring(), sr_session_dev_add(), sr_session_new(), sr_sessionfile_read_metadata(), and SR_ST_ACTIVE.

Here is the call graph for this function:

int sr_session_new	(	struct sr_context *	ctx,
		struct sr_session **	new_session
	)

Create a new session.

Parameters

ctx	The context in which to create the new session.
new_session	This will contain a pointer to the newly created session if the return value is SR_OK, otherwise the value is undefined and should not be used. Must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid argument.

Since

0.4.0

Definition at line 214 of file session.c.

References SR_ERR_ARG, and SR_OK.

Referenced by sr_session_load().

Here is the caller graph for this function:

int sr_session_run

(

struct sr_session *

session

)

Block until the running session stops.

This is a convenience function which creates a GLib main loop and runs it to process session events until the session stops.

Instead of using this function, applications may run their own GLib main loop, and use sr_session_stopped_callback_set() to receive notification when the session finished running.

Parameters

session

The session to use. Must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid session passed.
SR_ERR	Other error.

Since

0.4.0

Definition at line 865 of file session.c.

References SR_ERR, SR_ERR_ARG, and SR_OK.

int sr_session_start

(

struct sr_session *

session

)

Start a session.

When this function returns with a status code indicating success, the session is running. Use sr_session_stopped_callback_set() to receive notification upon completion, or call sr_session_run() to block until the session stops.

Session events will be processed in the context of the current thread. If a thread-default GLib main context has been set, and is not owned by any other thread, it will be used. Otherwise, libsigrok will create its own main context for the current thread.

Parameters

session

The session to use. Must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid session passed.
SR_ERR	Other error.

Since

0.4.0

Definition at line 753 of file session.c.

References sr_channel::enabled, sr_config_commit(), SR_ERR, SR_ERR_ARG, and SR_OK.

Here is the call graph for this function:

int sr_session_stop

(

struct sr_session *

session

)

Stop a session.

This requests the drivers of each device participating in the session to abort the acquisition as soon as possible. Even after this function returns, event processing still continues until all devices have actually stopped.

Use sr_session_stopped_callback_set() to receive notification when the event processing finished.

This function is reentrant. That is, it may be called from a different thread than the one executing the session, as long as it can be ensured that the session object is valid.

If the session is not running, sr_session_stop() silently does nothing.

Parameters

session

The session to use. Must not be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid session passed.

Since

0.4.0

Definition at line 944 of file session.c.

References SR_ERR_ARG, and SR_OK.

int sr_session_stopped_callback_set	(	struct sr_session *	session,
		sr_session_stopped_callback	cb,
		void *	cb_data
	)

Set the callback to be invoked after a session stopped running.

Install a callback to receive notification when a session run stopped. This can be used to integrate session execution with an existing main loop, without having to block in sr_session_run().

Note that the callback will be invoked in the context of the thread that calls sr_session_start().

Parameters

session	The session to use. Must not be NULL.
cb	The callback to invoke on session stop. May be NULL to unset.
cb_data	User data pointer to be passed to the callback.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid session passed.

Since

0.4.0

Definition at line 1014 of file session.c.

References SR_ERR_ARG, and SR_OK.

struct sr_trigger* sr_session_trigger_get

(

struct sr_session *

session

)

Get the trigger assigned to this session.

Parameters

session

The session to use.

Return values

NULL	Invalid (NULL) session was passed to the function.
other	The trigger assigned to this session (can be NULL).

Since

0.4.0

Definition at line 518 of file session.c.

int sr_session_trigger_set	(	struct sr_session *	session,
		struct sr_trigger *	trig
	)

Set the trigger of this session.

Parameters

session	The session to use. Must not be NULL.
trig	The trigger to assign to this session. Can be NULL.

Return values

SR_OK	Success.
SR_ERR_ARG	Invalid argument.

Since

0.4.0

Definition at line 537 of file session.c.

References SR_ERR_ARG, and SR_OK.

SR_PRIV GKeyFile* sr_sessionfile_read_metadata	(	struct zip *	archive,
		const struct zip_stat *	entry
	)

Read metadata entries from a session archive.

Parameters

[in]	archive	An open ZIP archive.
[in]	entry	Stat buffer filled in for the metadata archive member.

Returns

A new key/value store containing the session metadata.

Definition at line 64 of file session_file.c.

Referenced by sr_session_load().

Here is the caller graph for this function:

SR_PRIV void sr_zip_discard

(

struct zip *

archive

)

Definition at line 52 of file session_file.c.

Variable Documentation

SR_PRIV struct sr_dev_driver session_driver

Referenced by sr_session_load().