Library context and init/deinit

Macros
#define	PG2SDR_API_VERSION   0x01000100U
	Compile-time library API version.

Typedefs
typedef struct pg2sdr__context	pg2sdr_context
	An opaque handle for library state.
typedef void(*	pg2sdr_log_callback) (pg2sdr_context *context, pg2sdr_log_level level, const char *message)
	Callback function passed to pg2sdr_set_log_callback()

Enumerations
enum	pg2sdr_log_level { PG2SDR_LOG_DEBUG , PG2SDR_LOG_INFO , PG2SDR_LOG_ERROR }
	Severity of log messages passed to pg2sdr_log_callback() More...

Functions
uint32_t	pg2sdr_get_api_version (void)
	Get runtime library API version.
int	pg2sdr_init (pg2sdr_context **ctx)
	Allocate a new library context.
int	pg2sdr_exit (pg2sdr_context *ctx)
	Free a library context.
int	pg2sdr_set_log_callback (pg2sdr_context *ctx, pg2sdr_log_callback callback)
	Set a callback to receive library logging.

Detailed Description

Library contexts allow for multiple users of the pg2sdr library in the same process, without requiring coordination between the different users. Each library user should allocate a separate context, and pass it to the various API functions that expect a context.

There is a context associated with each pg2sdr_device instance. APIs that accept pg2sdr_device arguments implicitly use the associated context.

The lifetime of contexts is managed by pg2sdr_init() and pg2sdr_exit().

Macro Definition Documentation

PG2SDR_API_VERSION

#define PG2SDR_API_VERSION   0x01000100U

Compile-time library API version.

A monotonically-increasing unsigned integer that will be increased on API change. This can be used to detect the presence of functions added in later library versions. (Currently, nothing makes use of this as there's only one library API released so far).

Typedef Documentation

pg2sdr_context

typedef struct pg2sdr__context pg2sdr_context

An opaque handle for library state.

Library context is represented as a pointer to an opaque pg2sdr_context struct, where the details of the struct are internal to the library.

See also

pg2sdr_init()

pg2sdr_exit()

pg2sdr_log_callback

typedef void(* pg2sdr_log_callback) (pg2sdr_context *context, pg2sdr_log_level level, const char *message)

Callback function passed to pg2sdr_set_log_callback()

Parameters

context	the library context associated with this log message
level	the log level of this message
message	an ASCII message to log

Enumeration Type Documentation

pg2sdr_log_level

enum pg2sdr_log_level

Severity of log messages passed to pg2sdr_log_callback()

Enumerator
PG2SDR_LOG_DEBUG	debug messages
PG2SDR_LOG_INFO	informational messages
PG2SDR_LOG_ERROR	errors

Function Documentation

pg2sdr_exit()

int pg2sdr_exit

(

pg2sdr_context *

ctx

)

Free a library context.

Releases resources associated with a context previously allocated by pg2sdr_init().

Must not be called while there are in-progress API calls using the context.

After a call to pg2sdr_exit(), the context is no longer valid and should not be used.

Parameters

[in]

ctx

The context to free

Return values

PG2SDR_SUCCESS	success
<0	negative error code on failure

pg2sdr_get_api_version()

uint32_t pg2sdr_get_api_version

(

void

)

Get runtime library API version.

This gets the runtime API version of the library that was actually linked to. It may be higher than the version originally compiled against, if there were ABI-compatible upgrades to the installed library in the meantime.

If the returned value is less than PG2SDR_API_VERSION, then you have a version skew problem – your executable is linked to an older library version than the version it was compiled for.

Returns

the PG2SDR_API_VERSION value of the currently linked library

pg2sdr_init()

int pg2sdr_init

(

pg2sdr_context **

ctx

)

Allocate a new library context.

Context should be eventually freed by calling pg2sdr_exit()

Parameters

[out]

ctx

Storage for a pointer to the newly allocated context

Return values

PG2SDR_SUCCESS	success
PG2SDR_ERROR_LIBRARY_VERSION	runtime library version is older than version compiled against
<0	negative error code on failure

pg2sdr_set_log_callback()

int pg2sdr_set_log_callback	(	pg2sdr_context *	ctx,
		pg2sdr_log_callback	callback
	)

Set a callback to receive library logging.

By default, libpg2sdr will log INFO and ERROR messages to stderr. If the PG2SDR_DEBUG environment variable is set, it will also log DEBUG messages to stderr.

If log messages should be handled differently, provide a logging callback by calling this function. libpg2sdr will call the logging callback to perform logging, replacing the default behaviour.

Each library context has a separate log callback setting.

Logging callbacks must be threadsafe.

Parameters

[in]	ctx	The library context to change
[in]	callback	The callback to call for each log message

Return values

PG2SDR_SUCCESS	success
<0	negative error code on failure