libsigrok  0.3.0
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerations 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_dev_list (GSList **devlist)
 List all device instances attached 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 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 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 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 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...
 
int sr_session_save_init (const char *filename, uint64_t samplerate, char **channels)
 Initialize a saved session file. More...
 
int sr_session_append (const char *filename, unsigned char *buf, int unitsize, int units)
 Append data to an existing session 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_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
filenameThe name of the filename to append to. Must not be NULL.
bufThe data to be appended.
unitsizeThe number of bytes per sample.
unitsThe number of samples.
Return values
SR_OKSuccess
SR_ERR_ARGInvalid arguments
SR_ERROther 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
cbFunction to call when a chunk of data is received. Must not be NULL.
cb_dataOpaque pointer passed in by the caller.
Return values
SR_OKSuccess.
SR_ERR_BUGNo 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_OKSuccess.
SR_ERR_BUGNo 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_OKSuccess.
SR_ERR_BUGNo 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
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.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid argument.
SR_ERR_BUGNo 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
devlistA 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_OKSuccess.
SR_ERRInvalid 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_OKSuccess.
SR_ERR_BUGNo 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
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 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  )

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
NULLError.
otherA 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_OKSuccess.
SR_ERR_BUGError 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
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.
Return values
SR_OKSuccess
SR_ERR_ARGInvalid arguments
SR_ERROther 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
filenameThe name of the filename to save the current session as. Must not be NULL.
samplerateThe samplerate to store for this session.
channelsA NULL-terminated array of strings containing the names of all the channels active in this session.
Return values
SR_OKSuccess
SR_ERR_ARGInvalid arguments
SR_ERROther 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
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.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid argument.
SR_ERR_MALLOCMemory 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
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.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid argument.
SR_ERR_MALLOCMemory 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
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.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid argument.
SR_ERR_MALLOCMemory 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
fdThe file descriptor for which the source should be removed.
Return values
SR_OKSuccess
SR_ERR_ARGInvalid argument
SR_ERR_MALLOCMemory allocation error.
SR_ERR_BUGInternal 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
channelThe channel for which the source should be removed.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid argument.
SR_ERR_MALLOCMemory 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
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.
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_OKSuccess.
SR_ERRError 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_OKSuccess.
SR_ERR_BUGNo 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.

Referenced by sr_session_new().

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().