#ifndef foopulseaudiohfoo
#define foopulseaudiohfoo
-/* $Id$ */
-
/***
This file is part of PulseAudio.
USA.
***/
+#include <pulse/direction.h>
#include <pulse/mainloop-api.h>
#include <pulse/sample.h>
+#include <pulse/format.h>
#include <pulse/def.h>
#include <pulse/context.h>
#include <pulse/stream.h>
#include <pulse/mainloop-signal.h>
#include <pulse/util.h>
#include <pulse/timeval.h>
+#include <pulse/proplist.h>
+#include <pulse/rtclock.h>
/** \file
- * Include all libpulse header files at once. The following
- * files are included: \ref mainloop-api.h, \ref sample.h, \ref def.h,
- * \ref context.h, \ref stream.h, \ref introspect.h, \ref subscribe.h,
- * \ref scache.h, \ref version.h, \ref error.h, \ref channelmap.h,
- * \ref operation.h,\ref volume.h, \ref xmalloc.h, \ref utf8.h, \ref
- * thread-mainloop.h, \ref mainloop.h, \ref util.h, \ref timeval.h and
- * \ref mainloop-signal.h at once */
+ * Include all libpulse header files at once. The following files are
+ * included: \ref direction.h, \ref mainloop-api.h, \ref sample.h, \ref def.h,
+ * \ref context.h, \ref stream.h, \ref introspect.h, \ref subscribe.h, \ref
+ * scache.h, \ref version.h, \ref error.h, \ref channelmap.h, \ref
+ * operation.h,\ref volume.h, \ref xmalloc.h, \ref utf8.h, \ref
+ * thread-mainloop.h, \ref mainloop.h, \ref util.h, \ref proplist.h,
+ * \ref timeval.h, \ref rtclock.h and \ref mainloop-signal.h at
+ * once */
/** \mainpage
*
* \section intro_sec Introduction
*
* This document describes the client API for the PulseAudio sound
- * server. The API comes in two flavours to accomodate different styles
+ * server. The API comes in two flavours to accommodate different styles
* of applications and different needs in complexity:
*
* \li The complete but somewhat complicated to use asynchronous API
* based style or if you want to use the advanced features of the
* PulseAudio API. A guide can be found in \subpage async.
*
- * By using the built-in threaded main loop, it is possible to acheive a
+ * 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. See the \ref async page for
* details.
*
* \section thread_sec Threads
*
- * The PulseAudio client libraries are not designed to be used in a
- * heavily threaded environment. They are however designed to be reentrant
- * safe.
+ * The PulseAudio client libraries are not designed to be directly
+ * thread-safe. They are however designed to be reentrant and
+ * threads-aware.
*
- * To use a the libraries in a threaded environment, you must assure that
+ * 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 lists are not manipulated when any other code is
+ * to make sure event objects are not manipulated when any other code is
* using the main loop.
*
+ * \section error_sec Error Handling
+ *
+ * Every function should explicitly document how errors are reported to
+ * the caller. Unfortunately, currently a lot of that documentation is
+ * missing. Here is an overview of the general conventions used.
+ *
+ * The PulseAudio API indicates error conditions by returning a negative
+ * integer value or a NULL pointer. On success, zero or a positive integer
+ * value or a valid pointer is returned.
+ *
+ * Functions of the \ref simple generally return -1 or NULL on failure and
+ * can optionally store an error code (see ::pa_error_code) using a pointer
+ * argument.
+ *
+ * Functions of the \ref async return an negative error code or NULL on
+ * failure (see ::pa_error_code). In the later case, pa_context_errno()
+ * can be used to obtain the error code of the last failed operation.
+ *
+ * An error code can be turned into a human readable message using
+ * pa_strerror().
+ *
* \section pkgconfig pkg-config
*
* The PulseAudio libraries provide pkg-config snippets for the different
* modules:
*
* \li libpulse - The asynchronous API and the internal main loop implementation.
- * \li libpulse-mainloop-glib12 - GLIB 1.2 main loop bindings.
* \li libpulse-mainloop-glib - GLIB 2.x main loop bindings.
* \li libpulse-simple - The simple PulseAudio API.
*/