Enumerations
enum	pg2sdr_error { PG2SDR_SUCCESS = 0 , PG2SDR_ERROR_NOT_FOUND = -1 , PG2SDR_ERROR_DISCONNECTED = -2 , PG2SDR_ERROR_BAD_ARGUMENT = -3 , PG2SDR_ERROR_NO_MEMORY = -4 , PG2SDR_ERROR_NOT_IMPLEMENTED = -5 , PG2SDR_ERROR_FIRMWARE_MISMATCH = -6 , PG2SDR_ERROR_MULTIPLE_DEVICES = -7 , PG2SDR_ERROR_BUSY = -8 , PG2SDR_ERROR_BAD_STATE = -9 , PG2SDR_ERROR_TIMEOUT = -10 , PG2SDR_ERROR_CORRUPTION = -11 , PG2SDR_ERROR_ACCESS = -12 , PG2SDR_ERROR_LIBRARY_VERSION = -13 , PG2SDR_ERROR_TRANSFER_OTHER = -200 , PG2SDR_ERROR_TRANSFER_STALL = -201 , PG2SDR_ERROR_TRANSFER_OVERFLOW = -202 , PG2SDR_ERROR_TRANSFER_FORMAT = -203 , PG2SDR_ERROR_TUNER_DETECT = -300 , PG2SDR_ERROR_TUNER_PLL_LOCK = -301 , PG2SDR_ERROR_TUNER_PLL_RANGE = -302 , PG2SDR_ERROR_TUNER_I2C = -303 , PG2SDR_ERROR_ADC_RATE_RANGE = -304 , PG2SDR_ERROR_SYSTEM_MAX = -1000 , PG2SDR_ERROR_SYSTEM_MIN = -1999 , PG2SDR_ERROR_LIBUSB_MAX = -2000 , PG2SDR_ERROR_LIBUSB_MIN = -2999 }
	Enumeration of possible negative error codes. More...

Functions
const char *	pg2sdr_strerror (int error)
	Format a pg2sdr error code as a human-readable error message.

const char *	pg2sdr_strerror_r (int error, char *buf, size_t buflen)
	Format a pg2sdr error code as a human-readable error message.

Detailed Description

Most libpg2sdr API functions return an integer, with 0 indicating success and negative values representing errors. A few APIs can also return positive values on success.

Negative error codes are chosen from the pg2sdr_error enumeration. Users of the library API can directly match on these values to handle specific errors differently, or use pg2sdr_strerror() and pg2sdr_strerror_r() to format the errors for human consumption.

When libpg2sdr encounters an error from a system call or libusb, that error is remapped into a value within the PG2SDR_ERROR_SYSTEM_MIN .. PG2SDR_ERROR_SYSTEM_MAX or PG2SDR_ERROR_LIBUSB_MIN .. PG2SDR_ERROR_LIBUSB_MAX ranges, preserving the underlying error. pg2sdr_strerror() knows how to interpret values in this range by calling strerror() or libusb_strerror() as needed.

Some error codes can be returned from any function, and are not individually documented in each function:

PG2SDR_ERROR_SYSTEM_MIN .. PG2SDR_ERROR_SYSTEM_MAX are returned if there is an error in a system/library call that sets errno which does not have a more specific PG2SDR_ERROR_* error code.
PG2SDR_ERROR_LIBUSB_MIN .. PG2SDR_ERROR_LIBUSB_MAX are returned if there is an error in a libusb call that does not have a more specific PG2SDR_ERROR_* error code.
PG2SDR_ERROR_NO_MEMORY is returned if memory allocation is needed, but allocation failed.
PG2SDR_ERROR_BAD_ARGUMENT is returned if a NULL device or context pointer is provided
PG2SDR_ERROR_CORRUPTION might be returned if an invalid or freed device or context pointer is provided, but this is just a courtesy to try to detect bugs before heap corruption occurs - callers should not rely on this.
PG2SDR_ERROR_FIRMWARE_MISMATCH is returned if there is an unexpected protocol error in messages exchanged with the device; this generally indicates a bug or a mismatch in firmware versus library versions.
PG2SDR_ERROR_DISCONNECTED is returned if the device has disconnected from the USB bus (might be a power issue!)

Enumeration Type Documentation

◆ pg2sdr_error

enum pg2sdr_error

Enumeration of possible negative error codes.

libpg2sdr API functions return an integer error code, where values >= 0 indicate success and values <0 indicate errors. The pg2sdr_error enumeration describes those error codes.

Enumerator
PG2SDR_SUCCESS	no error
PG2SDR_ERROR_NOT_FOUND	pg2sdr_open_single_device() found no matching devices
PG2SDR_ERROR_DISCONNECTED	Device unexpectedly disconnected
PG2SDR_ERROR_BAD_ARGUMENT	Bad argument to API call
PG2SDR_ERROR_NO_MEMORY	Memory allocation failed
PG2SDR_ERROR_NOT_IMPLEMENTED	Operation not implemented
PG2SDR_ERROR_FIRMWARE_MISMATCH	Host/firmware version mismatch
PG2SDR_ERROR_MULTIPLE_DEVICES	pg2sdr_open_single_device() found more than one matching device
PG2SDR_ERROR_BUSY	Device already in use
PG2SDR_ERROR_BAD_STATE	Operation not possible in this state
PG2SDR_ERROR_TIMEOUT	Operation timed out
PG2SDR_ERROR_CORRUPTION	Heap corruption, double-free, or use-after-free detected
PG2SDR_ERROR_ACCESS	Insufficient permissions to access device
PG2SDR_ERROR_LIBRARY_VERSION	Library version is older than expected version
PG2SDR_ERROR_TRANSFER_OTHER	Unexpected libusb transfer status
PG2SDR_ERROR_TRANSFER_STALL	Bulk endpoint stalled (libusb transfer status LIBUSB_TRANSFER_STALL)
PG2SDR_ERROR_TRANSFER_OVERFLOW	Received unexpected data on bulk endpoint (libusb transfer status LIBUSB_TRANSFER_OVERFLOW)
PG2SDR_ERROR_TRANSFER_FORMAT	Received malformed data on bulk endpoint
PG2SDR_ERROR_TUNER_DETECT	Tuner not present on I2C bus
PG2SDR_ERROR_TUNER_PLL_LOCK	Tuner LO PLL did not lock
PG2SDR_ERROR_TUNER_PLL_RANGE	Required tuner LO PLL frequency out of range
PG2SDR_ERROR_TUNER_I2C	Tuner I2C bus communication error
PG2SDR_ERROR_ADC_RATE_RANGE	Required ADC sample rate out of range for ADC hardware
PG2SDR_ERROR_SYSTEM_MAX	Upper end of remapped errno range
PG2SDR_ERROR_SYSTEM_MIN	Lower end of remapped errno range
PG2SDR_ERROR_LIBUSB_MAX	Upper end of remapped libusb error range
PG2SDR_ERROR_LIBUSB_MIN	Lower end of remapped libusb error range

Function Documentation

◆ pg2sdr_strerror()

const char * pg2sdr_strerror ( int error )

Format a pg2sdr error code as a human-readable error message.

This function is not threadsafe; the returned message may be a pointer to a static buffer area that is reused on each call. For a threadsafe version, use pg2sdr_strerror_r().

Parameters

[in] error an error code returned by the PG2SDR API

Returns: an ASCIIZ error message, that may point to shared buffer space

◆ pg2sdr_strerror_r()

const char * pg2sdr_strerror_r	(	int	error,
		char *	buf,
		size_t	buflen
	)

Format a pg2sdr error code as a human-readable error message.

This is the threadsafe variant of pg2sdr_strerror(), using a user- provided buffer if needed.

Note that in cases where the error message is fixed, buf is not used and a pointer to the fixed error message is returned directly.