Merge branch 'master' of ssh://rootserver/home/lennart/git/public/pulseaudio
[profile/ivi/pulseaudio.git] / src / pulse / def.h
1 #ifndef foodefhfoo
2 #define foodefhfoo
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
12   published by the Free Software Foundation; either version 2.1 of the
13   License, 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   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public
21   License along with PulseAudio; if not, write to the Free Software
22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
23   USA.
24 ***/
25
26 #include <inttypes.h>
27 #include <sys/time.h>
28 #include <time.h>
29
30 #include <pulse/cdecl.h>
31 #include <pulse/sample.h>
32 #include <pulse/version.h>
33
34 /** \file
35  * Global definitions */
36
37 PA_C_DECL_BEGIN
38
39 /** The state of a connection context */
40 typedef enum pa_context_state {
41     PA_CONTEXT_UNCONNECTED,    /**< The context hasn't been connected yet */
42     PA_CONTEXT_CONNECTING,     /**< A connection is being established */
43     PA_CONTEXT_AUTHORIZING,    /**< The client is authorizing itself to the daemon */
44     PA_CONTEXT_SETTING_NAME,   /**< The client is passing its application name to the daemon */
45     PA_CONTEXT_READY,          /**< The connection is established, the context is ready to execute operations */
46     PA_CONTEXT_FAILED,         /**< The connection failed or was disconnected */
47     PA_CONTEXT_TERMINATED      /**< The connection was terminated cleanly */
48 } pa_context_state_t;
49
50 /** Return non-zero if the passed state is one of the connected states. \since 0.9.11 */
51 static inline int PA_CONTEXT_IS_GOOD(pa_context_state_t x) {
52     return
53         x == PA_CONTEXT_CONNECTING ||
54         x == PA_CONTEXT_AUTHORIZING ||
55         x == PA_CONTEXT_SETTING_NAME ||
56         x == PA_CONTEXT_READY;
57 }
58
59 /** \cond fulldocs */
60 #define PA_CONTEXT_UNCONNECTED PA_CONTEXT_UNCONNECTED
61 #define PA_CONTEXT_CONNECTING PA_CONTEXT_CONNECTING
62 #define PA_CONTEXT_AUTHORIZING PA_CONTEXT_AUTHORIZING
63 #define PA_CONTEXT_SETTING_NAME PA_CONTEXT_SETTING_NAME
64 #define PA_CONTEXT_READY PA_CONTEXT_READY
65 #define PA_CONTEXT_FAILED PA_CONTEXT_FAILED
66 #define PA_CONTEXT_IS_GOOD PA_CONTEXT_IS_GOOD
67 /** \endcond */
68
69 /** The state of a stream */
70 typedef enum pa_stream_state {
71     PA_STREAM_UNCONNECTED,  /**< The stream is not yet connected to any sink or source */
72     PA_STREAM_CREATING,     /**< The stream is being created */
73     PA_STREAM_READY,        /**< The stream is established, you may pass audio data to it now */
74     PA_STREAM_FAILED,       /**< An error occurred that made the stream invalid */
75     PA_STREAM_TERMINATED    /**< The stream has been terminated cleanly */
76 } pa_stream_state_t;
77
78 /** Return non-zero if the passed state is one of the connected states. \since 0.9.11 */
79 static inline int PA_STREAM_IS_GOOD(pa_stream_state_t x) {
80     return
81         x == PA_STREAM_CREATING ||
82         x == PA_STREAM_READY;
83 }
84
85 /** \cond fulldocs */
86 #define PA_STREAM_UNCONNECTED PA_STREAM_UNCONNECTED
87 #define PA_STREAM_CREATING PA_STREAM_CREATING
88 #define PA_STREAM_READY PA_STREAM_READY
89 #define PA_STREAM_FAILED PA_STREAM_FAILED
90 #define PA_STREAM_TERMINATED PA_STREAM_TERMINATED
91 #define PA_STREAM_IS_GOOD PA_STREAM_IS_GOOD
92 /** \endcond */
93
94 /** The state of an operation */
95 typedef enum pa_operation_state {
96     PA_OPERATION_RUNNING,      /**< The operation is still running */
97     PA_OPERATION_DONE,         /**< The operation has been completed */
98     PA_OPERATION_CANCELED      /**< The operation has been canceled */
99 } pa_operation_state_t;
100
101 /** \cond fulldocs */
102 #define PA_OPERATION_RUNNING PA_OPERATION_RUNNING
103 #define PA_OPERATION_DONE PA_OPERATION_DONE
104 #define PA_OPERATION_CANCELED PA_OPERATION_CANCELED
105 /** \endcond */
106
107 /** An invalid index */
108 #define PA_INVALID_INDEX ((uint32_t) -1)
109
110 /** Some special flags for contexts. */
111 typedef enum pa_context_flags {
112     PA_CONTEXT_NOAUTOSPAWN = 0x0001U,
113     /**< Disabled autospawning of the PulseAudio daemon if required */
114     PA_CONTEXT_NOFAIL = 0x0002U
115     /**< Don't fail if the daemon is not available when pa_context_connect() is called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon to appear.  \since 0.9.15 */
116 } pa_context_flags_t;
117
118 /** \cond fulldocs */
119 /* Allow clients to check with #ifdef for those flags */
120 #define PA_CONTEXT_NOAUTOSPAWN PA_CONTEXT_NOAUTOSPAWN
121 #define PA_CONTEXT_NOFAIL PA_CONTEXT_NOFAIL
122 /** \endcond */
123
124 /** The direction of a pa_stream object */
125 typedef enum pa_stream_direction {
126     PA_STREAM_NODIRECTION,   /**< Invalid direction */
127     PA_STREAM_PLAYBACK,      /**< Playback stream */
128     PA_STREAM_RECORD,        /**< Record stream */
129     PA_STREAM_UPLOAD         /**< Sample upload stream */
130 } pa_stream_direction_t;
131
132 /** \cond fulldocs */
133 #define PA_STREAM_NODIRECTION PA_STREAM_NODIRECTION
134 #define PA_STREAM_PLAYBACK PA_STREAM_PLAYBACK
135 #define PA_STREAM_RECORD PA_STREAM_RECORD
136 #define PA_STREAM_UPLOAD PA_STREAM_UPLOAD
137 /** \endcond */
138
139 /** Some special flags for stream connections. */
140 typedef enum pa_stream_flags {
141
142     PA_STREAM_START_CORKED = 0x0001U,
143     /**< Create the stream corked, requiring an explicit
144      * pa_stream_cork() call to uncork it. */
145
146     PA_STREAM_INTERPOLATE_TIMING = 0x0002U,
147     /**< Interpolate the latency for this stream. When enabled,
148      * pa_stream_get_latency() and pa_stream_get_time() will try to
149      * estimate the current record/playback time based on the local
150      * time that passed since the last timing info update.  Using this
151      * option has the advantage of not requiring a whole roundtrip
152      * when the current playback/recording time is needed. Consider
153      * using this option when requesting latency information
154      * frequently. This is especially useful on long latency network
155      * connections. It makes a lot of sense to combine this option
156      * with PA_STREAM_AUTO_TIMING_UPDATE. */
157
158     PA_STREAM_NOT_MONOTONIC = 0x0004U,
159     /**< Don't force the time to increase monotonically. If this
160      * option is enabled, pa_stream_get_time() will not necessarily
161      * return always monotonically increasing time values on each
162      * call. This may confuse applications which cannot deal with time
163      * going 'backwards', but has the advantage that bad transport
164      * latency estimations that caused the time to to jump ahead can
165      * be corrected quickly, without the need to wait. (Please note
166      * that this flag was named PA_STREAM_NOT_MONOTONOUS in releases
167      * prior to 0.9.11. The old name is still defined too, for
168      * compatibility reasons. */
169
170     PA_STREAM_AUTO_TIMING_UPDATE = 0x0008U,
171     /**< If set timing update requests are issued periodically
172      * automatically. Combined with PA_STREAM_INTERPOLATE_TIMING you
173      * will be able to query the current time and latency with
174      * pa_stream_get_time() and pa_stream_get_latency() at all times
175      * without a packet round trip.*/
176
177     PA_STREAM_NO_REMAP_CHANNELS = 0x0010U,
178     /**< Don't remap channels by their name, instead map them simply
179      * by their index. Implies PA_STREAM_NO_REMIX_CHANNELS. Only
180      * supported when the server is at least PA 0.9.8. It is ignored
181      * on older servers.\since 0.9.8 */
182
183     PA_STREAM_NO_REMIX_CHANNELS = 0x0020U,
184     /**< When remapping channels by name, don't upmix or downmix them
185      * to related channels. Copy them into matching channels of the
186      * device 1:1. Only supported when the server is at least PA
187      * 0.9.8. It is ignored on older servers. \since 0.9.8 */
188
189     PA_STREAM_FIX_FORMAT = 0x0040U,
190     /**< Use the sample format of the sink/device this stream is being
191      * connected to, and possibly ignore the format the sample spec
192      * contains -- but you still have to pass a valid value in it as a
193      * hint to PulseAudio what would suit your stream best. If this is
194      * used you should query the used sample format after creating the
195      * stream by using pa_stream_get_sample_spec(). Also, if you
196      * specified manual buffer metrics it is recommended to update
197      * them with pa_stream_set_buffer_attr() to compensate for the
198      * changed frame sizes. Only supported when the server is at least
199      * PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
200
201     PA_STREAM_FIX_RATE = 0x0080U,
202     /**< Use the sample rate of the sink, and possibly ignore the rate
203      * the sample spec contains. Usage similar to
204      * PA_STREAM_FIX_FORMAT.Only supported when the server is at least
205      * PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
206
207     PA_STREAM_FIX_CHANNELS = 0x0100,
208     /**< Use the number of channels and the channel map of the sink,
209      * and possibly ignore the number of channels and the map the
210      * sample spec and the passed channel map contains. Usage similar
211      * to PA_STREAM_FIX_FORMAT. Only supported when the server is at
212      * least PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
213
214     PA_STREAM_DONT_MOVE = 0x0200U,
215     /**< Don't allow moving of this stream to another
216      * sink/device. Useful if you use any of the PA_STREAM_FIX_ flags
217      * and want to make sure that resampling never takes place --
218      * which might happen if the stream is moved to another
219      * sink/source with a different sample spec/channel map. Only
220      * supported when the server is at least PA 0.9.8. It is ignored
221      * on older servers. \since 0.9.8 */
222
223     PA_STREAM_VARIABLE_RATE = 0x0400U,
224     /**< Allow dynamic changing of the sampling rate during playback
225      * with pa_stream_update_sample_rate(). Only supported when the
226      * server is at least PA 0.9.8. It is ignored on older
227      * servers. \since 0.9.8 */
228
229     PA_STREAM_PEAK_DETECT = 0x0800U,
230     /**< Find peaks instead of resampling. \since 0.9.11 */
231
232     PA_STREAM_START_MUTED = 0x1000U,
233     /**< Create in muted state. If neither PA_STREAM_START_UNMUTED nor
234      * PA_STREAM_START_MUTED it is left to the server to decide
235      * whether to create the stream in muted or in unmuted
236      * state. \since 0.9.11 */
237
238     PA_STREAM_ADJUST_LATENCY = 0x2000U,
239     /**< Try to adjust the latency of the sink/source based on the
240      * requested buffer metrics and adjust buffer metrics
241      * accordingly. Also see pa_buffer_attr. This option may not be
242      * specified at the same time as PA_STREAM_EARLY_REQUESTS. \since
243      * 0.9.11 */
244
245     PA_STREAM_EARLY_REQUESTS = 0x4000U,
246     /**< Enable compatibility mode for legacy clients that rely on a
247      * "classic" hardware device fragment-style playback model. If
248      * this option is set, the minreq value of the buffer metrics gets
249      * a new meaning: instead of just specifying that no requests
250      * asking for less new data than this value will be made to the
251      * client it will also guarantee that requests are generated as
252      * early as this limit is reached. This flag should only be set in
253      * very few situations where compatibility with a fragment-based
254      * playback model needs to be kept and the client applications
255      * cannot deal with data requests that are delayed to the latest
256      * moment possible. (Usually these are programs that use usleep()
257      * or a similar call in their playback loops instead of sleeping
258      * on the device itself.) Also see pa_buffer_attr. This option may
259      * not be specified at the same time as
260      * PA_STREAM_ADJUST_LATENCY. \since 0.9.12 */
261
262     PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND = 0x8000U,
263     /**< If set this stream won't be taken into account when we it is
264      * checked whether the device this stream is connected to should
265      * auto-suspend. \since 0.9.15 */
266
267     PA_STREAM_START_UNMUTED = 0x10000U,
268     /**< Create in unmuted state. If neither PA_STREAM_START_UNMUTED
269      * nor PA_STREAM_START_MUTED it is left to the server to decide
270      * whether to create the stream in muted or in unmuted
271      * state. \since 0.9.15 */
272
273     PA_STREAM_FAIL_ON_SUSPEND = 0x20000U
274     /**< If the sink/source this stream is connected to is suspended
275      * during the creation of this stream, cause it to fail. If the
276      * sink/source is being suspended during creation of this stream,
277      * make sure this stream is terminated. \since 0.9.15 */
278 } pa_stream_flags_t;
279
280 /** \cond fulldocs */
281
282 /* English is an evil language */
283 #define PA_STREAM_NOT_MONOTONOUS PA_STREAM_NOT_MONOTONIC
284
285 /* Allow clients to check with #ifdef for those flags */
286 #define PA_STREAM_START_CORKED PA_STREAM_START_CORKED
287 #define PA_STREAM_INTERPOLATE_TIMING PA_STREAM_INTERPOLATE_TIMING
288 #define PA_STREAM_NOT_MONOTONIC PA_STREAM_NOT_MONOTONIC
289 #define PA_STREAM_AUTO_TIMING_UPDATE PA_STREAM_AUTO_TIMING_UPDATE
290 #define PA_STREAM_NO_REMAP_CHANNELS PA_STREAM_NO_REMAP_CHANNELS
291 #define PA_STREAM_NO_REMIX_CHANNELS PA_STREAM_NO_REMIX_CHANNELS
292 #define PA_STREAM_FIX_FORMAT PA_STREAM_FIX_FORMAT
293 #define PA_STREAM_FIX_RATE PA_STREAM_FIX_RATE
294 #define PA_STREAM_FIX_CHANNELS PA_STREAM_FIX_CHANNELS
295 #define PA_STREAM_DONT_MOVE PA_STREAM_DONT_MOVE
296 #define PA_STREAM_VARIABLE_RATE PA_STREAM_VARIABLE_RATE
297 #define PA_STREAM_PEAK_DETECT PA_STREAM_PEAK_DETECT
298 #define PA_STREAM_START_MUTED PA_STREAM_START_MUTED
299 #define PA_STREAM_ADJUST_LATENCY PA_STREAM_ADJUST_LATENCY
300 #define PA_STREAM_EARLY_REQUESTS PA_STREAM_EARLY_REQUESTS
301 #define PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND
302 #define PA_STREAM_START_UNMUTED PA_STREAM_START_UNMUTED
303 #define PA_STREAM_FAIL_ON_SUSPEND PA_STREAM_FAIL_ON_SUSPEND
304
305 /** \endcond */
306
307 /** Playback and record buffer metrics */
308 typedef struct pa_buffer_attr {
309     uint32_t maxlength;
310     /**< Maximum length of the buffer. Setting this to (uint32_t) -1
311      * will initialize this to the maximum value supported by server,
312      * which is recommended. */
313
314     uint32_t tlength;
315     /**< Playback only: target length of the buffer. The server tries
316      * to assure that at least tlength bytes are always available in
317      * the per-stream server-side playback buffer. It is recommended
318      * to set this to (uint32_t) -1, which will initialize this to a
319      * value that is deemed sensible by the server. However, this
320      * value will default to something like 2s, i.e. for applications
321      * that have specific latency requirements this value should be
322      * set to the maximum latency that the application can deal
323      * with. When PA_STREAM_ADJUST_LATENCY is not set this value will
324      * influence only the per-stream playback buffer size. When
325      * PA_STREAM_ADJUST_LATENCY is set the overall latency of the sink
326      * plus the playback buffer size is configured to this value. Set
327      * PA_STREAM_ADJUST_LATENCY if you are interested in adjusting the
328      * overall latency. Don't set it if you are interested in
329      * configuring the server-side per-stream playback buffer
330      * size. */
331
332     uint32_t prebuf;
333     /**< Playback only: pre-buffering. The server does not start with
334      * playback before at least prebuf bytes are available in the
335      * buffer. It is recommended to set this to (uint32_t) -1, which
336      * will initialize this to the same value as tlength, whatever
337      * that may be. Initialize to 0 to enable manual start/stop
338      * control of the stream. This means that playback will not stop
339      * on underrun and playback will not start automatically. Instead
340      * pa_stream_corked() needs to be called explicitly. If you set
341      * this value to 0 you should also set PA_STREAM_START_CORKED. */
342
343     uint32_t minreq;
344     /**< Playback only: minimum request. The server does not request
345      * less than minreq bytes from the client, instead waits until the
346      * buffer is free enough to request more bytes at once. It is
347      * recommended to set this to (uint32_t) -1, which will initialize
348      * this to a value that is deemed sensible by the server. This
349      * should be set to a value that gives PulseAudio enough time to
350      * move the data from the per-stream playback buffer into the
351      * hardware playback buffer. */
352
353     uint32_t fragsize;
354     /**< Recording only: fragment size. The server sends data in
355      * blocks of fragsize bytes size. Large values diminish
356      * interactivity with other operations on the connection context
357      * but decrease control overhead. It is recommended to set this to
358      * (uint32_t) -1, which will initialize this to a value that is
359      * deemed sensible by the server. However, this value will default
360      * to something like 2s, i.e. for applications that have specific
361      * latency requirements this value should be set to the maximum
362      * latency that the application can deal with. If
363      * PA_STREAM_ADJUST_LATENCY is set the overall source latency will
364      * be adjusted according to this value. If it is not set the
365      * source latency is left unmodified. */
366
367 } pa_buffer_attr;
368
369 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
370 enum {
371     PA_OK = 0,                     /**< No error */
372     PA_ERR_ACCESS,                 /**< Access failure */
373     PA_ERR_COMMAND,                /**< Unknown command */
374     PA_ERR_INVALID,                /**< Invalid argument */
375     PA_ERR_EXIST,                  /**< Entity exists */
376     PA_ERR_NOENTITY,               /**< No such entity */
377     PA_ERR_CONNECTIONREFUSED,      /**< Connection refused */
378     PA_ERR_PROTOCOL,               /**< Protocol error */
379     PA_ERR_TIMEOUT,                /**< Timeout */
380     PA_ERR_AUTHKEY,                /**< No authorization key */
381     PA_ERR_INTERNAL,               /**< Internal error */
382     PA_ERR_CONNECTIONTERMINATED,   /**< Connection terminated */
383     PA_ERR_KILLED,                 /**< Entity killed */
384     PA_ERR_INVALIDSERVER,          /**< Invalid server */
385     PA_ERR_MODINITFAILED,          /**< Module initialization failed */
386     PA_ERR_BADSTATE,               /**< Bad state */
387     PA_ERR_NODATA,                 /**< No data */
388     PA_ERR_VERSION,                /**< Incompatible protocol version */
389     PA_ERR_TOOLARGE,               /**< Data too large */
390     PA_ERR_NOTSUPPORTED,           /**< Operation not supported \since 0.9.5 */
391     PA_ERR_UNKNOWN,                /**< The error code was unknown to the client */
392     PA_ERR_NOEXTENSION,            /**< Extension does not exist. \since 0.9.12 */
393     PA_ERR_OBSOLETE,               /**< Obsolete functionality. \since 0.9.15 */
394     PA_ERR_NOTIMPLEMENTED,         /**< Missing implementation. \since 0.9.15 */
395     PA_ERR_FORKED,                 /**< The caller forked without calling execve() and tried to reuse the context. \since 0.9.15 */
396     PA_ERR_MAX                     /**< Not really an error but the first invalid error code */
397 };
398
399 /** \cond fulldocs */
400 #define PA_OK PA_OK
401 #define PA_ERR_ACCESS PA_ERR_ACCESS
402 #define PA_ERR_COMMAND PA_ERR_COMMAND
403 #define PA_ERR_INVALID PA_ERR_INVALID
404 #define PA_ERR_EXIST PA_ERR_EXIST
405 #define PA_ERR_NOENTITY PA_ERR_NOENTITY
406 #define PA_ERR_CONNECTIONREFUSED PA_ERR_CONNECTIONREFUSED
407 #define PA_ERR_PROTOCOL PA_ERR_PROTOCOL
408 #define PA_ERR_TIMEOUT PA_ERR_TIMEOUT
409 #define PA_ERR_AUTHKEY PA_ERR_AUTHKEY
410 #define PA_ERR_INTERNAL PA_ERR_INTERNAL
411 #define PA_ERR_CONNECTIONTERMINATED PA_ERR_CONNECTIONTERMINATED
412 #define PA_ERR_KILLED PA_ERR_KILLED
413 #define PA_ERR_INVALIDSERVER PA_ERR_INVALIDSERVER
414 #define PA_ERR_MODINITFAILED PA_ERR_MODINITFAILED
415 #define PA_ERR_BADSTATE PA_ERR_BADSTATE
416 #define PA_ERR_NODATA PA_ERR_NODATA
417 #define PA_ERR_VERSION PA_ERR_VERSION
418 #define PA_ERR_TOOLARGE PA_ERR_TOOLARGE
419 #define PA_ERR_NOTSUPPORTED PA_ERR_NOTSUPPORTED
420 #define PA_ERR_UNKNOWN PA_ERR_UNKNOWN
421 #define PA_ERR_NOEXTENSION PA_ERR_NOEXTENSION
422 #define PA_ERR_OBSOLETE PA_ERR_OBSOLETE
423 #define PA_ERR_NOTIMPLEMENTED PA_ERR_NOTIMPLEMENTED
424 #define PA_ERR_FORKED PA_ERR_FORKED
425 #define PA_ERR_MAX PA_ERR_MAX
426 /** \endcond */
427
428 /** Subscription event mask, as used by pa_context_subscribe() */
429 typedef enum pa_subscription_mask {
430     PA_SUBSCRIPTION_MASK_NULL = 0x0000U,
431     /**< No events */
432
433     PA_SUBSCRIPTION_MASK_SINK = 0x0001U,
434     /**< Sink events */
435
436     PA_SUBSCRIPTION_MASK_SOURCE = 0x0002U,
437     /**< Source events */
438
439     PA_SUBSCRIPTION_MASK_SINK_INPUT = 0x0004U,
440     /**< Sink input events */
441
442     PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 0x0008U,
443     /**< Source output events */
444
445     PA_SUBSCRIPTION_MASK_MODULE = 0x0010U,
446     /**< Module events */
447
448     PA_SUBSCRIPTION_MASK_CLIENT = 0x0020U,
449     /**< Client events */
450
451     PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 0x0040U,
452     /**< Sample cache events */
453
454     PA_SUBSCRIPTION_MASK_SERVER = 0x0080U,
455     /**< Other global server changes. */
456
457 /** \cond fulldocs */
458     PA_SUBSCRIPTION_MASK_AUTOLOAD = 0x0100U,
459     /**< \deprecated Autoload table events. */
460 /** \endcond */
461
462     PA_SUBSCRIPTION_MASK_CARD = 0x0200U,
463     /**< Card events. \since 0.9.15 */
464
465     PA_SUBSCRIPTION_MASK_ALL = 0x02ffU
466     /**< Catch all events */
467 } pa_subscription_mask_t;
468
469 /** Subscription event types, as used by pa_context_subscribe() */
470 typedef enum pa_subscription_event_type {
471     PA_SUBSCRIPTION_EVENT_SINK = 0x0000U,
472     /**< Event type: Sink */
473
474     PA_SUBSCRIPTION_EVENT_SOURCE = 0x0001U,
475     /**< Event type: Source */
476
477     PA_SUBSCRIPTION_EVENT_SINK_INPUT = 0x0002U,
478     /**< Event type: Sink input */
479
480     PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 0x0003U,
481     /**< Event type: Source output */
482
483     PA_SUBSCRIPTION_EVENT_MODULE = 0x0004U,
484     /**< Event type: Module */
485
486     PA_SUBSCRIPTION_EVENT_CLIENT = 0x0005U,
487     /**< Event type: Client */
488
489     PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 0x0006U,
490     /**< Event type: Sample cache item */
491
492     PA_SUBSCRIPTION_EVENT_SERVER = 0x0007U,
493     /**< Event type: Global server change, only occurring with PA_SUBSCRIPTION_EVENT_CHANGE. */
494
495 /** \cond fulldocs */
496     PA_SUBSCRIPTION_EVENT_AUTOLOAD = 0x0008U,
497     /**< \deprecated Event type: Autoload table changes. */
498 /** \endcond */
499
500     PA_SUBSCRIPTION_EVENT_CARD = 0x0009U,
501     /**< Event type: Card \since 0.9.15 */
502
503     PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 0x000FU,
504     /**< A mask to extract the event type from an event value */
505
506     PA_SUBSCRIPTION_EVENT_NEW = 0x0000U,
507     /**< A new object was created */
508
509     PA_SUBSCRIPTION_EVENT_CHANGE = 0x0010U,
510     /**< A property of the object was modified */
511
512     PA_SUBSCRIPTION_EVENT_REMOVE = 0x0020U,
513     /**< An object was removed */
514
515     PA_SUBSCRIPTION_EVENT_TYPE_MASK = 0x0030U
516     /**< A mask to extract the event operation from an event value */
517
518 } pa_subscription_event_type_t;
519
520 /** Return one if an event type t matches an event mask bitfield */
521 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
522
523 /** \cond fulldocs */
524 #define PA_SUBSCRIPTION_MASK_NULL PA_SUBSCRIPTION_MASK_NULL
525 #define PA_SUBSCRIPTION_MASK_SINK PA_SUBSCRIPTION_MASK_SINK
526 #define PA_SUBSCRIPTION_MASK_SOURCE PA_SUBSCRIPTION_MASK_SOURCE
527 #define PA_SUBSCRIPTION_MASK_SINK_INPUT PA_SUBSCRIPTION_MASK_SINK_INPUT
528 #define PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT
529 #define PA_SUBSCRIPTION_MASK_MODULE PA_SUBSCRIPTION_MASK_MODULE
530 #define PA_SUBSCRIPTION_MASK_CLIENT PA_SUBSCRIPTION_MASK_CLIENT
531 #define PA_SUBSCRIPTION_MASK_SAMPLE_CACHE PA_SUBSCRIPTION_MASK_SAMPLE_CACHE
532 #define PA_SUBSCRIPTION_MASK_SERVER PA_SUBSCRIPTION_MASK_SERVER
533 #define PA_SUBSCRIPTION_MASK_AUTOLOAD PA_SUBSCRIPTION_MASK_AUTOLOAD
534 #define PA_SUBSCRIPTION_MASK_CARD PA_SUBSCRIPTION_MASK_CARD
535 #define PA_SUBSCRIPTION_MASK_ALL PA_SUBSCRIPTION_MASK_ALL
536 #define PA_SUBSCRIPTION_EVENT_SINK PA_SUBSCRIPTION_EVENT_SINK
537 #define PA_SUBSCRIPTION_EVENT_SOURCE PA_SUBSCRIPTION_EVENT_SOURCE
538 #define PA_SUBSCRIPTION_EVENT_SINK_INPUT PA_SUBSCRIPTION_EVENT_SINK_INPUT
539 #define PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT
540 #define PA_SUBSCRIPTION_EVENT_MODULE PA_SUBSCRIPTION_EVENT_MODULE
541 #define PA_SUBSCRIPTION_EVENT_CLIENT PA_SUBSCRIPTION_EVENT_CLIENT
542 #define PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE
543 #define PA_SUBSCRIPTION_EVENT_SERVER PA_SUBSCRIPTION_EVENT_SERVER
544 #define PA_SUBSCRIPTION_EVENT_AUTOLOAD PA_SUBSCRIPTION_EVENT_AUTOLOAD
545 #define PA_SUBSCRIPTION_EVENT_CARD PA_SUBSCRIPTION_EVENT_CARD
546 #define PA_SUBSCRIPTION_EVENT_FACILITY_MASK PA_SUBSCRIPTION_EVENT_FACILITY_MASK
547 #define PA_SUBSCRIPTION_EVENT_NEW PA_SUBSCRIPTION_EVENT_NEW
548 #define PA_SUBSCRIPTION_EVENT_CHANGE PA_SUBSCRIPTION_EVENT_CHANGE
549 #define PA_SUBSCRIPTION_EVENT_REMOVE PA_SUBSCRIPTION_EVENT_REMOVE
550 #define PA_SUBSCRIPTION_EVENT_TYPE_MASK PA_SUBSCRIPTION_EVENT_TYPE_MASK
551 /** \endcond */
552
553 /** A structure for all kinds of timing information of a stream. See
554  * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
555  * total output latency a sample that is written with
556  * pa_stream_write() takes to be played may be estimated by
557  * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
558  * as pa_bytes_to_usec(write_index-read_index)) The output buffer
559  * which buffer_usec relates to may be manipulated freely (with
560  * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
561  * the buffers sink_usec and source_usec relate to are first-in
562  * first-out (FIFO) buffers which cannot be flushed or manipulated in
563  * any way. The total input latency a sample that is recorded takes to
564  * be delivered to the application is:
565  * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
566  * sign issues!) When connected to a monitor source sink_usec contains
567  * the latency of the owning sink. The two latency estimations
568  * described here are implemented in pa_stream_get_latency(). Please
569  * note that this structure can be extended as part of evolutionary
570  * API updates at any time in any new release.*/
571 typedef struct pa_timing_info {
572     struct timeval timestamp;
573     /**< The time when this timing info structure was current */
574
575     int synchronized_clocks;
576     /**< Non-zero if the local and the remote machine have
577      * synchronized clocks. If synchronized clocks are detected
578      * transport_usec becomes much more reliable. However, the code
579      * that detects synchronized clocks is very limited and unreliable
580      * itself. */
581
582     pa_usec_t sink_usec;
583     /**< Time in usecs a sample takes to be played on the sink. For
584      * playback streams and record streams connected to a monitor
585      * source. */
586
587     pa_usec_t source_usec;
588     /**< Time in usecs a sample takes from being recorded to being
589      * delivered to the application. Only for record streams. */
590
591     pa_usec_t transport_usec;
592     /**< Estimated time in usecs a sample takes to be transferred
593      * to/from the daemon. For both playback and record streams. */
594
595     int playing;
596     /**< Non-zero when the stream is currently not underrun and data
597      * is being passed on to the device. Only for playback
598      * streams. This field does not say whether the data is actually
599      * already being played. To determine this check whether
600      * since_underrun (converted to usec) is larger than sink_usec.*/
601
602     int write_index_corrupt;
603     /**< Non-zero if write_index is not up-to-date because a local
604      * write command that corrupted it has been issued in the time
605      * since this latency info was current . Only write commands with
606      * SEEK_RELATIVE_ON_READ and SEEK_RELATIVE_END can corrupt
607      * write_index. */
608
609     int64_t write_index;
610     /**< Current write index into the playback buffer in bytes. Think
611      * twice before using this for seeking purposes: it might be out
612      * of date a the time you want to use it. Consider using
613      * PA_SEEK_RELATIVE instead. */
614
615     int read_index_corrupt;
616     /**< Non-zero if read_index is not up-to-date because a local
617      * pause or flush request that corrupted it has been issued in the
618      * time since this latency info was current. */
619
620     int64_t read_index;
621     /**< Current read index into the playback buffer in bytes. Think
622      * twice before using this for seeking purposes: it might be out
623      * of date a the time you want to use it. Consider using
624      * PA_SEEK_RELATIVE_ON_READ instead. */
625
626     pa_usec_t configured_sink_usec;
627     /**< The configured latency for the sink. \since 0.9.11 */
628
629     pa_usec_t configured_source_usec;
630     /**< The configured latency for the source. \since 0.9.11 */
631
632     int64_t since_underrun;
633     /**< Bytes that were handed to the sink since the last underrun
634      * happened, or since playback started again after the last
635      * underrun. playing will tell you which case it is. \since
636      * 0.9.11 */
637
638 } pa_timing_info;
639
640 /** A structure for the spawn api. This may be used to integrate auto
641  * spawned daemons into your application. For more information see
642  * pa_context_connect(). When spawning a new child process the
643  * waitpid() is used on the child's PID. The spawn routine will not
644  * block or ignore SIGCHLD signals, since this cannot be done in a
645  * thread compatible way. You might have to do this in
646  * prefork/postfork. */
647 typedef struct pa_spawn_api {
648     void (*prefork)(void);
649     /**< Is called just before the fork in the parent process. May be
650      * NULL. */
651
652     void (*postfork)(void);
653     /**< Is called immediately after the fork in the parent
654      * process. May be NULL.*/
655
656     void (*atfork)(void);
657     /**< Is called immediately after the fork in the child
658      * process. May be NULL. It is not safe to close all file
659      * descriptors in this function unconditionally, since a UNIX
660      * socket (created using socketpair()) is passed to the new
661      * process. */
662 } pa_spawn_api;
663
664 /** Seek type for pa_stream_write(). */
665 typedef enum pa_seek_mode {
666     PA_SEEK_RELATIVE = 0,
667     /**< Seek relatively to the write index */
668
669     PA_SEEK_ABSOLUTE = 1,
670     /**< Seek relatively to the start of the buffer queue */
671
672     PA_SEEK_RELATIVE_ON_READ = 2,
673     /**< Seek relatively to the read index.  */
674
675     PA_SEEK_RELATIVE_END = 3
676     /**< Seek relatively to the current end of the buffer queue. */
677 } pa_seek_mode_t;
678
679 /** \cond fulldocs */
680 #define PA_SEEK_RELATIVE PA_SEEK_RELATIVE
681 #define PA_SEEK_ABSOLUTE PA_SEEK_ABSOLUTE
682 #define PA_SEEK_RELATIVE_ON_READ PA_SEEK_RELATIVE_ON_READ
683 #define PA_SEEK_RELATIVE_END PA_SEEK_RELATIVE_END
684 /** \endcond */
685
686 /** Special sink flags. */
687 typedef enum pa_sink_flags {
688     PA_SINK_HW_VOLUME_CTRL = 0x0001U,
689     /**< Supports hardware volume control */
690
691     PA_SINK_LATENCY = 0x0002U,
692     /**< Supports latency querying */
693
694     PA_SINK_HARDWARE = 0x0004U,
695     /**< Is a hardware sink of some kind, in contrast to
696      * "virtual"/software sinks \since 0.9.3 */
697
698     PA_SINK_NETWORK = 0x0008U,
699     /**< Is a networked sink of some kind. \since 0.9.7 */
700
701     PA_SINK_HW_MUTE_CTRL = 0x0010U,
702     /**< Supports hardware mute control \since 0.9.11 */
703
704     PA_SINK_DECIBEL_VOLUME = 0x0020U,
705     /**< Volume can be translated to dB with pa_sw_volume_to_dB()
706      * \since 0.9.11 */
707
708     PA_SINK_FLAT_VOLUME = 0x0040U,
709     /**< This sink is in flat volume mode, i.e. always the maximum of
710      * the volume of all connected inputs. \since 0.9.15 */
711
712     PA_SINK_DYNAMIC_LATENCY = 0x0080U
713     /**< The latency can be adjusted dynamically depending on the
714      * needs of the connected streams. \since 0.9.15 */
715 } pa_sink_flags_t;
716
717 /** \cond fulldocs */
718 #define PA_SINK_HW_VOLUME_CTRL PA_SINK_HW_VOLUME_CTRL
719 #define PA_SINK_LATENCY PA_SINK_LATENCY
720 #define PA_SINK_HARDWARE PA_SINK_HARDWARE
721 #define PA_SINK_NETWORK PA_SINK_NETWORK
722 #define PA_SINK_HW_MUTE_CTRL PA_SINK_HW_MUTE_CTRL
723 #define PA_SINK_DECIBEL_VOLUME PA_SINK_DECIBEL_VOLUME
724 #define PA_SINK_FLAT_VOLUME PA_SINK_FLAT_VOLUME
725 #define PA_SINK_DYNAMIC_LATENCY PA_SINK_DYNAMIC_LATENCY
726 /** \endcond */
727
728 /** Sink state. \since 0.9.15 */
729 typedef enum pa_sink_state { /* enum serialized in u8 */
730     PA_SINK_INVALID_STATE = -1,
731     /**< This state is used when the server does not support sink state introspection \since 0.9.15 */
732
733     PA_SINK_RUNNING = 0,
734     /**< Running, sink is playing and used by at least one non-corked sink-input \since 0.9.15 */
735
736     PA_SINK_IDLE = 1,
737     /**< When idle, the sink is playing but there is no non-corked sink-input attached to it \since 0.9.15 */
738
739     PA_SINK_SUSPENDED = 2,
740     /**< When suspended, actual sink access can be closed, for instance \since 0.9.15 */
741
742 /** \cond fulldocs */
743     /* PRIVATE: Server-side values -- DO NOT USE THIS ON THE CLIENT
744      * SIDE! These values are *not* considered part of the official PA
745      * API/ABI. If you use them your application might break when PA
746      * is upgraded. Also, please note that these values are not useful
747      * on the client side anyway. */
748
749     PA_SINK_INIT = -2,
750     /**< Initialization state */
751
752     PA_SINK_UNLINKED = -3
753     /**< The state when the sink is getting unregistered and removed from client access */
754 /** \endcond */
755
756 } pa_sink_state_t;
757
758 /** Returns non-zero if sink is playing: running or idle. \since 0.9.15 */
759 static inline int PA_SINK_IS_OPENED(pa_sink_state_t x) {
760     return x == PA_SINK_RUNNING || x == PA_SINK_IDLE;
761 }
762
763 /** \cond fulldocs */
764 #define PA_SINK_INVALID_STATE PA_SINK_INVALID_STATE
765 #define PA_SINK_RUNNING PA_SINK_RUNNING
766 #define PA_SINK_IDLE PA_SINK_IDLE
767 #define PA_SINK_SUSPENDED PA_SINK_SUSPENDED
768 #define PA_SINK_INIT PA_SINK_INIT
769 #define PA_SINK_UNLINKED PA_SINK_UNLINKED
770 #define PA_SINK_IS_OPENED PA_SINK_IS_OPENED
771 /** \endcond */
772
773 /** Special source flags.  */
774 typedef enum pa_source_flags {
775     PA_SOURCE_HW_VOLUME_CTRL = 0x0001U,
776     /**< Supports hardware volume control */
777
778     PA_SOURCE_LATENCY = 0x0002U,
779     /**< Supports latency querying */
780
781     PA_SOURCE_HARDWARE = 0x0004U,
782     /**< Is a hardware source of some kind, in contrast to
783      * "virtual"/software source \since 0.9.3 */
784
785     PA_SOURCE_NETWORK = 0x0008U,
786     /**< Is a networked source of some kind. \since 0.9.7 */
787
788     PA_SOURCE_HW_MUTE_CTRL = 0x0010U,
789     /**< Supports hardware mute control \since 0.9.11 */
790
791     PA_SOURCE_DECIBEL_VOLUME = 0x0020U,
792     /**< Volume can be translated to dB with pa_sw_volume_to_dB()
793      * \since 0.9.11 */
794
795     PA_SOURCE_DYNAMIC_LATENCY = 0x0040U
796     /**< The latency can be adjusted dynamically depending on the
797      * needs of the connected streams. \since 0.9.15 */
798 } pa_source_flags_t;
799
800 /** \cond fulldocs */
801 #define PA_SOURCE_HW_VOLUME_CTRL PA_SOURCE_HW_VOLUME_CTRL
802 #define PA_SOURCE_LATENCY PA_SOURCE_LATENCY
803 #define PA_SOURCE_HARDWARE PA_SOURCE_HARDWARE
804 #define PA_SOURCE_NETWORK PA_SOURCE_NETWORK
805 #define PA_SOURCE_HW_MUTE_CTRL PA_SOURCE_HW_MUTE_CTRL
806 #define PA_SOURCE_DECIBEL_VOLUME PA_SOURCE_DECIBEL_VOLUME
807 #define PA_SOURCE_DYNAMIC_LATENCY PA_SOURCE_DYNAMIC_LATENCY
808 /** \endcond */
809
810 /** Source state. \since 0.9.15 */
811 typedef enum pa_source_state {
812     PA_SOURCE_INVALID_STATE = -1,
813     /**< This state is used when the server does not support source state introspection \since 0.9.15 */
814
815     PA_SOURCE_RUNNING = 0,
816     /**< Running, source is recording and used by at least one non-corked source-output \since 0.9.15 */
817
818     PA_SOURCE_IDLE = 1,
819     /**< When idle, the source is still recording but there is no non-corked source-output \since 0.9.15 */
820
821     PA_SOURCE_SUSPENDED = 2,
822     /**< When suspended, actual source access can be closed, for instance \since 0.9.15 */
823
824 /** \cond fulldocs */
825     /* PRIVATE: Server-side values -- DO NOT USE THIS ON THE CLIENT
826      * SIDE! These values are *not* considered part of the official PA
827      * API/ABI. If you use them your application might break when PA
828      * is upgraded. Also, please note that these values are not useful
829      * on the client side anyway. */
830
831     PA_SOURCE_INIT = -2,
832     /**< Initialization state */
833
834     PA_SOURCE_UNLINKED = -3
835     /**< The state when the source is getting unregistered and removed from client access */
836 /** \endcond */
837
838 } pa_source_state_t;
839
840 /** Returns non-zero if source is recording: running or idle. \since 0.9.15 */
841 static inline int PA_SOURCE_IS_OPENED(pa_source_state_t x) {
842     return x == PA_SOURCE_RUNNING || x == PA_SOURCE_IDLE;
843 }
844
845 /** \cond fulldocs */
846 #define PA_SOURCE_INVALID_STATE PA_SOURCE_INVALID_STATE
847 #define PA_SOURCE_RUNNING PA_SOURCE_RUNNING
848 #define PA_SOURCE_IDLE PA_SOURCE_IDLE
849 #define PA_SOURCE_SUSPENDED PA_SOURCE_SUSPENDED
850 #define PA_SOURCE_INIT PA_SOURCE_INIT
851 #define PA_SOURCE_UNLINKED PA_SOURCE_UNLINKED
852 #define PA_SOURCE_IS_OPENED PA_SOURCE_IS_OPENED
853 /** \endcond */
854
855 /** A generic free() like callback prototype */
856 typedef void (*pa_free_cb_t)(void *p);
857
858 /** A stream policy/meta event requesting that an application should
859  * cork a specific stream. See pa_stream_event_cb_t for more
860  * information, \since 0.9.15 */
861 #define PA_STREAM_EVENT_REQUEST_CORK "request-cork"
862
863 /** A stream policy/meta event requesting that an application should
864  * cork a specific stream. See pa_stream_event_cb_t for more
865  * information, \since 0.9.15 */
866 #define PA_STREAM_EVENT_REQUEST_UNCORK "request-uncork"
867
868 PA_C_DECL_END
869
870 #endif