libsigrok  0.2.2
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerator Macros Groups Pages
Functions | Variables
Session handling

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

Functions

struct sr_sessionsr_session_new (void)
 Create a new session. More...
 
int sr_session_destroy (void)
 Destroy the current session. More...
 
int sr_session_dev_remove_all (void)
 Remove all the devices from the current session. More...
 
int sr_session_dev_add (const struct sr_dev_inst *sdi)
 Add a device instance to the current session. More...
 
int sr_session_datafeed_callback_remove_all (void)
 Remove all datafeed callbacks in the current session. More...
 
int sr_session_datafeed_callback_add (sr_datafeed_callback_t cb, void *cb_data)
 Add a datafeed callback to the current session. More...
 
int sr_session_start (void)
 Start a session. More...
 
int sr_session_run (void)
 Run the session. More...
 
int sr_session_stop (void)
 Stop the current session. More...
 
int sr_session_source_add (int fd, int events, int timeout, sr_receive_data_callback_t cb, void *cb_data)
 Add an event source for a file descriptor. More...
 
int sr_session_source_add_pollfd (GPollFD *pollfd, int timeout, sr_receive_data_callback_t cb, void *cb_data)
 Add an event source for a GPollFD. More...
 
int sr_session_source_add_channel (GIOChannel *channel, int events, int timeout, sr_receive_data_callback_t cb, void *cb_data)
 Add an event source for a GIOChannel. More...
 
int sr_session_source_remove (int fd)
 Remove the source belonging to the specified file descriptor. More...
 
int sr_session_source_remove_pollfd (GPollFD *pollfd)
 Remove the source belonging to the specified poll descriptor. More...
 
int sr_session_source_remove_channel (GIOChannel *channel)
 Remove the source belonging to the specified channel. More...
 
int sr_session_load (const char *filename)
 Load the session from the specified filename. More...
 
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. More...
 

Variables

struct sr_sessionsession
 
struct sr_sessionsession
 
SR_PRIV struct sr_dev_driver session_driver
 

Detailed Description

Creating, using, or destroying libsigrok sessions.

Function Documentation

int sr_session_datafeed_callback_add ( sr_datafeed_callback_t  cb,
void *  cb_data 
)

Add a datafeed callback to the current session.

Parameters
cbFunction to call when a chunk of data is received. Must not be NULL.
cb_dataOpaque pointer passed in by the caller.
Returns
SR_OK upon success, SR_ERR_BUG if no session exists.

Definition at line 220 of file session.c.

References sr_session::datafeed_callbacks, sr_err, 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.

Returns
SR_OK upon success, SR_ERR_BUG if no session exists.

Definition at line 198 of file session.c.

References sr_session::datafeed_callbacks, sr_err, SR_ERR_BUG, and SR_OK.

int sr_session_destroy ( void  )

Destroy the current session.

This frees up all memory used by the session.

Returns
SR_OK upon success, SR_ERR_BUG if no session exists.

Definition at line 101 of file session.c.

References sr_err, SR_ERR_BUG, SR_OK, sr_session_dev_remove_all(), and sr_session::stop_mutex.

+ 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
sdiThe device instance to add to the current session. Must not be NULL. Also, sdi->driver and sdi->driver->dev_open must not be NULL.
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments.

Definition at line 150 of file session.c.

References sr_dev_driver::dev_open, sr_session::devs, sr_dev_inst::driver, sr_session::running, sr_dbg, sr_err, SR_ERR_ARG, SR_ERR_BUG, and SR_OK.

Referenced by sr_session_load().

+ Here is the caller graph for this function:

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.

Returns
SR_OK upon success, SR_ERR_BUG if no session exists.

Definition at line 128 of file session.c.

References sr_session::devs, sr_err, 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
filenameThe 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 63 of file session_file.c.

References sr_dev_driver::config_set, sr_dev_inst::driver, sr_dev_driver::init, sr_dev_inst::probes, session_driver, SR_CONF_CAPTURE_NUM_PROBES, SR_CONF_CAPTURE_UNITSIZE, SR_CONF_CAPTUREFILE, SR_CONF_SAMPLERATE, SR_CONF_SESSIONFILE, sr_dbg, sr_dev_open(), sr_dev_probe_enable(), sr_dev_probe_name_set(), sr_dev_trigger_set(), sr_err, SR_ERR, SR_ERR_ARG, SR_ERR_MALLOC, SR_MAX_PROBENAME_LEN, SR_OK, sr_parse_sizestring(), SR_PROBE_LOGIC, 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.
Returns
A pointer to the newly allocated session, or NULL upon errors.

Definition at line 79 of file session.c.

References sr_session::abort_session, sr_session::running, session, sr_session::source_timeout, sr_err, and sr_session::stop_mutex.

Referenced by sr_session_load().

+ Here is the caller graph for this function:

int sr_session_run ( void  )

Run the session.

Returns
SR_OK upon success, SR_ERR_BUG upon errors.

Definition at line 347 of file session.c.

References sr_session::devs, sr_session::num_sources, sr_session::pollfds, sr_session::running, sr_session::sources, sr_err, SR_ERR_BUG, sr_info, 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
filenameThe name of the filename to save the current session as. Must not be NULL.
sdiThe device instance from which the data was captured.
bufThe data to be saved.
unitsizeThe number of bytes per sample.
unitsThe number of samples.
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR upon other errors.

Definition at line 213 of file session_file.c.

References sr_dev_inst::driver, sr_probe::enabled, sr_probe::name, sr_dev_driver::name, sr_dev_inst::probes, SR_CONF_SAMPLERATE, sr_config_get(), sr_dev_has_option(), sr_err, SR_ERR, SR_ERR_ARG, sr_info, SR_OK, sr_samplerate_string(), and sr_probe::trigger.

+ Here is the call graph for this function:

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

Add an event source for a file descriptor.

Parameters
fdThe file descriptor.
eventsEvents to check for.
timeoutMax time to wait before the callback is called, ignored if 0.
cbCallback function to add. Must not be NULL.
cb_dataData for the callback function. Can be NULL.
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR_MALLOC upon memory allocation errors.

Definition at line 593 of file session.c.

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

Add an event source for a GIOChannel.

Parameters
channelThe GIOChannel.
eventsEvents to poll on.
timeoutMax time to wait before the callback is called, ignored if 0.
cbCallback function to add. Must not be NULL.
cb_dataData for the callback function. Can be NULL.
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR_MALLOC upon memory allocation errors.

Definition at line 634 of file session.c.

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

Add an event source for a GPollFD.

Parameters
pollfdThe GPollFD.
timeoutMax time to wait before the callback is called, ignored if 0.
cbCallback function to add. Must not be NULL.
cb_dataData for the callback function. Can be NULL.
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR_MALLOC upon memory allocation errors.

Definition at line 615 of file session.c.

int sr_session_source_remove ( int  fd)

Remove the source belonging to the specified file descriptor.

Parameters
fdThe file 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.

Definition at line 716 of file session.c.

int sr_session_source_remove_channel ( GIOChannel *  channel)

Remove the source belonging to the specified channel.

Parameters
channelThe channel 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.

Definition at line 744 of file session.c.

int sr_session_source_remove_pollfd ( GPollFD *  pollfd)

Remove the source belonging to the specified poll descriptor.

Parameters
pollfdThe 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.

Definition at line 730 of file session.c.

int sr_session_start ( void  )

Start a session.

There can only be one session at a time.

Returns
SR_OK upon success, SR_ERR upon errors.

Definition at line 307 of file session.c.

References sr_dev_driver::dev_acquisition_start, sr_session::devs, sr_dev_inst::driver, sr_err, SR_ERR_BUG, sr_info, 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.

Returns
SR_OK upon success, SR_ERR_BUG if no session exists.

Definition at line 429 of file session.c.

References sr_session::abort_session, sr_err, SR_ERR_BUG, SR_OK, and sr_session::stop_mutex.

Variable Documentation

struct sr_session* session

Definition at line 69 of file session.c.

struct sr_session* session

Definition at line 69 of file session.c.

Referenced by sr_session_new().

SR_PRIV struct sr_dev_driver session_driver

Referenced by sr_session_load().