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

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