7 This file is part of polypaudio.
9 polypaudio 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.
14 polypaudio 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.
19 You should have received a copy of the GNU Lesser General Public License
20 along with polypaudio; if not, write to the Free Software
21 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
25 #include <polyp/sample.h>
26 #include <polyp/def.h>
27 #include <polyp/mainloop-api.h>
28 #include <polyp/cdecl.h>
29 #include <polyp/operation.h>
31 /** \page async Asynchronous API
33 * \section overv_sec Overview
35 * The asynchronous API is the native interface to the polypaudio 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.
39 * \section mainloop_sec Main loop abstraction
41 * The API is based around an asynchronous event loop, or main loop,
42 * abstraction. This abstraction contains three basic elements:
44 * \li Deferred events - Events that trigger each iteration of the main loop.
45 * \li I/O events - Events that trigger on file descriptor activities.
46 * \li Times events - Events that trigger after a fixed ammount of time.
48 * The abstraction is represented as a number of function pointers in the
49 * pa_mainloop_api structure.
51 * To actually be able to use these functions, an implementation needs to
52 * be coupled to the abstraction. There are two of these shipped with
53 * polypaudio, but any other can be used with a minimal ammount of work,
54 * provided it supports the three basic events listed above.
56 * The implementations shipped with polypaudio are:
58 * \li \subpage mainloop - A minimal but fast implementation based on poll().
59 * \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
60 * for both GLIB 1.2 and GLIB 2.x.
62 * UNIX signals may be hooked to a main loop using the functions from
63 * \ref mainloop-signal.h. These rely only on the main loop abstraction
64 * and can therefore be used with any of the implementations.
66 * \section refcnt_sec Reference counting
68 * Almost all objects in polypaudio are reference counted. What that means
69 * is that you rarely malloc() or free() any objects. Instead you increase
70 * and decrease their reference counts. Whenever an object's reference
71 * count reaches zero, that object gets destroy and any resources it uses
74 * The benefit of this design is that an application need not worry about
75 * whether or not it needs to keep an object around in case the library is
76 * using it internally. If it is, then it has made sure it has its own
79 * Whenever the library creates an object, it will have an initial
80 * reference count of one. Most of the time, this single reference will be
81 * sufficient for the application, so all required reference count
82 * interaction will be a single call to the objects unref function.
84 * \section context_sec Context
86 * A context is the basic object for a connection to a polypaudio server.
87 * It multiplexes commands, data streams and events through a single
90 * There is no need for more than one context per application, unless
91 * connections to multiple servers are needed.
93 * \subsection ops_subsec Operations
95 * All operations on the context are performed asynchronously. I.e. the
96 * client will not wait for the server to complete the request. To keep
97 * track of all these in-flight operations, the application is given a
98 * pa_operation object for each asynchronous operation.
100 * There are only two actions (besides reference counting) that can be
101 * performed on a pa_operation: querying its state with
102 * pa_operation_get_state() and aborting it with pa_operation_cancel().
104 * A pa_operation object is reference counted, so an application must
105 * make sure to unreference it, even if it has no intention of using it.
107 * \subsection conn_subsec Connecting
109 * A context must be connected to a server before any operation can be
110 * issued. Calling pa_context_connect() will initiate the connection
111 * procedure. Unlike most asynchronous operations, connecting does not
112 * result in a pa_operation object. Instead, the application should
113 * register a callback using pa_context_set_state_callback().
115 * \subsection disc_subsec Disconnecting
117 * When the sound support is no longer needed, the connection needs to be
118 * closed using pa_context_disconnect(). This is an immediate function that
119 * works synchronously.
121 * Since the context object has references to other objects it must be
122 * disconnected after use or there is a high risk of memory leaks. If the
123 * connection has terminated by itself, then there is no need to explicitly
124 * disconnect the context using pa_context_disconnect().
128 * The sound server's functionality can be divided into a number of
131 * \li \subpage streams
132 * \li \subpage scache
133 * \li \subpage introspect
134 * \li \subpage subscribe
138 * Connection contexts for asynchrononous communication with a
139 * server. A pa_context object wraps a connection to a polypaudio
140 * server using its native protocol. */
143 * A playback and recording tool using the asynchronous API */
145 /** \example paplay.c
146 * A sound file playback tool using the asynchronous API, based on libsndfile */
150 /** An opaque connection context to a daemon */
151 typedef struct pa_context pa_context
;
153 /** Generic notification callback prototype */
154 typedef void (*pa_context_notify_cb_t
)(pa_context
*c
, void *userdata
);
156 /** A generic callback for operation completion */
157 typedef void (*pa_context_success_cb_t
) (pa_context
*c
, int success
, void *userdata
);
159 /** Instantiate a new connection context with an abstract mainloop API
160 * and an application name */
161 pa_context
*pa_context_new(pa_mainloop_api
*mainloop
, const char *name
);
163 /** Decrease the reference counter of the context by one */
164 void pa_context_unref(pa_context
*c
);
166 /** Increase the reference counter of the context by one */
167 pa_context
* pa_context_ref(pa_context
*c
);
169 /** Set a callback function that is called whenever the context status changes */
170 void pa_context_set_state_callback(pa_context
*c
, pa_context_notify_cb_t cb
, void *userdata
);
172 /** Return the error number of the last failed operation */
173 int pa_context_errno(pa_context
*c
);
175 /** Return non-zero if some data is pending to be written to the connection */
176 int pa_context_is_pending(pa_context
*c
);
178 /** Return the current context status */
179 pa_context_state_t
pa_context_get_state(pa_context
*c
);
181 /** Connect the context to the specified server. If server is NULL,
182 connect to the default server. This routine may but will not always
183 return synchronously on error. Use pa_context_set_state_callback() to
184 be notified when the connection is established. If flags doesn't have
185 PA_NOAUTOSPAWN set and no specific server is specified or accessible a
186 new daemon is spawned. If api is non-NULL, the functions specified in
187 the structure are used when forking a new child process. */
188 int pa_context_connect(pa_context
*c
, const char *server
, pa_context_flags_t flags
, const pa_spawn_api
*api
);
190 /** Terminate the context connection immediately */
191 void pa_context_disconnect(pa_context
*c
);
193 /** Drain the context. If there is nothing to drain, the function returns NULL */
194 pa_operation
* pa_context_drain(pa_context
*c
, pa_context_notify_cb_t cb
, void *userdata
);
196 /** Tell the daemon to exit. The returned operation is unlikely to
197 * complete succesfully, since the daemon probably died before
198 * returning a success notification */
199 pa_operation
* pa_context_exit_daemon(pa_context
*c
, pa_context_success_cb_t cb
, void *userdata
);
201 /** Set the name of the default sink. \since 0.4 */
202 pa_operation
* pa_context_set_default_sink(pa_context
*c
, const char *name
, pa_context_success_cb_t cb
, void *userdata
);
204 /** Set the name of the default source. \since 0.4 */
205 pa_operation
* pa_context_set_default_source(pa_context
*c
, const char *name
, pa_context_success_cb_t cb
, void *userdata
);
207 /** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. \since 0.5 */
208 int pa_context_is_local(pa_context
*c
);
210 /** Set a different application name for context on the server. \since 0.5 */
211 pa_operation
* pa_context_set_name(pa_context
*c
, const char *name
, pa_context_success_cb_t cb
, void *userdata
);
213 /** Return the server name this context is connected to. \since 0.7 */
214 const char* pa_context_get_server(pa_context
*c
);
216 /** Return the protocol version of the library. \since 0.8 */
217 uint32_t pa_context_get_protocol_version(pa_context
*c
);
219 /** Return the protocol version of the connected server. \since 0.8 */
220 uint32_t pa_context_get_server_protocol_version(pa_context
*c
);