1 module pulse.context; 2 3 version(linux): 4 5 import pulse.proplist; 6 import pulse.mainloopapi; 7 import pulse.def; 8 import pulse.operation; 9 import pulse.sample; 10 11 extern (C): 12 13 /*** 14 This file is part of PulseAudio. 15 16 Copyright 2004-2006 Lennart Poettering 17 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB 18 19 PulseAudio is free software; you can redistribute it and/or modify 20 it under the terms of the GNU Lesser General Public License as published 21 by the Free Software Foundation; either version 2.1 of the License, 22 or (at your option) any later version. 23 24 PulseAudio is distributed in the hope that it will be useful, but 25 WITHOUT ANY WARRANTY; without even the implied warranty of 26 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 27 General Public License for more details. 28 29 You should have received a copy of the GNU Lesser General Public License 30 along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. 31 ***/ 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 Timer events - Events that trigger after a fixed amount 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 amount 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 object's 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 asynchronous communication with a 146 * server. A pa_context object wraps a connection to a PulseAudio 147 * server using its native protocol. 148 * 149 * See also \subpage async 150 */ 151 152 /** An opaque connection context to a daemon */ 153 struct pa_context; 154 155 /** Generic notification callback prototype */ 156 alias pa_context_notify_cb_t = void function (pa_context* c, void* userdata); 157 158 /** A generic callback for operation completion */ 159 alias pa_context_success_cb_t = void function (pa_context* c, int success, void* userdata); 160 161 /** A callback for asynchronous meta/policy event messages. The set 162 * of defined events can be extended at any time. Also, server modules 163 * may introduce additional message types so make sure that your 164 * callback function ignores messages it doesn't know. \since 165 * 0.9.15 */ 166 alias pa_context_event_cb_t = void function (pa_context* c, const(char)* name, pa_proplist* p, void* userdata); 167 168 /** Instantiate a new connection context with an abstract mainloop API 169 * and an application name. It is recommended to use pa_context_new_with_proplist() 170 * instead and specify some initial properties.*/ 171 pa_context* pa_context_new (pa_mainloop_api* mainloop, const(char)* name); 172 173 /** Instantiate a new connection context with an abstract mainloop API 174 * and an application name, and specify the initial client property 175 * list. \since 0.9.11 */ 176 pa_context* pa_context_new_with_proplist (pa_mainloop_api* mainloop, const(char)* name, const(pa_proplist)* proplist); 177 178 /** Decrease the reference counter of the context by one */ 179 void pa_context_unref (pa_context* c); 180 181 /** Increase the reference counter of the context by one */ 182 pa_context* pa_context_ref (pa_context* c); 183 184 /** Set a callback function that is called whenever the context status changes */ 185 void pa_context_set_state_callback (pa_context* c, pa_context_notify_cb_t cb, void* userdata); 186 187 /** Set a callback function that is called whenever a meta/policy 188 * control event is received. \since 0.9.15 */ 189 void pa_context_set_event_callback (pa_context* p, pa_context_event_cb_t cb, void* userdata); 190 191 /** Return the error number of the last failed operation */ 192 int pa_context_errno (const(pa_context)* c); 193 194 /** Return non-zero if some data is pending to be written to the connection */ 195 int pa_context_is_pending (const(pa_context)* c); 196 197 /** Return the current context status */ 198 pa_context_state_t pa_context_get_state (const(pa_context)* c); 199 200 /** Connect the context to the specified server. If server is NULL, 201 * connect to the default server. This routine may but will not always 202 * return synchronously on error. Use pa_context_set_state_callback() to 203 * be notified when the connection is established. If flags doesn't have 204 * PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or 205 * accessible a new daemon is spawned. If api is non-NULL, the functions 206 * specified in the structure are used when forking a new child 207 * process. Returns negative on certain errors such as invalid state 208 * or parameters. */ 209 int 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 */ 212 void pa_context_disconnect (pa_context* c); 213 214 /** Drain the context. If there is nothing to drain, the function returns NULL */ 215 pa_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 */ 220 pa_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. */ 223 pa_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. */ 226 pa_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. */ 229 int pa_context_is_local (const(pa_context)* c); 230 231 /** Set a different application name for context on the server. */ 232 pa_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. */ 235 const(char)* pa_context_get_server (const(pa_context)* c); 236 237 /** Return the protocol version of the library. */ 238 uint pa_context_get_protocol_version (const(pa_context)* c); 239 240 /** Return the protocol version of the connected server. 241 * Returns PA_INVALID_INDEX on error. */ 242 uint pa_context_get_server_protocol_version (const(pa_context)* c); 243 244 /** Update the property list of the client, adding new entries. Please 245 * note that it is highly recommended to set as many properties 246 * initially via pa_context_new_with_proplist() as possible instead a 247 * posteriori with this function, since that information may then be 248 * used to route streams of the client to the right device. \since 0.9.11 */ 249 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); 250 251 /** Update the property list of the client, remove entries. \since 0.9.11 */ 252 pa_operation* pa_context_proplist_remove (pa_context* c, const(char*)* keys, pa_context_success_cb_t cb, void* userdata); 253 254 /** Return the client index this context is 255 * identified in the server with. This is useful for usage with the 256 * introspection functions, such as pa_context_get_client_info(). 257 * Returns PA_INVALID_INDEX on error. \since 0.9.11 */ 258 uint pa_context_get_index (const(pa_context)* s); 259 260 /** Create a new timer event source for the specified time (wrapper 261 * for mainloop->time_new). \since 0.9.16 */ 262 pa_time_event* pa_context_rttime_new (const(pa_context)* c, pa_usec_t usec, pa_time_event_cb_t cb, void* userdata); 263 264 /** Restart a running or expired timer event source (wrapper for 265 * mainloop->time_restart). \since 0.9.16 */ 266 void pa_context_rttime_restart (const(pa_context)* c, pa_time_event* e, pa_usec_t usec); 267 268 /** Return the optimal block size for passing around audio buffers. It 269 * is recommended to allocate buffers of the size returned here when 270 * writing audio data to playback streams, if the latency constraints 271 * permit this. It is not recommended writing larger blocks than this 272 * because usually they will then be split up internally into chunks 273 * of this size. It is not recommended writing smaller blocks than 274 * this (unless required due to latency demands) because this 275 * increases CPU usage. If ss is NULL you will be returned the 276 * byte-exact tile size. if ss is invalid, (size_t) -1 will be 277 * returned. If you pass a valid ss, then the tile size 278 * will be rounded down to multiple of the frame size. This is 279 * supposed to be used in a construct such as 280 * pa_context_get_tile_size(pa_stream_get_context(s), 281 * pa_stream_get_sample_spec(ss)); \since 0.9.20 */ 282 size_t pa_context_get_tile_size (const(pa_context)* c, const(pa_sample_spec)* ss); 283 284 /** Load the authentication cookie from a file. This function is primarily 285 * meant for PulseAudio's own tunnel modules, which need to load the cookie 286 * from a custom location. Applications don't usually need to care about the 287 * cookie at all, but if it happens that you know what the authentication 288 * cookie is and your application needs to load it from a non-standard 289 * location, feel free to use this function. \since 5.0 */ 290 int pa_context_load_cookie_from_file (pa_context* c, const(char)* cookie_file_path); 291