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

   1 #ifndef foocontexthfoo
   2 #define foocontexthfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of PulseAudio.
   8
   9   PulseAudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as published
  11   by the Free Software Foundation; either version 2 of the License,
  12   or (at your option) any later version.
  13
  14   PulseAudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public License
  20   along with PulseAudio; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 #include <pulse/sample.h>
  26 #include <pulse/def.h>
  27 #include <pulse/mainloop-api.h>
  28 #include <pulse/cdecl.h>
  29 #include <pulse/operation.h>
  30
  31 /** \page async Asynchronous API
  32  *
  33  * \section overv_sec Overview
  34  *
  35  * The asynchronous API is the native interface to the PulseAudio library.
  36  * It allows full access to all available functions. This also means that
  37  * it is rather complex and can take some time to fully master.
  38  *
  39  * \section mainloop_sec Main Loop Abstraction
  40  *
  41  * The API is based around an asynchronous event loop, or main loop,
  42  * abstraction. This abstraction contains three basic elements:
  43  *
  44  * \li Deferred events - Events that will trigger as soon as possible. Note
  45  *                       that some implementations may block all other events
  46  *                       when a deferred event is active.
  47  * \li I/O events - Events that trigger on file descriptor activities.
  48  * \li Times events - Events that trigger after a fixed ammount of time.
  49  *
  50  * The abstraction is represented as a number of function pointers in the
  51  * pa_mainloop_api structure.
  52  *
  53  * To actually be able to use these functions, an implementation needs to
  54  * be coupled to the abstraction. There are three of these shipped with
  55  * PulseAudio, but any other can be used with a minimal ammount of work,
  56  * provided it supports the three basic events listed above.
  57  *
  58  * The implementations shipped with PulseAudio are:
  59  *
  60  * \li \subpage mainloop - A minimal but fast implementation based on poll().
  61  * \li \subpage threaded_mainloop - A special version of the previous
  62  *                                  implementation where all of PulseAudio's
  63  *                                  internal handling runs in a separate
  64  *                                  thread.
  65  * \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
  66  *                              for both GLIB 1.2 and GLIB 2.x.
  67  *
  68  * UNIX signals may be hooked to a main loop using the functions from
  69  * \ref mainloop-signal.h. These rely only on the main loop abstraction
  70  * and can therefore be used with any of the implementations.
  71  *
  72  * \section refcnt_sec Reference Counting
  73  *
  74  * Almost all objects in PulseAudio are reference counted. What that means
  75  * is that you rarely malloc() or free() any objects. Instead you increase
  76  * and decrease their reference counts. Whenever an object's reference
  77  * count reaches zero, that object gets destroy and any resources it uses
  78  * get freed.
  79  *
  80  * The benefit of this design is that an application need not worry about
  81  * whether or not it needs to keep an object around in case the library is
  82  * using it internally. If it is, then it has made sure it has its own
  83  * reference to it.
  84  *
  85  * Whenever the library creates an object, it will have an initial
  86  * reference count of one. Most of the time, this single reference will be
  87  * sufficient for the application, so all required reference count
  88  * interaction will be a single call to the objects unref function.
  89  *
  90  * \section context_sec Context
  91  *
  92  * A context is the basic object for a connection to a PulseAudio server.
  93  * It multiplexes commands, data streams and events through a single
  94  * channel.
  95  *
  96  * There is no need for more than one context per application, unless
  97  * connections to multiple servers are needed.
  98  *
  99  * \subsection ops_subsec Operations
 100  *
 101  * All operations on the context are performed asynchronously. I.e. the
 102  * client will not wait for the server to complete the request. To keep
 103  * track of all these in-flight operations, the application is given a
 104  * pa_operation object for each asynchronous operation.
 105  *
 106  * There are only two actions (besides reference counting) that can be
 107  * performed on a pa_operation: querying its state with
 108  * pa_operation_get_state() and aborting it with pa_operation_cancel().
 109  *
 110  * A pa_operation object is reference counted, so an application must
 111  * make sure to unreference it, even if it has no intention of using it.
 112  *
 113  * \subsection conn_subsec Connecting
 114  *
 115  * A context must be connected to a server before any operation can be
 116  * issued. Calling pa_context_connect() will initiate the connection
 117  * procedure. Unlike most asynchronous operations, connecting does not
 118  * result in a pa_operation object. Instead, the application should
 119  * register a callback using pa_context_set_state_callback().
 120  *
 121  * \subsection disc_subsec Disconnecting
 122  *
 123  * When the sound support is no longer needed, the connection needs to be
 124  * closed using pa_context_disconnect(). This is an immediate function that
 125  * works synchronously.
 126  *
 127  * Since the context object has references to other objects it must be
 128  * disconnected after use or there is a high risk of memory leaks. If the
 129  * connection has terminated by itself, then there is no need to explicitly
 130  * disconnect the context using pa_context_disconnect().
 131  *
 132  * \section Functions
 133  *
 134  * The sound server's functionality can be divided into a number of
 135  * subsections:
 136  *
 137  * \li \subpage streams
 138  * \li \subpage scache
 139  * \li \subpage introspect
 140  * \li \subpage subscribe
 141  */
 142
 143 /** \file
 144  * Connection contexts for asynchrononous communication with a
 145  * server. A pa_context object wraps a connection to a PulseAudio
 146  * server using its native protocol. */
 147
 148 /** \example pacat.c
 149  * A playback and recording tool using the asynchronous API */
 150
 151 /** \example paplay.c
 152  * A sound file playback tool using the asynchronous API, based on libsndfile */
 153
 154 PA_C_DECL_BEGIN
 155
 156 /** An opaque connection context to a daemon */
 157 typedef struct pa_context pa_context;
 158
 159 /** Generic notification callback prototype */
 160 typedef void (*pa_context_notify_cb_t)(pa_context *c, void *userdata);
 161
 162 /** A generic callback for operation completion */
 163 typedef void (*pa_context_success_cb_t) (pa_context *c, int success, void *userdata);
 164
 165 /** Instantiate a new connection context with an abstract mainloop API
 166  * and an application name */
 167 pa_context *pa_context_new(pa_mainloop_api *mainloop, const char *name);
 168
 169 /** Decrease the reference counter of the context by one */
 170 void pa_context_unref(pa_context *c);
 171
 172 /** Increase the reference counter of the context by one */
 173 pa_context* pa_context_ref(pa_context *c);
 174
 175 /** Set a callback function that is called whenever the context status changes */
 176 void pa_context_set_state_callback(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
 177
 178 /** Return the error number of the last failed operation */
 179 int pa_context_errno(pa_context *c);
 180
 181 /** Return non-zero if some data is pending to be written to the connection */
 182 int pa_context_is_pending(pa_context *c);
 183
 184 /** Return the current context status */
 185 pa_context_state_t pa_context_get_state(pa_context *c);
 186
 187 /** Connect the context to the specified server. If server is NULL,
 188 connect to the default server. This routine may but will not always
 189 return synchronously on error. Use pa_context_set_state_callback() to
 190 be notified when the connection is established. If flags doesn't have
 191 PA_NOAUTOSPAWN set and no specific server is specified or accessible a
 192 new daemon is spawned. If api is non-NULL, the functions specified in
 193 the structure are used when forking a new child process. */
 194 int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api);
 195
 196 /** Terminate the context connection immediately */
 197 void pa_context_disconnect(pa_context *c);
 198
 199 /** Drain the context. If there is nothing to drain, the function returns NULL */
 200 pa_operation* pa_context_drain(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
 201
 202 /** Tell the daemon to exit. The returned operation is unlikely to
 203  * complete succesfully, since the daemon probably died before
 204  * returning a success notification */
 205 pa_operation* pa_context_exit_daemon(pa_context *c, pa_context_success_cb_t cb, void *userdata);
 206
 207 /** Set the name of the default sink. \since 0.4 */
 208 pa_operation* pa_context_set_default_sink(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
 209
 210 /** Set the name of the default source. \since 0.4 */
 211 pa_operation* pa_context_set_default_source(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
 212
 213 /** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. \since 0.5 */
 214 int pa_context_is_local(pa_context *c);
 215
 216 /** Set a different application name for context on the server. \since 0.5 */
 217 pa_operation* pa_context_set_name(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
 218
 219 /** Return the server name this context is connected to. \since 0.7 */
 220 const char* pa_context_get_server(pa_context *c);
 221
 222 /** Return the protocol version of the library. \since 0.8 */
 223 uint32_t pa_context_get_protocol_version(pa_context *c);
 224
 225 /** Return the protocol version of the connected server. \since 0.8 */
 226 uint32_t pa_context_get_server_protocol_version(pa_context *c);
 227
 228 PA_C_DECL_END
 229
 230 #endif