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

Functions
struct sr_session *	sr_session_new (void)
	Create a new session.
int	sr_session_destroy (void)
	Destroy the current session.
int	sr_session_dev_remove_all (void)
	Remove all the devices from the current session.
int	sr_session_dev_add (const struct sr_dev_inst *sdi)
	Add a device instance to the current session.
int	sr_session_dev_list (GSList **devlist)
	List all device instances attached to the current session.
int	sr_session_datafeed_callback_remove_all (void)
	Remove all datafeed callbacks in the current session.
int	sr_session_datafeed_callback_add (sr_datafeed_callback cb, void *cb_data)
	Add a datafeed callback to the current session.
int	sr_session_start (void)
	Start a session.
int	sr_session_run (void)
	Run the session.
int	sr_session_stop (void)
	Stop the current session.
int	sr_session_source_add (int fd, int events, int timeout, sr_receive_data_callback cb, void *cb_data)
	Add an event source for a file descriptor.
int	sr_session_source_add_pollfd (GPollFD pollfd, int timeout, sr_receive_data_callback cb, void cb_data)
	Add an event source for a GPollFD.
int	sr_session_source_add_channel (GIOChannel channel, int events, int timeout, sr_receive_data_callback cb, void cb_data)
	Add an event source for a GIOChannel.
int	sr_session_source_remove (int fd)
	Remove the source belonging to the specified file descriptor.
int	sr_session_source_remove_pollfd (GPollFD *pollfd)
	Remove the source belonging to the specified poll descriptor.
int	sr_session_source_remove_channel (GIOChannel *channel)
	Remove the source belonging to the specified channel.
int	sr_session_load (const char *filename)
	Load the session from the specified filename.
int	sr_session_save (const char filename, const struct sr_dev_inst sdi, unsigned char *buf, int unitsize, int units)
	Save the current session to the specified file.
int	sr_session_save_init (const char filename, uint64_t samplerate, char *channels)
	Initialize a saved session file.
int	sr_session_append (const char filename, unsigned char buf, int unitsize, int units)
	Append data to an existing session file.
Variables
struct sr_session *	session
struct sr_session *	session
SR_PRIV struct sr_dev_driver	session_driver

Detailed Description

Creating, using, or destroying libsigrok sessions.

Function Documentation

int sr_session_append	(	const char *	filename,
		unsigned char *	buf,
		int	unitsize,
		int	units
	)

Append data to an existing session file.

The session file must have been created with sr_session_save_init() or sr_session_save() beforehand.

Parameters:

filename	The name of the filename to append to. Must not be NULL.
buf	The data to be appended.
unitsize	The number of bytes per sample.
units	The number of samples.

Return values:

SR_OK	Success
SR_ERR_ARG	Invalid arguments
SR_ERR	Other errors

Since:: 0.3.0

Definition at line 387 of file session_file.c.

References SR_ERR, and SR_OK.

Referenced by sr_session_save().

Here is the caller graph for this function:

int sr_session_datafeed_callback_add	(	sr_datafeed_callback	cb,
		void *	cb_data
	)

Add a datafeed callback to the current session.

Parameters:

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 269 of file session.c.

References SR_ERR_ARG, SR_ERR_BUG, SR_ERR_MALLOC, and SR_OK.

int sr_session_datafeed_callback_remove_all ( void )

Remove all datafeed callbacks in the current session.

Return values:

SR_OK	Success.
SR_ERR_BUG	No session exists.

Since:: 0.1.0

Definition at line 244 of file session.c.

References SR_ERR_BUG, and SR_OK.

int sr_session_destroy ( void )

Destroy the current session.

This frees up all memory used by the session.

Return values:

SR_OK	Success.
SR_ERR_BUG	No session exists.

Since:: 0.1.0

Definition at line 101 of file session.c.

References SR_ERR_BUG, SR_OK, and sr_session_dev_remove_all().

Here is the call graph for this function:

int sr_session_dev_add ( const struct sr_dev_inst * sdi )

Add a device instance to the current session.

Parameters:

sdi	The device instance to add to the current 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.
SR_ERR_BUG	No session exists.

Since:: 0.2.0

Definition at line 157 of file session.c.

References sr_dev_driver::dev_open, sr_dev_inst::driver, 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 ( GSList ** devlist )

List all device instances attached to the current session.

Parameters:

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	Invalid argument.

Since:: 0.3.0

Definition at line 223 of file session.c.

References SR_ERR, and SR_OK.

int sr_session_dev_remove_all ( void )

Remove all the devices from the current session.

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

Return values:

SR_OK	Success.
SR_ERR_BUG	No session exists.

Since:: 0.1.0

Definition at line 131 of file session.c.

References SR_ERR_BUG, and SR_OK.

Referenced by sr_session_destroy().

Here is the caller graph for this function:

int sr_session_load ( const char * filename )

Load the session from the specified filename.

Parameters:

filename The name of the session file to load. Must not be NULL.

Returns:: SR_OK upon success, SR_ERR_ARG upon invalid arguments, SR_ERR_MALLOC upon memory allocation errors, or SR_ERR upon other errors.

Definition at line 110 of file session_file.c.

References sr_dev_inst::channels, sr_dev_driver::config_set, sr_dev_inst::driver, sr_dev_driver::init, session_driver, SR_CHANNEL_LOGIC, SR_CONF_CAPTURE_UNITSIZE, SR_CONF_CAPTUREFILE, SR_CONF_NUM_LOGIC_CHANNELS, SR_CONF_SAMPLERATE, SR_CONF_SESSIONFILE, sr_dev_channel_enable(), sr_dev_channel_name_set(), sr_dev_open(), sr_dev_trigger_set(), SR_ERR, SR_ERR_MALLOC, SR_MAX_CHANNELNAME_LEN, SR_OK, sr_parse_sizestring(), sr_session_dev_add(), sr_session_new(), and SR_ST_ACTIVE.

Here is the call graph for this function:

struct sr_session* sr_session_new ( void ) [read]

Create a new session.

Todo:: Should it use the file-global "session" variable or take an argument? The same question applies to all the other session functions.

Return values:

NULL	Error.
other	A pointer to the newly allocated session.

Since:: 0.1.0

Definition at line 77 of file session.c.

References session.

Referenced by sr_session_load().

Here is the caller graph for this function:

int sr_session_run ( void )

Run the session.

Return values:

SR_OK	Success.
SR_ERR_BUG	Error occured.

Since:: 0.1.0

Definition at line 408 of file session.c.

References SR_ERR_BUG, and SR_OK.

int sr_session_save	(	const char *	filename,
		const struct sr_dev_inst *	sdi,
		unsigned char *	buf,
		int	unitsize,
		int	units
	)

Save the current session to the specified file.

Parameters:

filename	The name of the filename to save the current session as. Must not be NULL.
sdi	The device instance from which the data was captured.
buf	The data to be saved.
unitsize	The number of bytes per sample.
units	The number of samples.

Return values:

SR_OK	Success
SR_ERR_ARG	Invalid arguments
SR_ERR	Other errors

Since:: 0.2.0

Definition at line 238 of file session_file.c.

References sr_dev_inst::channels, sr_dev_inst::driver, sr_channel::enabled, sr_channel::name, SR_CHANNEL_LOGIC, SR_CONF_SAMPLERATE, sr_config_get(), sr_dev_has_option(), SR_OK, sr_session_append(), sr_session_save_init(), and sr_channel::type.

Here is the call graph for this function:

int sr_session_save_init	(	const char *	filename,
		uint64_t	samplerate,
		char **	channels
	)

Initialize a saved session file.

Parameters:

filename	The name of the filename to save the current session as. Must not be NULL.
samplerate	The samplerate to store for this session.
channels	A NULL-terminated array of strings containing the names of all the channels active in this session.

Return values:

SR_OK	Success
SR_ERR_ARG	Invalid arguments
SR_ERR	Other errors

Since:: 0.3.0

Definition at line 294 of file session_file.c.

References SR_ERR, SR_ERR_ARG, SR_OK, and sr_samplerate_string().

Referenced by sr_session_save().

Here is the call graph for this function:

Here is the caller graph for this function:

int sr_session_source_add	(	int	fd,
		int	events,
		int	timeout,
		sr_receive_data_callback	cb,
		void *	cb_data
	)

Add an event source for a file descriptor.

Parameters:

fd	The file descriptor.
events	Events to check for.
timeout	Max time to wait before the callback is called, ignored if 0.
cb	Callback function to add. Must not be NULL.
cb_data	Data for the callback function. Can be NULL.

Return values:

SR_OK	Success.
SR_ERR_ARG	Invalid argument.
SR_ERR_MALLOC	Memory allocation error.

Since:: 0.3.0

Definition at line 664 of file session.c.

int sr_session_source_add_channel	(	GIOChannel *	channel,
		int	events,
		int	timeout,
		sr_receive_data_callback	cb,
		void *	cb_data
	)

Add an event source for a GIOChannel.

Parameters:

channel	The GIOChannel.
events	Events to poll on.
timeout	Max time to wait before the callback is called, ignored if 0.
cb	Callback function to add. Must not be NULL.
cb_data	Data for the callback function. Can be NULL.

Return values:

SR_OK	Success.
SR_ERR_ARG	Invalid argument.
SR_ERR_MALLOC	Memory allocation error.

Since:: 0.3.0

Definition at line 711 of file session.c.

int sr_session_source_add_pollfd	(	GPollFD *	pollfd,
		int	timeout,
		sr_receive_data_callback	cb,
		void *	cb_data
	)

Add an event source for a GPollFD.

Parameters:

pollfd	The GPollFD.
timeout	Max time to wait before the callback is called, ignored if 0.
cb	Callback function to add. Must not be NULL.
cb_data	Data for the callback function. Can be NULL.

Return values:

SR_OK	Success.
SR_ERR_ARG	Invalid argument.
SR_ERR_MALLOC	Memory allocation error.

Since:: 0.3.0

Definition at line 689 of file session.c.

int sr_session_source_remove ( int fd )

Remove the source belonging to the specified file descriptor.

Parameters:

fd	The file descriptor for which the source should be removed.

Return values:

SR_OK	Success
SR_ERR_ARG	Invalid argument
SR_ERR_MALLOC	Memory allocation error.
SR_ERR_BUG	Internal error.

Since:: 0.3.0

Definition at line 797 of file session.c.

int sr_session_source_remove_channel ( GIOChannel * channel )

Remove the source belonging to the specified channel.

Parameters:

channel The channel for which the source should be removed.

Return values:

SR_OK	Success.
SR_ERR_ARG	Invalid argument.
SR_ERR_MALLOC	Memory allocation error.

Returns:: SR_ERR_BUG Internal error.

Since:: 0.2.0

Definition at line 830 of file session.c.

int sr_session_source_remove_pollfd ( GPollFD * pollfd )

Remove the source belonging to the specified poll descriptor.

Parameters:

pollfd The poll descriptor for which the source should be removed.

Returns:: SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon internal errors.

Since:: 0.2.0

Definition at line 813 of file session.c.

int sr_session_start ( void )

Start a session.

There can only be one session at a time.

Return values:

SR_OK	Success.
SR_ERR	Error occured.

Since:: 0.1.0

Definition at line 360 of file session.c.

References sr_dev_driver::dev_acquisition_start, sr_dev_inst::driver, sr_config_commit(), SR_ERR_BUG, SR_OK, and sr_strerror().

Here is the call graph for this function:

int sr_session_stop ( void )

Stop the current session.

The current session is stopped immediately, with all acquisition sessions being stopped and hardware drivers cleaned up.

If the session is run in a separate thread, this function will not block until the session is finished executing. It is the caller's responsibility to wait for the session thread to return before assuming that the session is completely decommissioned.

Return values:

SR_OK	Success.
SR_ERR_BUG	No session exists.

Since:: 0.1.0

Definition at line 494 of file session.c.

References SR_ERR_BUG, and SR_OK.

Variable Documentation

struct sr_session* session

Definition at line 64 of file session.c.

struct sr_session* session

Definition at line 64 of file session.c.

Referenced by sr_session_new().

SR_PRIV struct sr_dev_driver session_driver

Referenced by sr_session_load().

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation