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