1#ifndef foopulseaudiohfoo
2#define foopulseaudiohfoo
3
4/***
5 This file is part of PulseAudio.
6
7 Copyright 2004-2006 Lennart Poettering
8 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
9
10 PulseAudio is free software; you can redistribute it and/or modify
11 it under the terms of the GNU Lesser General Public License as
12 published by the Free Software Foundation; either version 2.1 of the
13 License, or (at your option) any later version.
14
15 PulseAudio is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public
21 License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
22***/
23
24#include <pulse/direction.h>
25#include <pulse/mainloop-api.h>
26#include <pulse/sample.h>
27#include <pulse/format.h>
28#include <pulse/def.h>
29#include <pulse/context.h>
30#include <pulse/stream.h>
31#include <pulse/introspect.h>
32#include <pulse/subscribe.h>
33#include <pulse/scache.h>
34#include <pulse/version.h>
35#include <pulse/error.h>
36#include <pulse/operation.h>
37#include <pulse/channelmap.h>
38#include <pulse/volume.h>
39#include <pulse/xmalloc.h>
40#include <pulse/utf8.h>
41#include <pulse/thread-mainloop.h>
42#include <pulse/mainloop.h>
43#include <pulse/mainloop-signal.h>
44#include <pulse/util.h>
45#include <pulse/timeval.h>
46#include <pulse/proplist.h>
47#include <pulse/rtclock.h>
48
49/** \file
50 * Include all libpulse header files at once. The following files are
51 * included: \ref direction.h, \ref mainloop-api.h, \ref sample.h, \ref def.h,
52 * \ref context.h, \ref stream.h, \ref introspect.h, \ref subscribe.h, \ref
53 * scache.h, \ref version.h, \ref error.h, \ref channelmap.h, \ref
54 * operation.h,\ref volume.h, \ref xmalloc.h, \ref utf8.h, \ref
55 * thread-mainloop.h, \ref mainloop.h, \ref util.h, \ref proplist.h,
56 * \ref timeval.h, \ref rtclock.h and \ref mainloop-signal.h at
57 * once */
58
59/** \mainpage
60 *
61 * \section intro_sec Introduction
62 *
63 * This document describes the client API for the PulseAudio sound
64 * server. The API comes in two flavours to accommodate different styles
65 * of applications and different needs in complexity:
66 *
67 * \li The complete but somewhat complicated to use asynchronous API
68 * \li The simplified, easy to use, but limited synchronous API
69 *
70 * All strings in PulseAudio are in the UTF-8 encoding, regardless of current
71 * locale. Some functions will filter invalid sequences from the string, some
72 * will simply fail. To ensure reliable behaviour, make sure everything you
73 * pass to the API is already in UTF-8.
74
75 * \section simple_sec Simple API
76 *
77 * Use this if you develop your program in synchronous style and just
78 * need a way to play or record data on the sound server. See
79 * \subpage simple for more details.
80 *
81 * \section async_sec Asynchronous API
82 *
83 * Use this if you develop your programs in asynchronous, event loop
84 * based style or if you want to use the advanced features of the
85 * PulseAudio API. A guide can be found in \subpage async.
86 *
87 * By using the built-in threaded main loop, it is possible to achieve a
88 * pseudo-synchronous API, which can be useful in synchronous applications
89 * where the simple API is insufficient. See the \ref async page for
90 * details.
91 *
92 * \section thread_sec Threads
93 *
94 * The PulseAudio client libraries are not designed to be directly
95 * thread-safe. They are however designed to be reentrant and
96 * threads-aware.
97 *
98 * To use the libraries in a threaded environment, you must assure that
99 * all objects are only used in one thread at a time. Normally, this means
100 * that all objects belonging to a single context must be accessed from the
101 * same thread.
102 *
103 * The included main loop implementation is also not thread safe. Take care
104 * to make sure event objects are not manipulated when any other code is
105 * using the main loop.
106 *
107 * \section error_sec Error Handling
108 *
109 * Every function should explicitly document how errors are reported to
110 * the caller. Unfortunately, currently a lot of that documentation is
111 * missing. Here is an overview of the general conventions used.
112 *
113 * The PulseAudio API indicates error conditions by returning a negative
114 * integer value or a NULL pointer. On success, zero or a positive integer
115 * value or a valid pointer is returned.
116 *
117 * Functions of the \ref simple generally return -1 or NULL on failure and
118 * can optionally store an error code (see ::pa_error_code) using a pointer
119 * argument.
120 *
121 * Functions of the \ref async return an negative error code or NULL on
122 * failure (see ::pa_error_code). In the later case, pa_context_errno()
123 * can be used to obtain the error code of the last failed operation.
124 *
125 * An error code can be turned into a human readable message using
126 * pa_strerror().
127 *
128 * \section logging_sec Logging
129 *
130 * You can configure different logging parameters for the PulseAudio client
131 * libraries. The following environment variables are recognized:
132 *
133 * - `PULSE_LOG`: Maximum log level required. Bigger values result in a
134 * more verbose logging output. The following values are recognized:
135 * + `0`: Error messages
136 * + `1`: Warning messages
137 * + `2`: Notice messages
138 * + `3`: Info messages
139 * + `4`: Debug messages
140 * - `PULSE_LOG_SYSLOG`: If defined, force all client libraries to log
141 * their output using the syslog(3) mechanism. Default behavior is to
142 * log all output to stderr.
143 * - `PULSE_LOG_JOURNAL`: If defined, force all client libraries to log
144 * their output using the systemd journal. If both `PULSE_LOG_JOURNAL`
145 * and `PULSE_LOG_SYSLOG` are defined, logging to the systemd journal
146 * takes a higher precedence. Each message originating library file name
147 * and function are included by default through the journal fields
148 * `CODE_FILE`, `CODE_FUNC`, and `CODE_LINE`. Any backtrace attached to
149 * the logging message is sent through the PulseAudio-specific journal
150 * field `PULSE_BACKTRACE`. This environment variable has no effect if
151 * PulseAudio was compiled without systemd journal support.
152 * - `PULSE_LOG_COLORS`: If defined, enables colored logging output.
153 * - `PULSE_LOG_TIME`: If defined, include timestamps with each message.
154 * - `PULSE_LOG_FILE`: If defined, include each message originating file
155 * name.
156 * - `PULSE_LOG_META`: If defined, include each message originating file
157 * name and path relative to the PulseAudio source tree root.
158 * - `PULSE_LOG_LEVEL`: If defined, include a log level prefix with each
159 * message. Respectively, the prefixes "E", "W", "N", "I", "D" stands
160 * for Error, Warning, Notice, Info, and Debugging.
161 * - `PULSE_LOG_BACKTRACE`: Number of functions to display in the backtrace.
162 * If this variable is not defined, or has a value of zero, no backtrace
163 * is shown.
164 * - `PULSE_LOG_BACKTRACE_SKIP`: Number of backtrace levels to skip, from
165 * the function printing the log message downwards.
166 * - `PULSE_LOG_NO_RATE_LIMIT`: If defined, do not rate limit the logging
167 * output. Rate limiting skips certain log messages when their frequency
168 * is considered too high.
169 *
170 * \section pkgconfig pkg-config
171 *
172 * The PulseAudio libraries provide pkg-config snippets for the different
173 * modules:
174 *
175 * \li libpulse - The asynchronous API and the internal main loop implementation.
176 * \li libpulse-mainloop-glib - GLIB 2.x main loop bindings.
177 * \li libpulse-simple - The simple PulseAudio API.
178 */
179
180#endif
181