Data Structures
struct	pg2sdr_usb_device
	Representation of an unopened PG2SDR device on the USB bus. More...

Typedefs
typedef struct pg2sdr__device	pg2sdr_device
	Opaque type representing the state of an opened PG2SDR device.

Functions
ssize_t	pg2sdr_discover_devices (pg2sdr_context ctx, const char match_serial_prefix, const char match_ports, pg2sdr_usb_device **usb_device_list)
	Enumerate available pg2sdr devices.

void	pg2sdr_free_device_list (pg2sdr_usb_device **usb_device_list)
	Free a device list previously allocated by pg2sdr_discover_devices()

int	pg2sdr_open_device (pg2sdr_context ctx, pg2sdr_usb_device usb_device, pg2sdr_device **device)
	Open a device previously discovered by pg2sdr_discover_devices()

int	pg2sdr_open_libusb_device (pg2sdr_context ctx, libusb_device lu_device, pg2sdr_device **device)
	Open a device directly from a libusb device.

int	pg2sdr_open_single_device (pg2sdr_context ctx, const char serial_prefix, const char ports, pg2sdr_device *device)
	Open a single device by serial number or port path.

int	pg2sdr_close_device (pg2sdr_device *dev)
	Close a pg2sdr device.

const char *	pg2sdr_get_serial (pg2sdr_device *dev)
	Get the serial number of an opened device.

const char *	pg2sdr_get_ports (pg2sdr_device *dev)
	Get the USB port path of an opened device.

uint32_t	pg2sdr_get_firmware_version (pg2sdr_device *dev)
	Get the firmware version of an opened device.

Detailed Description

This group of functions allow a libpg2sdr user to enumerate available PG2SDR devices, and open them for streaming.

Two main datatypes are used by the library:

pg2sdr_usb_device describes a single device available on the USB bus, without actively opening the device for streaming data. Arrays of pg2sdr_usb_device are created by pg2sdr_discover_devices() during device discovery, and should be freed by calling pg2sdr_free_device_list() when no longer required.

pg2sdr_device is an opaque type used after device discovery has completed, to represent a device that has been actively opened for use, together with the associated library state. Instances of pg2sdr_device are allocated by pg2sdr_open_device(), pg2sdr_open_libusb_device(), or pg2sdr_open_single_device(), and should be closed/freed by calling pg2sdr_close_device() when no longer required.

Typedef Documentation

◆ pg2sdr_device

typedef struct pg2sdr__device pg2sdr_device

Opaque type representing the state of an opened PG2SDR device.

Allocation of these instances is managed by the library, users of the library deal only in terms of pointers to this type.

See also: pg2sdr_open_device(); pg2sdr_open_libusb_device(); pg2sdr_open_single_device(); pg2sdr_close_device()

Function Documentation

◆ pg2sdr_close_device()

int pg2sdr_close_device ( pg2sdr_device * dev )

Close a pg2sdr device.

If the device is currently streaming data, PG2SDR_ERROR_BAD_STATE will be returned. To avoid this, call pg2sdr_stop_streaming() and wait for pg2sdr_stream_data() to return before calling pg2sdr_close_device().

The device handle should not be used after being closed.

Parameters

[in] dev the device to close

Return values

PG2SDR_SUCCESS	success
PG2SDR_ERROR_BAD_STATE	device is currently streaming data, cannot close
<0	negative error code on failure

◆ pg2sdr_discover_devices()

ssize_t pg2sdr_discover_devices	(	pg2sdr_context *	ctx,
		const char *	match_serial_prefix,
		const char *	match_ports,
		pg2sdr_usb_device ***	usb_device_list
	)

Enumerate available pg2sdr devices.

Enumerates available devices and creates an array of pg2sdr_usb_device *, one per discovered device.

Optionally, a serial prefix and/or port path can be provided to limit the search to only devices matching that prefix or path.

The caller should not modify the returned device list. Once the device list is no longer required, pg2sdr_free_device_list() should be called to free storage associated with the list.

The final value in the array is a sentinel NULL pointer. The return value indicates the number of devices in the array (possibly zero), not including the sentinel.

Parameters

[in]	ctx	A library context.
[in]	match_serial_prefix	if not NULL, an ASCIIZ serial number prefix to match devices against
[in]	match_ports	if not NULL, an ASCIIZ port path to match devices against
[out]	usb_device_list	Storage for a pointer to an array of pg2sdr_usb_device

Return values

>=0	success, return value indicates size of returned array
<0	failure, negative error code

See also: pg2sdr_free_device_list; pg2sdr_open_device

◆ pg2sdr_free_device_list()

void pg2sdr_free_device_list ( pg2sdr_usb_device ** usb_device_list )

Free a device list previously allocated by pg2sdr_discover_devices()

After a device list is freed, the individual pg2sdr_usb_device instances in the list should not be used.

Parameters

[in] usb_device_list The device list to free

◆ pg2sdr_get_firmware_version()

uint32_t pg2sdr_get_firmware_version ( pg2sdr_device * dev )

Get the firmware version of an opened device.

Firmware versions are 32-bit unsigned integers that can be directly compared.

Parameters

[in] dev the device to query

Returns: the firmware version of the connected device, or 0 if the given device is not valid.

◆ pg2sdr_get_ports()

const char * pg2sdr_get_ports ( pg2sdr_device * dev )

Get the USB port path of an opened device.

The USB port path represents the physical port a device is connected to, in the same format used by pg2sdr_usb_device::ports and the "port" parameter of pg2sdr_open_single_device().

The returned string is a shared value specific to the device instance and should not be modified or freed, or used after the device is closed.

Parameters

[in] dev the device to query

Returns: pointer to an ASCIIZ string, or NULL if the given device is not valid.

◆ pg2sdr_get_serial()

const char * pg2sdr_get_serial ( pg2sdr_device * dev )

Get the serial number of an opened device.

The returned string is a shared value specific to the device instance and should not be modified or freed, or used after the device is closed.

Parameters

[in] dev the device to query

Returns: pointer to an ASCIIZ string, or NULL if the given device is not valid.

◆ pg2sdr_open_device()

int pg2sdr_open_device	(	pg2sdr_context *	ctx,
		pg2sdr_usb_device *	usb_device,
		pg2sdr_device **	device
	)

Open a device previously discovered by pg2sdr_discover_devices()

Parameters

[in]	ctx	The library context that allocated the device
[in]	usb_device	The USB device to open
[out]	device	Storage for the newly opened device instance

Return values

PG2SDR_SUCCESS	success
PG2SDR_ERROR_BUSY	device is already in use by another process
PG2SDR_ERROR_ACCESS	insufficient permissions to open device
<0	negative error code on failure

See also: pg2sdr_discover_devices(); pg2sdr_close_device()

◆ pg2sdr_open_libusb_device()

int pg2sdr_open_libusb_device	(	pg2sdr_context *	ctx,
		libusb_device *	lu_device,
		pg2sdr_device **	device
	)

Open a device directly from a libusb device.

No special checks are done to see if the device really is a PG2SDR, it's assumed to be a PG2SDR and used directly.

Parameters

[in]	ctx	The library context that allocated the device
[in]	lu_device	The libusb device to open
[out]	device	Storage for the newly opened device instance

Return values

PG2SDR_SUCCESS	success
PG2SDR_ERROR_BUSY	device is already in use by another process
PG2SDR_ERROR_ACCESS	insufficient permissions to open device
<0	negative error code on failure

See also: pg2sdr_close_device()

◆ pg2sdr_open_single_device()

int pg2sdr_open_single_device	(	pg2sdr_context *	ctx,
		const char *	serial_prefix,
		const char *	ports,
		pg2sdr_device **	device
	)

Open a single device by serial number or port path.

Search for a single connected pg2sdr device and open it. This is the preferred way for simple single-device library users to open a device.

Optionally, a serial prefix and/or port path can be provided to limit the search to only devices matching that prefix or path.

The search must be unambiguous – exactly one device should match the given criteria. In most cases, there will only be a single pg2sdr device connected, so no special criteria are needed. If more than one device is connected, then match_serial_prefix or match_ports must be provided to select a single device.

Parameters

[in]	ctx	The library context to use to open the device
[in]	serial_prefix	if not NULL, an ASCIIZ serial number prefix to match devices against
[in]	ports	if not NULL, an ASCIIZ port path to match devices against
[out]	device	Storage for the newly opened device instance

Return values

PG2SDR_SUCCESS	success
PG2SDR_ERROR_NOT_FOUND	no matching device found
PG2SDR_ERROR_MULTIPLE_DEVICES	more than one matching device found
PG2SDR_ERROR_BUSY	device is already in use by another process
PG2SDR_ERROR_ACCESS	insufficient permissions to open device
<0	negative error code on failure

See also: pg2sdr_close_device()

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ pg2sdr_device

Function Documentation

◆ pg2sdr_close_device()

◆ pg2sdr_discover_devices()

◆ pg2sdr_free_device_list()

◆ pg2sdr_get_firmware_version()

◆ pg2sdr_get_ports()

◆ pg2sdr_get_serial()

◆ pg2sdr_open_device()

◆ pg2sdr_open_libusb_device()

◆ pg2sdr_open_single_device()