Module version

Source
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 the TARGET_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 project COMPATIBILITY.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.