Expand description
Version related constants and functions.
This module contains functions and constants relating to the version of the PulseAudio (PA) client system library.
§Dynamic compatibility
As discussed in the project COMPATIBILITY.md
file, compatibility is offered for multiple
versions of the PA client system library, with feature flags adapting the crate to changes made
in the API of newer PA versions.
Note that the minimum supported version of PA is v5.0.
§Runtime checking
The following functions are provided to retrieve and compare the version of the actual PA client system library in use at runtime:
- The
get_library_version()
function obtains the version string the system library provides. - The
get_library_version_numbers()
function uses the previous function and attempts to parse the version string it returns into numeric form for comparison purposes. - The
compare_with_library_version()
function uses the previous function and allows comparing a provided major and minor version number with what it returned. - The
library_version_is_too_old()
function uses the previous function to compare against theTARGET_VERSION
constant version numbers. This constant varies depending upon PA version feature flags, and thus this can be used to check that a program is not being run on a system with too old of a version of PA, helping combat the “forward” compatibility problem discussed in the projectCOMPATIBILITY.md
documentation.
§Dynamic constants
The version constants defined here mostly relate to those provided in the PA C headers, and are likely of little use to most projects. They are set dynamically, depending upon the feature flags used, or in other words the level of minimum compatibility support selected. Note that PA version feature flags are only introduced when new versions of PA introduce changes to its API that would require one. The version numbers associated with each PA version feature flag are those from the PA version that required introduction of that feature flag.
As an example to clarify, if the “newest” PA version feature flag enabled is pa_v8
(which
obviously corresponds to a minimum compatibility level of PA version 8.0), then the
TARGET_VERSION
constant is set to (8, 0)
. The “next-newest” feature flag is pa_v11
,
which if enabled would bump it up to (11, 0)
.
Structs§
- Error
- Error from trying to parse the runtime PulseAudio system library version string.
Enums§
- Compatibility
- PulseAudio version compatibility.
Constants§
- API_
VERSION - The current API version.
- PROTOCOL_
VERSION - Protocol version of targetted version.
- TARGET_
VERSION - Version number of targetted version.
- TARGET_
VERSION_ STRING - Version string of targetted version.
Functions§
- compare_
with_ library_ version - Compares the supplied version with that of the runtime system library.
- get_
compatibility - Get selected compatibility level.
- get_
library_ version - Gets the version string of the (PulseAudio client system) library actually in use at runtime.
- get_
library_ version_ numbers - Tries to convert the runtime system library version to numeric major, minor and micro form, for comparison purposes.
- library_
version_ is_ too_ old - Checks whether the version of the running system library is older than the version corresponding to the compatibility level selected via the available feature flags.