4
/* $Id: def.h 1179 2006-08-01 21:04:43Z lennart $ */
7
This file is part of PulseAudio.
9
PulseAudio is free software; you can redistribute it and/or modify
10
it under the terms of the GNU Lesser General Public License as
11
published by the Free Software Foundation; either version 2.1 of the
12
License, or (at your option) any later version.
14
PulseAudio is distributed in the hope that it will be useful, but
15
WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
Lesser General Public License for more details.
19
You should have received a copy of the GNU Lesser General Public
20
License along with PulseAudio; if not, write to the Free Software
21
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
29
#include <pulse/cdecl.h>
30
#include <pulse/sample.h>
33
* Global definitions */
37
/** The state of a connection context */
38
typedef enum pa_context_state {
39
PA_CONTEXT_UNCONNECTED, /**< The context hasn't been connected yet */
40
PA_CONTEXT_CONNECTING, /**< A connection is being established */
41
PA_CONTEXT_AUTHORIZING, /**< The client is authorizing itself to the daemon */
42
PA_CONTEXT_SETTING_NAME, /**< The client is passing its application name to the daemon */
43
PA_CONTEXT_READY, /**< The connection is established, the context is ready to execute operations */
44
PA_CONTEXT_FAILED, /**< The connection failed or was disconnected */
45
PA_CONTEXT_TERMINATED /**< The connection was terminated cleanly */
48
/** The state of a stream */
49
typedef enum pa_stream_state {
50
PA_STREAM_UNCONNECTED, /**< The stream is not yet connected to any sink or source */
51
PA_STREAM_CREATING, /**< The stream is being created */
52
PA_STREAM_READY, /**< The stream is established, you may pass audio data to it now */
53
PA_STREAM_FAILED, /**< An error occured that made the stream invalid */
54
PA_STREAM_TERMINATED /**< The stream has been terminated cleanly */
57
/** The state of an operation */
58
typedef enum pa_operation_state {
59
PA_OPERATION_RUNNING, /**< The operation is still running */
60
PA_OPERATION_DONE, /**< The operation has been completed */
61
PA_OPERATION_CANCELED /**< The operation has been canceled */
62
} pa_operation_state_t;
64
/** An invalid index */
65
#define PA_INVALID_INDEX ((uint32_t) -1)
67
/** Some special flags for contexts. \since 0.8 */
68
typedef enum pa_context_flags {
69
PA_CONTEXT_NOAUTOSPAWN = 1 /**< Disabled autospawning of the PulseAudio daemon if required */
72
/** The direction of a pa_stream object */
73
typedef enum pa_stream_direction {
74
PA_STREAM_NODIRECTION, /**< Invalid direction */
75
PA_STREAM_PLAYBACK, /**< Playback stream */
76
PA_STREAM_RECORD, /**< Record stream */
77
PA_STREAM_UPLOAD /**< Sample upload stream */
78
} pa_stream_direction_t;
80
/** Some special flags for stream connections. \since 0.6 */
81
typedef enum pa_stream_flags {
82
PA_STREAM_START_CORKED = 1, /**< Create the stream corked, requiring an explicit pa_stream_cork() call to uncork it. */
83
PA_STREAM_INTERPOLATE_TIMING = 2, /**< Interpolate the latency for
84
* this stream. When enabled,
85
* pa_stream_get_latency() and
86
* pa_stream_get_time() will try
87
* to estimate the current
88
* record/playback time based on
89
* the local time that passed
90
* since the last timing info
91
* update. Using this option
92
* has the advantage of not
93
* requiring a whole roundtrip
95
* playback/recording time is
96
* needed. Consider using this
97
* option when requesting
100
* especially useful on long
102
* connections. It makes a lot
103
* of sense to combine this
105
* PA_STREAM_AUTO_TIMING_UPDATE. */
106
PA_STREAM_NOT_MONOTONOUS = 4, /**< Don't force the time to
107
* increase monotonically. If
108
* this option is enabled,
109
* pa_stream_get_time() will not
110
* necessarily return always
111
* monotonically increasing time
112
* values on each call. This may
113
* confuse applications which
114
* cannot deal with time going
115
* 'backwards', but has the
116
* advantage that bad transport
117
* latency estimations that
118
* caused the time to to jump
119
* ahead can be corrected
120
* quickly, without the need to
122
PA_STREAM_AUTO_TIMING_UPDATE = 8 /**< If set timing update requests
123
* are issued periodically
124
* automatically. Combined with
125
* PA_STREAM_INTERPOLATE_TIMING
126
* you will be able to query the
127
* current time and latency with
128
* pa_stream_get_time() and
129
* pa_stream_get_latency() at
130
* all times without a packet
134
/** Playback and record buffer metrics */
135
typedef struct pa_buffer_attr {
136
uint32_t maxlength; /**< Maximum length of the buffer */
137
uint32_t tlength; /**< Playback only: target length of the buffer. The server tries to assure that at least tlength bytes are always available in the buffer */
138
uint32_t prebuf; /**< Playback only: pre-buffering. The server does not start with playback before at least prebug bytes are available in the buffer */
139
uint32_t minreq; /**< Playback only: minimum request. The server does not request less than minreq bytes from the client, instead waints until the buffer is free enough to request more bytes at once */
140
uint32_t fragsize; /**< Recording only: fragment size. The server sends data in blocks of fragsize bytes size. Large values deminish interactivity with other operations on the connection context but decrease control overhead. */
143
/** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
145
PA_OK = 0, /**< No error */
146
PA_ERR_ACCESS, /**< Access failure */
147
PA_ERR_COMMAND, /**< Unknown command */
148
PA_ERR_INVALID, /**< Invalid argument */
149
PA_ERR_EXIST, /**< Entity exists */
150
PA_ERR_NOENTITY, /**< No such entity */
151
PA_ERR_CONNECTIONREFUSED, /**< Connection refused */
152
PA_ERR_PROTOCOL, /**< Protocol error */
153
PA_ERR_TIMEOUT, /**< Timeout */
154
PA_ERR_AUTHKEY, /**< No authorization key */
155
PA_ERR_INTERNAL, /**< Internal error */
156
PA_ERR_CONNECTIONTERMINATED, /**< Connection terminated */
157
PA_ERR_KILLED, /**< Entity killed */
158
PA_ERR_INVALIDSERVER, /**< Invalid server */
159
PA_ERR_MODINITFAILED, /**< Module initialization failed */
160
PA_ERR_BADSTATE, /**< Bad state */
161
PA_ERR_NODATA, /**< No data */
162
PA_ERR_VERSION, /**< Incompatible protocol version \since 0.8 */
163
PA_ERR_TOOLARGE, /**< Data too large \since 0.8.1 */
164
PA_ERR_NOTSUPPORTED, /**< Operation not supported \since 0.9.5 */
165
PA_ERR_MAX /**< Not really an error but the first invalid error code */
168
/** Subscription event mask, as used by pa_context_subscribe() */
169
typedef enum pa_subscription_mask {
170
PA_SUBSCRIPTION_MASK_NULL = 0, /**< No events */
171
PA_SUBSCRIPTION_MASK_SINK = 1, /**< Sink events */
172
PA_SUBSCRIPTION_MASK_SOURCE = 2, /**< Source events */
173
PA_SUBSCRIPTION_MASK_SINK_INPUT = 4, /**< Sink input events */
174
PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 8, /**< Source output events */
175
PA_SUBSCRIPTION_MASK_MODULE = 16, /**< Module events */
176
PA_SUBSCRIPTION_MASK_CLIENT = 32, /**< Client events */
177
PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64, /**< Sample cache events */
178
PA_SUBSCRIPTION_MASK_SERVER = 128, /**< Other global server changes. \since 0.4 */
179
PA_SUBSCRIPTION_MASK_AUTOLOAD = 256, /**< Autoload table events. \since 0.5 */
180
PA_SUBSCRIPTION_MASK_ALL = 511 /**< Catch all events \since 0.8 */
181
} pa_subscription_mask_t;
183
/** Subscription event types, as used by pa_context_subscribe() */
184
typedef enum pa_subscription_event_type {
185
PA_SUBSCRIPTION_EVENT_SINK = 0, /**< Event type: Sink */
186
PA_SUBSCRIPTION_EVENT_SOURCE = 1, /**< Event type: Source */
187
PA_SUBSCRIPTION_EVENT_SINK_INPUT = 2, /**< Event type: Sink input */
188
PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 3, /**< Event type: Source output */
189
PA_SUBSCRIPTION_EVENT_MODULE = 4, /**< Event type: Module */
190
PA_SUBSCRIPTION_EVENT_CLIENT = 5, /**< Event type: Client */
191
PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6, /**< Event type: Sample cache item */
192
PA_SUBSCRIPTION_EVENT_SERVER = 7, /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. \since 0.4 */
193
PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8, /**< Event type: Autoload table changes. \since 0.5 */
194
PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */
196
PA_SUBSCRIPTION_EVENT_NEW = 0, /**< A new object was created */
197
PA_SUBSCRIPTION_EVENT_CHANGE = 16, /**< A property of the object was modified */
198
PA_SUBSCRIPTION_EVENT_REMOVE = 32, /**< An object was removed */
199
PA_SUBSCRIPTION_EVENT_TYPE_MASK = 16+32 /**< A mask to extract the event operation from an event value */
200
} pa_subscription_event_type_t;
202
/** Return one if an event type t matches an event mask bitfield */
203
#define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
205
/** A structure for all kinds of timing information of a stream. See
206
* pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
207
* total output latency a sample that is written with
208
* pa_stream_write() takes to be played may be estimated by
209
* sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
210
* as pa_bytes_to_usec(write_index-read_index)) The output buffer
211
* which buffer_usec relates to may be manipulated freely (with
212
* pa_stream_write()'s seek argument, pa_stream_flush() and friends),
213
* the buffers sink_usec and source_usec relate to are first-in
214
* first-out (FIFO) buffers which cannot be flushed or manipulated in
215
* any way. The total input latency a sample that is recorded takes to
216
* be delivered to the application is:
217
* source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
218
* sign issues!) When connected to a monitor source sink_usec contains
219
* the latency of the owning sink. The two latency estimations
220
* described here are implemented in pa_stream_get_latency().*/
221
typedef struct pa_timing_info {
222
struct timeval timestamp; /**< The time when this timing info structure was current */
223
int synchronized_clocks; /**< Non-zero if the local and the
224
* remote machine have synchronized
225
* clocks. If synchronized clocks are
226
* detected transport_usec becomes much
227
* more reliable. However, the code that
228
* detects synchronized clocks is very
229
* limited und unreliable itself. \since
232
pa_usec_t sink_usec; /**< Time in usecs a sample takes to be played on the sink. For playback streams and record streams connected to a monitor source. */
233
pa_usec_t source_usec; /**< Time in usecs a sample takes from being recorded to being delivered to the application. Only for record streams. \since 0.5*/
234
pa_usec_t transport_usec; /**< Estimated time in usecs a sample takes to be transferred to/from the daemon. For both playback and record streams. \since 0.5 */
236
int playing; /**< Non-zero when the stream is currently playing. Only for playback streams. */
238
int write_index_corrupt; /**< Non-zero if write_index is not
239
* up-to-date because a local write
240
* command that corrupted it has been
241
* issued in the time since this latency
242
* info was current . Only write
243
* commands with SEEK_RELATIVE_ON_READ
244
* and SEEK_RELATIVE_END can corrupt
245
* write_index. \since 0.8 */
246
int64_t write_index; /**< Current write index into the
247
* playback buffer in bytes. Think twice before
248
* using this for seeking purposes: it
249
* might be out of date a the time you
250
* want to use it. Consider using
251
* PA_SEEK_RELATIVE instead. \since
254
int read_index_corrupt; /**< Non-zero if read_index is not
255
* up-to-date because a local pause or
256
* flush request that corrupted it has
257
* been issued in the time since this
258
* latency info was current. \since 0.8 */
260
int64_t read_index; /**< Current read index into the
261
* playback buffer in bytes. Think twice before
262
* using this for seeking purposes: it
263
* might be out of date a the time you
264
* want to use it. Consider using
265
* PA_SEEK_RELATIVE_ON_READ
266
* instead. \since 0.8 */
269
/** A structure for the spawn api. This may be used to integrate auto
270
* spawned daemons into your application. For more information see
271
* pa_context_connect(). When spawning a new child process the
272
* waitpid() is used on the child's PID. The spawn routine will not
273
* block or ignore SIGCHLD signals, since this cannot be done in a
274
* thread compatible way. You might have to do this in
275
* prefork/postfork. \since 0.4 */
276
typedef struct pa_spawn_api {
277
void (*prefork)(void); /**< Is called just before the fork in the parent process. May be NULL. */
278
void (*postfork)(void); /**< Is called immediately after the fork in the parent process. May be NULL.*/
279
void (*atfork)(void); /**< Is called immediately after the
280
* fork in the child process. May be
281
* NULL. It is not safe to close all
282
* file descriptors in this function
283
* unconditionally, since a UNIX socket
284
* (created using socketpair()) is
285
* passed to the new process. */
288
/** Seek type for pa_stream_write(). \since 0.8*/
289
typedef enum pa_seek_mode {
290
PA_SEEK_RELATIVE = 0, /**< Seek relatively to the write index */
291
PA_SEEK_ABSOLUTE = 1, /**< Seek relatively to the start of the buffer queue */
292
PA_SEEK_RELATIVE_ON_READ = 2, /**< Seek relatively to the read index. */
293
PA_SEEK_RELATIVE_END = 3 /**< Seek relatively to the current end of the buffer queue. */
296
/** Special sink flags. \since 0.8 */
297
typedef enum pa_sink_flags {
298
PA_SINK_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */
299
PA_SINK_LATENCY = 2, /**< Supports latency querying */
300
PA_SINK_HARDWARE = 4 /**< Is a hardware sink of some kind, in contrast to "virtual"/software sinks \since 0.9.3 */
303
/** Special source flags. \since 0.8 */
304
typedef enum pa_source_flags {
305
PA_SOURCE_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */
306
PA_SOURCE_LATENCY = 2, /**< Supports latency querying */
307
PA_SOURCE_HARDWARE = 4 /**< Is a hardware source of some kind, in contrast to "virtual"/software source \since 0.9.3 */
310
/** A generic free() like callback prototype */
311
typedef void (*pa_free_cb_t)(void *p);
added
removed
src/pulse/def.h
