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