Receiving samples from the PG2SDR

Data Structures
struct	pg2sdr_sample_buffer
	Sample buffer passed to pg2sdr_stream_callback. More...

Typedefs
typedef bool(*	pg2sdr_stream_callback) (pg2sdr_device *dev, pg2sdr_sample_buffer *buffer, void *user_data)
	Callback type that receives sample buffers.

Functions
int	pg2sdr_stream_data (pg2sdr_device *dev, pg2sdr_stream_callback callback, void *user_data)
	Stream ADC data and pass converted samples to user callback.
int	pg2sdr_stop_streaming (pg2sdr_device *dev)
	Halt data streaming.
void	pg2sdr_release_buffer (pg2sdr_sample_buffer *buffer)
	Free a sample buffer previously passed to a pg2sdr_stream_callback callback.

Detailed Description

.. some overview description goes here ..

Typedef Documentation

pg2sdr_stream_callback

typedef bool(* pg2sdr_stream_callback) (pg2sdr_device *dev, pg2sdr_sample_buffer *buffer, void *user_data)

Callback type that receives sample buffers.

While streaming data with pg2sdr_stream_data(), this callback is repeatedly called as samples are received.

If the callback returns true, the provided buffer is immediately freed. If the callback returns false, then it is the responsibility of the user code to eventually call pg2sdr_release_buffer() when the buffer is no longer needed. Sample buffers are heap-allocated as needed, so failing to release buffers will eventually exhaust available memory.

Parameters

[in]	dev	the device generating this callback
[in]	buffer	Newly received samples to be processed. This buffer remains valid until either the callback function returns non-zero, or pg2sdr_release_buffer() is called.
[in]	user_data	The opaque user_data value passed to pg2sdr_stream_data()

Return values

false	caller will not free buffer
true	caller will automatically free buffer

Function Documentation

pg2sdr_release_buffer()

void pg2sdr_release_buffer

(

pg2sdr_sample_buffer *

buffer

)

Free a sample buffer previously passed to a pg2sdr_stream_callback callback.

If a pg2sdr_stream_callback returns 0, then the sample buffer that was passed to that callback is not automatically freed and can continue to be used by user code. When user code has finished using the buffer, it should be explicitly freed by calling pg2sdr_release_buffer().

Parameters

[in]

buffer

the buffer to free

pg2sdr_stop_streaming()

int pg2sdr_stop_streaming

(

pg2sdr_device *

dev

)

Halt data streaming.

Stops ongoing data streaming, and makes the current call to pg2sdr_stream_data() return normally after it has finished processing any outstanding data.

This can be safely called from within a pg2sdr_stream_callback callback if needed, or can be called concurrently from a different thread.

Parameters

[in]

dev

the device that should stop streaming data

Return values

PG2SDR_SUCCESS	success, pg2sdr_stream_data() will return at some point soon
PG2SDR_ERROR_BAD_STATE	no concurrent call to pg2sdr_stream_data() is in progress
<0	negative error code on failure

See also

pg2sdr_stream_data()

pg2sdr_stream_data()

int pg2sdr_stream_data	(	pg2sdr_device *	dev,
		pg2sdr_stream_callback	callback,
		void *	user_data
	)

Stream ADC data and pass converted samples to user callback.

This function is the core of the sample capture process. It completes configuration of the PG2SDR device and then begins to stream ADC samples from the device, calling the user-provided callback as data becomes available.

pg2sdr_stream_data() implicitly calls pg2sdr_apply_changes() as part of configuring the device, and any possible errors returned by pg2sdr_apply_changes() can also be returned by pg2sdr_stream_data()

pg2sdr_stream_data() will block indefinitely, repeatedly receiving data and calling the user callback (callback), until either pg2sdr_stop_streaming() is called or an error occurs. Callers may want to call this in a dedicated thread if they have other processing that needs to happen in parallel with data capture.

Calls to callback are made from the same thread that called pg2sdr_stream_data(), and are made in order of increasing sample timestamp. The provided callback should return promptly, as data I/O is blocked while the callback is executing and samples may be dropped if the callback takes too long to return.

Only one call to pg2sdr_stream_data() can be outstanding at any particular time. Attempts to call it again while a call is active will return PG2SDR_ERROR_BAD_STATE.

Streaming of data can be halted by calling pg2sdr_stop_streaming(), either from within execution of callback or from a separate thread. This will cause pg2sdr_stream_data() to stop streaming data and return normally.

Parameters

[in]	dev	the device to stream data from
[in]	callback	a user callback function to call for each received block of sample data
[in]	user_data	an opaque value to pass through to the user callback function

Return values

PG2SDR_SUCCESS	normal termination of streaming
PG2SDR_ERROR_BAD_STATE	concurrent call to pg2sdr_stream_data() active
<0	negative error code on failure

See also

pg2sdr_stop_streaming()

pg2sdr_apply_changes()