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 Timer 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 151 PA_C_DECL_BEGIN 152 153 /** An opaque connection context to a daemon */ 154 typedef struct pa_context pa_context; 155 156 /** Generic notification callback prototype */ 157 typedef void (*pa_context_notify_cb_t)(pa_context *c, void *userdata); 158 159 /** A generic callback for operation completion */ 160 typedef 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 */ 167 typedef 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.*/ 172 pa_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 */ 177 pa_context *pa_context_new_with_proplist(pa_mainloop_api *mainloop, const char *name, const pa_proplist *proplist); 178 179 /** Decrease the reference counter of the context by one */ 180 void pa_context_unref(pa_context *c); 181 182 /** Increase the reference counter of the context by one */ 183 pa_context* pa_context_ref(pa_context *c); 184 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); 187 188 /** Set a callback function that is called whenever a meta/policy 189 * control event is received. \since 0.9.15 */ 190 void 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 */ 193 int pa_context_errno(const pa_context *c); 194 195 /** Return non-zero if some data is pending to be written to the connection */ 196 int pa_context_is_pending(const pa_context *c); 197 198 /** Return the current context status */ 199 pa_context_state_t pa_context_get_state(const pa_context *c); 200 201 /** Connect the context to the specified server. If server is NULL, 202 * connect to the default server. This routine may but will not always 203 * return synchronously on error. Use pa_context_set_state_callback() to 204 * be notified when the connection is established. If flags doesn't have 205 * PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or 206 * accessible a new daemon is spawned. If api is non-NULL, the functions 207 * specified in the structure are used when forking a new child 208 * process. Returns negative on certain errors such as invalid state 209 * or parameters. */ 210 int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api); 211 212 /** Terminate the context connection immediately */ 213 void pa_context_disconnect(pa_context *c); 214 215 /** Drain the context. If there is nothing to drain, the function returns NULL */ 216 pa_operation* pa_context_drain(pa_context *c, pa_context_notify_cb_t cb, void *userdata); 217 218 /** Tell the daemon to exit. The returned operation is unlikely to 219 * complete successfully, since the daemon probably died before 220 * returning a success notification */ 221 pa_operation* pa_context_exit_daemon(pa_context *c, pa_context_success_cb_t cb, void *userdata); 222 223 /** Set the name of the default sink. */ 224 pa_operation* pa_context_set_default_sink(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata); 225 226 /** Set the name of the default source. */ 227 pa_operation* pa_context_set_default_source(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata); 228 229 /** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. */ 230 int pa_context_is_local(const pa_context *c); 231 232 /** Set a different application name for context on the server. */ 233 pa_operation* pa_context_set_name(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata); 234 235 /** Return the server name this context is connected to. */ 236 const char* pa_context_get_server(const pa_context *c); 237 238 /** Return the protocol version of the library. */ 239 uint32_t pa_context_get_protocol_version(const pa_context *c); 240 241 /** Return the protocol version of the connected server. 242 * Returns PA_INVALID_INDEX on error. */ 243 uint32_t pa_context_get_server_protocol_version(const pa_context *c); 244 245 /** Update the property list of the client, adding new entries. Please 246 * note that it is highly recommended to set as many properties 247 * initially via pa_context_new_with_proplist() as possible instead a 248 * posteriori with this function, since that information may then be 249 * used to route streams of the client to the right device. \since 0.9.11 */ 250 pa_operation *pa_context_proplist_update(pa_context *c, pa_update_mode_t mode, const pa_proplist *p, pa_context_success_cb_t cb, void *userdata); 251 252 /** Update the property list of the client, remove entries. \since 0.9.11 */ 253 pa_operation *pa_context_proplist_remove(pa_context *c, const char *const keys[], pa_context_success_cb_t cb, void *userdata); 254 255 /** Return the client index this context is 256 * identified in the server with. This is useful for usage with the 257 * introspection functions, such as pa_context_get_client_info(). 258 * Returns PA_INVALID_INDEX on error. \since 0.9.11 */ 259 uint32_t pa_context_get_index(const pa_context *s); 260 261 /** Create a new timer event source for the specified time (wrapper 262 * for mainloop->time_new). \since 0.9.16 */ 263 pa_time_event* pa_context_rttime_new(const pa_context *c, pa_usec_t usec, pa_time_event_cb_t cb, void *userdata); 264 265 /** Restart a running or expired timer event source (wrapper for 266 * mainloop->time_restart). \since 0.9.16 */ 267 void pa_context_rttime_restart(const pa_context *c, pa_time_event *e, pa_usec_t usec); 268 269 /** Return the optimal block size for passing around audio buffers. It 270 * is recommended to allocate buffers of the size returned here when 271 * writing audio data to playback streams, if the latency constraints 272 * permit this. It is not recommended writing larger blocks than this 273 * because usually they will then be split up internally into chunks 274 * of this size. It is not recommended writing smaller blocks than 275 * this (unless required due to latency demands) because this 276 * increases CPU usage. If ss is NULL you will be returned the 277 * byte-exact tile size. if ss is invalid, (size_t) -1 will be 278 * returned. If you pass a valid ss, then the tile size 279 * will be rounded down to multiple of the frame size. This is 280 * supposed to be used in a construct such as 281 * pa_context_get_tile_size(pa_stream_get_context(s), 282 * pa_stream_get_sample_spec(ss)); \since 0.9.20 */ 283 size_t pa_context_get_tile_size(const pa_context *c, const pa_sample_spec *ss); 284 285 /** Load the authentication cookie from a file. This function is primarily 286 * meant for PulseAudio's own tunnel modules, which need to load the cookie 287 * from a custom location. Applications don't usually need to care about the 288 * cookie at all, but if it happens that you know what the authentication 289 * cookie is and your application needs to load it from a non-standard 290 * location, feel free to use this function. \since 5.0 */ 291 int pa_context_load_cookie_from_file(pa_context *c, const char *cookie_file_path); 292 293 PA_C_DECL_END 294 295 #endif 296