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.1 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, see <http://www.gnu.org/licenses/>.
22***/
23
24#include <pulse/sample.h>
25#include <pulse/def.h>
26#include <pulse/mainloop-api.h>
27#include <pulse/cdecl.h>
28#include <pulse/operation.h>
29#include <pulse/proplist.h>
30#include <pulse/version.h>
31
32/** \page async Asynchronous API
33 *
34 * \section overv_sec Overview
35 *
36 * The asynchronous API is the native interface to the PulseAudio library.
37 * It allows full access to all available functionality. This however means that
38 * it is rather complex and can take some time to fully master.
39 *
40 * \section mainloop_sec Main Loop Abstraction
41 *
42 * The API is based around an asynchronous event loop, or main loop,
43 * abstraction. This abstraction contains three basic elements:
44 *
45 * \li Deferred events - Events that will trigger as soon as possible. Note
46 * that some implementations may block all other events
47 * when a deferred event is active.
48 * \li I/O events - Events that trigger on file descriptor activities.
49 * \li Times events - Events that trigger after a fixed amount of time.
50 *
51 * The abstraction is represented as a number of function pointers in the
52 * pa_mainloop_api structure.
53 *
54 * To actually be able to use these functions, an implementation needs to
55 * be coupled to the abstraction. There are three of these shipped with
56 * PulseAudio, but any other can be used with a minimal amount of work,
57 * provided it supports the three basic events listed above.
58 *
59 * The implementations shipped with PulseAudio are:
60 *
61 * \li \subpage mainloop - A minimal but fast implementation based on poll().
62 * \li \subpage threaded_mainloop - A special version of the previous
63 * implementation where all of PulseAudio's
64 * internal handling runs in a separate
65 * thread.
66 * \li \subpage glib-mainloop - A wrapper around GLib's main loop.
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 object's 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 asynchronous communication with a
145 * server. A pa_context object wraps a connection to a PulseAudio
146 * server using its native protocol.
147 *
148 * See also \subpage async
149 */
150
151PA_C_DECL_BEGIN
152
153/** An opaque connection context to a daemon */
154typedef struct pa_context pa_context;
155
156/** Generic notification callback prototype */
157typedef void (*pa_context_notify_cb_t)(pa_context *c, void *userdata);
158
159/** A generic callback for operation completion */
160typedef void (*pa_context_success_cb_t) (pa_context *c, int success, void *userdata);
161
162/** A callback for asynchronous meta/policy event messages. The set
163 * of defined events can be extended at any time. Also, server modules
164 * may introduce additional message types so make sure that your
165 * callback function ignores messages it doesn't know. \since
166 * 0.9.15 */
167typedef void (*pa_context_event_cb_t)(pa_context *c, const char *name, pa_proplist *p, void *userdata);
168
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.*/
172pa_context *pa_context_new(pa_mainloop_api *mainloop, const char *name);
173
174/** Instantiate a new connection context with an abstract mainloop API
175 * and an application name, and specify the initial client property
176 * list. \since 0.9.11 */
177pa_context *pa_context_new_with_proplist(pa_mainloop_api *mainloop, const char *name, pa_proplist *proplist);
178
179/** Decrease the reference counter of the context by one */
180void pa_context_unref(pa_context *c);
181
182/** Increase the reference counter of the context by one */
183pa_context* pa_context_ref(pa_context *c);
184
185/** Set a callback function that is called whenever the context status changes */
186void pa_context_set_state_callback(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
187
188/** Set a callback function that is called whenever a meta/policy
189 * control event is received. \since 0.9.15 */
190void pa_context_set_event_callback(pa_context *p, pa_context_event_cb_t cb, void *userdata);
191
192/** Return the error number of the last failed operation */
193int pa_context_errno(pa_context *c);
194
195/** Return non-zero if some data is pending to be written to the connection */
196int pa_context_is_pending(pa_context *c);
197
198/** Return the current context status */
199pa_context_state_t pa_context_get_state(pa_context *c);
200
201/** Connect the context to the specified server. If server is NULL,
202connect to the default server. This routine may but will not always
203return synchronously on error. Use pa_context_set_state_callback() to
204be notified when the connection is established. If flags doesn't have
205PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or
206accessible a new daemon is spawned. If api is non-NULL, the functions
207specified in the structure are used when forking a new child
208process. */
209int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api);
210
211/** Terminate the context connection immediately */
212void pa_context_disconnect(pa_context *c);
213
214/** Drain the context. If there is nothing to drain, the function returns NULL */
215pa_operation* pa_context_drain(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
216
217/** Tell the daemon to exit. The returned operation is unlikely to
218 * complete successfully, since the daemon probably died before
219 * returning a success notification */
220pa_operation* pa_context_exit_daemon(pa_context *c, pa_context_success_cb_t cb, void *userdata);
221
222/** Set the name of the default sink. */
223pa_operation* pa_context_set_default_sink(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
224
225/** Set the name of the default source. */
226pa_operation* pa_context_set_default_source(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
227
228/** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. */
229int pa_context_is_local(pa_context *c);
230
231/** Set a different application name for context on the server. */
232pa_operation* pa_context_set_name(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
233
234/** Return the server name this context is connected to. */
235const char* pa_context_get_server(pa_context *c);
236
237/** Return the protocol version of the library. */
238uint32_t pa_context_get_protocol_version(pa_context *c);
239
240/** Return the protocol version of the connected server. */
241uint32_t pa_context_get_server_protocol_version(pa_context *c);
242
243/** Update the property list of the client, adding new entries. Please
244 * note that it is highly recommended to set as much properties
245 * initially via pa_context_new_with_proplist() as possible instead a
246 * posteriori with this function, since that information may then be
247 * used to route streams of the client to the right device. \since 0.9.11 */
248pa_operation *pa_context_proplist_update(pa_context *c, pa_update_mode_t mode, pa_proplist *p, pa_context_success_cb_t cb, void *userdata);
249
250/** Update the property list of the client, remove entries. \since 0.9.11 */
251pa_operation *pa_context_proplist_remove(pa_context *c, const char *const keys[], pa_context_success_cb_t cb, void *userdata);
252
253/** Return the client index this context is
254 * identified in the server with. This is useful for usage with the
255 * introspection functions, such as pa_context_get_client_info(). \since 0.9.11 */
256uint32_t pa_context_get_index(pa_context *s);
257
258/** Create a new timer event source for the specified time (wrapper
259 * for mainloop->time_new). \since 0.9.16 */
260pa_time_event* pa_context_rttime_new(pa_context *c, pa_usec_t usec, pa_time_event_cb_t cb, void *userdata);
261
262/** Restart a running or expired timer event source (wrapper for
263 * mainloop->time_restart). \since 0.9.16 */
264void pa_context_rttime_restart(pa_context *c, pa_time_event *e, pa_usec_t usec);
265
266/** Return the optimal block size for passing around audio buffers. It
267 * is recommended to allocate buffers of the size returned here when
268 * writing audio data to playback streams, if the latency constraints
269 * permit this. It is not recommended writing larger blocks than this
270 * because usually they will then be split up internally into chunks
271 * of this size. It is not recommended writing smaller blocks than
272 * this (unless required due to latency demands) because this
273 * increases CPU usage. If ss is NULL you will be returned the
274 * byte-exact tile size. If you pass a valid ss, then the tile size
275 * will be rounded down to multiple of the frame size. This is
276 * supposed to be used in a construct such as
277 * pa_context_get_tile_size(pa_stream_get_context(s),
278 * pa_stream_get_sample_spec(ss)); \since 0.9.20 */
279size_t pa_context_get_tile_size(pa_context *c, const pa_sample_spec *ss);
280
281/** Load the authentication cookie from a file. This function is primarily
282 * meant for PulseAudio's own tunnel modules, which need to load the cookie
283 * from a custom location. Applications don't usually need to care about the
284 * cookie at all, but if it happens that you know what the authentication
285 * cookie is and your application needs to load it from a non-standard
286 * location, feel free to use this function. \since 5.0 */
287int pa_context_load_cookie_from_file(pa_context *c, const char *cookie_file_path);
288
289PA_C_DECL_END
290
291#endif
292