1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
//! PulseAudio Rust language binding library.
// This file is part of the PulseAudio Rust language binding.
//
// Copyright (c) 2017 Lyndon Brown
//
// This library is free software; you can redistribute it and/or modify it under the terms of the
// GNU Lesser General Public License as published by the Free Software Foundation; either version
// 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
// even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License along with this library;
// if not, see <http://www.gnu.org/licenses/>.
//! # About
//!
//! This library is a binding that allows Rust code to connect to the PulseAudio sound server via
//! PulseAudio's existing C API. This binding provides a safe(r) Rust interface which might be
//! preferred over the raw C API provided by the underlying `sys` linking crate.
//!
//! The documentation below and throughout this crate have been largely lifted from the C API header
//! files.
//!
//! # Introduction
//!
//! The PulseAudio API comes in two flavours to accommodate different styles of applications and
//! different needs in complexity:
//!
//! * The complete but somewhat complicated to use asynchronous API.
//! * The simplified, easy to use, but limited synchronous API.
//!
//! All strings in PulseAudio are in the UTF-8 encoding, regardless of current locale. Some
//! functions will filter invalid sequences from the string, some will simply fail. To ensure
//! reliable behaviour, make sure everything you pass to the API is valid UTF-8.
//!
//! ## Simple API
//!
//! Use this if you develop your program in synchronous style and just need a way to play or record
//! data on the sound server. This functionality is kept in the separate `libpulse_simple_binding`
//! crate. See that for details.
//!
//! ## Asynchronous API
//!
//! Use this if you develop your programs in asynchronous, event loop based style or if you want to
//! use the advanced features of the PulseAudio API. A guide can be found in the [`::mainloop`]
//! module.
//!
//! By using the built-in threaded main loop, it is possible to achieve a pseudo-synchronous API,
//! which can be useful in synchronous applications where the simple API is insufficient.
//!
//! ## Threads
//!
//! The PulseAudio client libraries are not designed to be directly thread-safe. They are however
//! designed to be re-entrant and thread-aware.
//!
//! To use the libraries in a threaded environment, you must assure that all objects are only used
//! in one thread at a time. Normally, this means that all objects belonging to a single context
//! must be accessed from the same thread.
//!
//! The included main loop implementation is also not thread safe. Take care to make sure event
//! objects are not manipulated when any other code is using the main loop.
//!
//! ## Logging
//!
//! You can configure different logging parameters for the PulseAudio client libraries. The
//! following environment variables are recognized:
//!
//! * `PULSE_LOG`: Maximum log level required. Bigger values result in a more verbose logging
//! output. The following values are recognized:
//! * `0`: Error messages
//! * `1`: Warning messages
//! * `2`: Notice messages
//! * `3`: Info messages
//! * `4`: Debug messages
//! * `PULSE_LOG_SYSLOG`: If defined, force all client libraries to log their output using the
//! `syslog(3)` mechanism. Default behavior is to log all output to `stderr`.
//! * `PULSE_LOG_JOURNAL`: If defined, force all client libraries to log their output using the
//! systemd journal. If both `PULSE_LOG_JOURNAL` and `PULSE_LOG_SYSLOG` are defined, logging to
//! the systemd journal takes a higher precedence. Each message originating library file name and
//! function are included by default through the journal fields `CODE_FILE`, `CODE_FUNC`, and
//! `CODE_LINE`. Any backtrace attached to the logging message is sent through the
//! PulseAudio-specific journal field `PULSE_BACKTRACE`. This environment variable has no effect
//! if PulseAudio was compiled without systemd journal support.
//! * `PULSE_LOG_COLORS`: If defined, enables colored logging output.
//! * `PULSE_LOG_TIME`: If defined, include timestamps with each message.
//! * `PULSE_LOG_FILE`: If defined, include each message originating file name.
//! * `PULSE_LOG_META`: If defined, include each message originating file name and path relative to
//! the PulseAudio source tree root.
//! * `PULSE_LOG_LEVEL`: If defined, include a log level prefix with each message. Respectively, the
//! prefixes "E", "W", "N", "I", "D" stands for
//! Error, Warning, Notice, Info, and Debugging.
//! * `PULSE_LOG_BACKTRACE`: Number of functions to display in the backtrace. If this variable is
//! not defined, or has a value of zero, no backtrace is shown.
//! * `PULSE_LOG_BACKTRACE_SKIP`: Number of backtrace levels to skip, from the function printing the
//! log message downwards.
//! * `PULSE_LOG_NO_RATE_LIMIT`: If defined, do not rate limit the logging output. Rate limiting
//! skips certain log messages when their frequency is considered too high.
//!
//! # Usage
//!
//! Firstly, add a dependency on the crate in your program's `Cargo.toml` file. Secondly, import the
//! crate to the root of your program:
//!
//! ```rust,ignore
//! extern crate libpulse_binding as pulse;
//! ```
//!
//! See sub-modules for further information.
//!
//! [`::mainloop`]: mainloop/index.html
//! [`::error::Code`]: error/enum.Code.html
//! [`::context::Context::errno`]: context/struct.Context.html#method.errno
//! [`::error::strerror`]: error/fn.strerror.html
extern crate libc;
extern crate libpulse_sys as capi;