libpulse_sys/
version.rs

1// Copyright 2017 Lyndon Brown
2//
3// This file is part of the PulseAudio Rust language linking library.
4//
5// Licensed under the MIT license or the Apache license (version 2.0), at your option. You may not
6// copy, modify, or distribute this file except in compliance with said license. You can find copies
7// of these licenses either in the LICENSE-MIT and LICENSE-APACHE files, or alternatively at
8// <http://opensource.org/licenses/MIT> and <http://www.apache.org/licenses/LICENSE-2.0>
9// respectively.
10//
11// Portions of documentation are copied from the LGPL 2.1+ licensed PulseAudio C headers on a
12// fair-use basis, as discussed in the overall project readme (available in the git repository).
13
14//! Version constants and functions.
15//!
16//! This module contains functions and constants relating to PulseAudio (PA) client API version
17//! compatibility.
18//!
19//! # Dynamic compatibility
20//!
21//! As discussed in the project `COMPATIBILITY.md` file, support is offered for multiple versions of
22//! the PA client library, with changes made in newer versions being guarded with Cargo feature
23//! flags.
24//!
25//! Note that the minimum supported version of PA is v5.0.
26//!
27//! # Dynamic constants
28//!
29//! The version constants defined here mostly relate to those provided in the PA C headers. They are
30//! typically only updated following a new **major** release of PA. They are also dynamic, depending
31//! upon the level of compatibility support selected at compile time via the available Cargo feature
32//! flags.
33//!
34//! Note that there is **not** a one-to-one mapping of major PA version to compatibility feature. A
35//! new such feature is only introduced where actual changes in the PA client API require one
36//! because they introduce changes such as the addition of new functions.
37//!
38//! It is not obvious how the constants relate to version compatibility levels without reading the
39//! code, so this needs explaining. Simply put, version numbers are updated typically only on
40//! release of a new major version of PA, and update the existing version number associated with the
41//! current latest compatibility level selector when there are no changes requiring a new
42//! compatibility feature.
43//!
44//! Thus, for instance, PA versions 8 and 12 introduced additions to the API and have corresponding
45//! compatibility features to control the inclusion of those additions on top of the minimum level
46//! of support offered. If you have v8 compatibility enabled but not v12, then the version number
47//! indicated will be v11.
48
49use std::os::raw::c_char;
50
51/// PulseAudio version compatibility.
52///
53/// Used for indicating what level of PA version compatibility was selected at compile time via
54/// Cargo feature flags.
55///
56/// Note that PA v4 is the oldest supported.
57#[non_exhaustive]
58pub enum Compatibility {
59    /// Support for PA version 5+ selected.
60    V5Plus,
61    /// Support for PA version 6+ selected.
62    V6Plus,
63    /// Support for PA version 8+ selected.
64    V8Plus,
65    /// Support for PA version 12+ selected.
66    V12Plus,
67    /// Support for PA version 13+ selected.
68    V13Plus,
69    /// Support for PA version 14+ selected.
70    V14Plus,
71    /// Support for PA version 15+ selected.
72    V15Plus,
73}
74
75// Latest
76#[cfg(any(feature = "pa_v15", all(doc, not(feature = "pa_v6"))))]
77mod actual {
78    pub const COMPATIBILITY: super::Compatibility = super::Compatibility::V15Plus;
79    pub const TARGET_VERSION_STRING: &str = "15.0.0";
80    pub const TARGET_VERSION: (u8, u8) = (15, 0);
81    pub const PA_PROTOCOL_VERSION: u16 = 35;
82}
83
84// Pre-v15
85#[cfg(all(feature = "pa_v14", not(feature = "pa_v15")))]
86mod actual {
87    pub const COMPATIBILITY: super::Compatibility = super::Compatibility::V14Plus;
88    pub const TARGET_VERSION_STRING: &str = "14.0.0";
89    pub const TARGET_VERSION: (u8, u8) = (14, 0);
90    pub const PA_PROTOCOL_VERSION: u16 = 34;
91}
92
93// Pre-v14
94#[cfg(all(feature = "pa_v13", not(feature = "pa_v14")))]
95mod actual {
96    pub const COMPATIBILITY: super::Compatibility = super::Compatibility::V13Plus;
97    pub const TARGET_VERSION_STRING: &str = "13.0.0";
98    pub const TARGET_VERSION: (u8, u8) = (13, 0);
99    pub const PA_PROTOCOL_VERSION: u16 = 33;
100}
101
102// Pre-v13
103#[cfg(all(feature = "pa_v12", not(feature = "pa_v13")))]
104mod actual {
105    pub const COMPATIBILITY: super::Compatibility = super::Compatibility::V12Plus;
106    pub const TARGET_VERSION_STRING: &str = "12.0.0";
107    pub const TARGET_VERSION: (u8, u8) = (12, 0);
108    pub const PA_PROTOCOL_VERSION: u16 = 32;
109}
110
111// Pre-v12
112#[cfg(all(feature = "pa_v8", not(feature = "pa_v12")))]
113mod actual {
114    pub const COMPATIBILITY: super::Compatibility = super::Compatibility::V8Plus;
115    pub const TARGET_VERSION_STRING: &str = "8.0.0";
116    pub const TARGET_VERSION: (u8, u8) = (8, 0);
117    pub const PA_PROTOCOL_VERSION: u16 = 30;
118}
119
120// Pre-v8
121#[cfg(all(feature = "pa_v6", not(feature = "pa_v8")))]
122mod actual {
123    pub const COMPATIBILITY: super::Compatibility = super::Compatibility::V6Plus;
124    pub const TARGET_VERSION_STRING: &str = "6.0.0";
125    pub const TARGET_VERSION: (u8, u8) = (6, 0);
126    pub const PA_PROTOCOL_VERSION: u16 = 30;
127}
128
129// Pre-v6
130#[cfg(all(not(doc), not(feature = "pa_v6")))]
131mod actual {
132    pub const COMPATIBILITY: super::Compatibility = super::Compatibility::V5Plus;
133    pub const TARGET_VERSION_STRING: &str = "5.0.0";
134    pub const TARGET_VERSION: (u8, u8) = (5, 0);
135    pub const PA_PROTOCOL_VERSION: u16 = 29;
136}
137
138/// Version string of targetted version.
139///
140/// See the module level documentation for an explanation.
141pub const TARGET_VERSION_STRING: &str = actual::TARGET_VERSION_STRING;
142
143/// Version number of targetted version.
144///
145/// See the module level documentation for an explanation.
146pub const TARGET_VERSION: (u8, u8) = actual::TARGET_VERSION;
147
148/// Protocol version of targetted version.
149///
150/// See the module level documentation for an explanation.
151pub const PA_PROTOCOL_VERSION: u16 = actual::PA_PROTOCOL_VERSION;
152
153/// The current API version.
154///
155/// Note, this has not been updated since PA v0.9.11. It is presumed that it would only ever be
156/// updated for backwards-breaking API changes.
157pub const PA_API_VERSION: u8 = 12;
158
159/// Get selected compatibility level.
160///
161/// Returns indication of the level of PulseAudio version compatibility selected at compile time via
162/// Cargo feature flags.
163#[inline(always)]
164pub const fn get_compatibility() -> Compatibility {
165    actual::COMPATIBILITY
166}
167
168#[link(name = "pulse")]
169extern "C" {
170    pub fn pa_get_library_version() -> *const c_char;
171}
libpulse_sys/version.rs

libpulse_sys/
version.rs
