code.delx.au - pulseaudio/blob - src/pulse/pulseaudio.h

   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, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include <pulse/direction.h>
  27 #include <pulse/mainloop-api.h>
  28 #include <pulse/sample.h>
  29 #include <pulse/format.h>
  30 #include <pulse/def.h>
  31 #include <pulse/context.h>
  32 #include <pulse/stream.h>
  33 #include <pulse/introspect.h>
  34 #include <pulse/subscribe.h>
  35 #include <pulse/scache.h>
  36 #include <pulse/version.h>
  37 #include <pulse/error.h>
  38 #include <pulse/operation.h>
  39 #include <pulse/channelmap.h>
  40 #include <pulse/volume.h>
  41 #include <pulse/xmalloc.h>
  42 #include <pulse/utf8.h>
  43 #include <pulse/thread-mainloop.h>
  44 #include <pulse/mainloop.h>
  45 #include <pulse/mainloop-signal.h>
  46 #include <pulse/util.h>
  47 #include <pulse/timeval.h>
  48 #include <pulse/proplist.h>
  49 #include <pulse/rtclock.h>
  50
  51 /** \file
  52  * Include all libpulse header files at once. The following files are
  53  * included: \ref direction.h, \ref mainloop-api.h, \ref sample.h, \ref def.h,
  54  * \ref context.h, \ref stream.h, \ref introspect.h, \ref subscribe.h, \ref
  55  * scache.h, \ref version.h, \ref error.h, \ref channelmap.h, \ref
  56  * operation.h,\ref volume.h, \ref xmalloc.h, \ref utf8.h, \ref
  57  * thread-mainloop.h, \ref mainloop.h, \ref util.h, \ref proplist.h,
  58  * \ref timeval.h, \ref rtclock.h and \ref mainloop-signal.h at
  59  * once */
  60
  61 /** \mainpage
  62  *
  63  * \section intro_sec Introduction
  64  *
  65  * This document describes the client API for the PulseAudio sound
  66  * server. The API comes in two flavours to accommodate different styles
  67  * of applications and different needs in complexity:
  68  *
  69  * \li The complete but somewhat complicated to use asynchronous API
  70  * \li The simplified, easy to use, but limited synchronous API
  71  *
  72  * All strings in PulseAudio are in the UTF-8 encoding, regardless of current
  73  * locale. Some functions will filter invalid sequences from the string, some
  74  * will simply fail. To ensure reliable behaviour, make sure everything you
  75  * pass to the API is already in UTF-8.
  76
  77  * \section simple_sec Simple API
  78  *
  79  * Use this if you develop your program in synchronous style and just
  80  * need a way to play or record data on the sound server. See
  81  * \subpage simple for more details.
  82  *
  83  * \section async_sec Asynchronous API
  84  *
  85  * Use this if you develop your programs in asynchronous, event loop
  86  * based style or if you want to use the advanced features of the
  87  * PulseAudio API. A guide can be found in \subpage async.
  88  *
  89  * By using the built-in threaded main loop, it is possible to achieve a
  90  * pseudo-synchronous API, which can be useful in synchronous applications
  91  * where the simple API is insufficient. See the \ref async page for
  92  * details.
  93  *
  94  * \section thread_sec Threads
  95  *
  96  * The PulseAudio client libraries are not designed to be directly
  97  * thread-safe. They are however designed to be reentrant and
  98  * threads-aware.
  99  *
 100  * To use the libraries in a threaded environment, you must assure that
 101  * all objects are only used in one thread at a time. Normally, this means
 102  * that all objects belonging to a single context must be accessed from the
 103  * same thread.
 104  *
 105  * The included main loop implementation is also not thread safe. Take care
 106  * to make sure event objects are not manipulated when any other code is
 107  * using the main loop.
 108  *
 109  * \section error_sec Error Handling
 110  *
 111  * Every function should explicitly document how errors are reported to
 112  * the caller. Unfortunately, currently a lot of that documentation is
 113  * missing. Here is an overview of the general conventions used.
 114  *
 115  * The PulseAudio API indicates error conditions by returning a negative
 116  * integer value or a NULL pointer. On success, zero or a positive integer
 117  * value or a valid pointer is returned.
 118  *
 119  * Functions of the \ref simple generally return -1 or NULL on failure and
 120  * can optionally store an error code (see ::pa_error_code) using a pointer
 121  * argument.
 122  *
 123  * Functions of the \ref async return an negative error code or NULL on
 124  * failure (see ::pa_error_code). In the later case, pa_context_errno()
 125  * can be used to obtain the error code of the last failed operation.
 126  *
 127  * An error code can be turned into a human readable message using
 128  * pa_strerror().
 129  *
 130  * \section pkgconfig pkg-config
 131  *
 132  * The PulseAudio libraries provide pkg-config snippets for the different
 133  * modules:
 134  *
 135  * \li libpulse - The asynchronous API and the internal main loop implementation.
 136  * \li libpulse-mainloop-glib - GLIB 2.x main loop bindings.
 137  * \li libpulse-simple - The simple PulseAudio API.
 138  */
 139
 140 #endif