1 #ifndef foodefhfoo 2 #define foodefhfoo 3 4 /* $Id: def.h 2067 2007-11-21 01:30:40Z lennart $ */ 5 6 /*** 7 This file is part of PulseAudio. 8 9 Copyright 2004-2006 Lennart Poettering 10 Copyright 2006 Pierre Ossman <ossman (at) cendio.se> for Cendio AB 11 12 PulseAudio is free software; you can redistribute it and/or modify 13 it under the terms of the GNU Lesser General Public License as 14 published by the Free Software Foundation; either version 2.1 of the 15 License, or (at your option) any later version. 16 17 PulseAudio is distributed in the hope that it will be useful, but 18 WITHOUT ANY WARRANTY; without even the implied warranty of 19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 20 Lesser General Public License for more details. 21 22 You should have received a copy of the GNU Lesser General Public 23 License along with PulseAudio; if not, write to the Free Software 24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 25 USA. 26 ***/ 27 28 #include <inttypes.h> 29 #include <sys/time.h> 30 #include <time.h> 31 32 #include <pulse/cdecl.h> 33 #include <pulse/sample.h> 34 35 /** \file 36 * Global definitions */ 37 38 PA_C_DECL_BEGIN 39 40 /** The state of a connection context */ 41 typedef enum pa_context_state { 42 PA_CONTEXT_UNCONNECTED, /**< The context hasn't been connected yet */ 43 PA_CONTEXT_CONNECTING, /**< A connection is being established */ 44 PA_CONTEXT_AUTHORIZING, /**< The client is authorizing itself to the daemon */ 45 PA_CONTEXT_SETTING_NAME, /**< The client is passing its application name to the daemon */ 46 PA_CONTEXT_READY, /**< The connection is established, the context is ready to execute operations */ 47 PA_CONTEXT_FAILED, /**< The connection failed or was disconnected */ 48 PA_CONTEXT_TERMINATED /**< The connection was terminated cleanly */ 49 } pa_context_state_t; 50 51 /** The state of a stream */ 52 typedef enum pa_stream_state { 53 PA_STREAM_UNCONNECTED, /**< The stream is not yet connected to any sink or source */ 54 PA_STREAM_CREATING, /**< The stream is being created */ 55 PA_STREAM_READY, /**< The stream is established, you may pass audio data to it now */ 56 PA_STREAM_FAILED, /**< An error occured that made the stream invalid */ 57 PA_STREAM_TERMINATED /**< The stream has been terminated cleanly */ 58 } pa_stream_state_t; 59 60 /** The state of an operation */ 61 typedef enum pa_operation_state { 62 PA_OPERATION_RUNNING, /**< The operation is still running */ 63 PA_OPERATION_DONE, /**< The operation has been completed */ 64 PA_OPERATION_CANCELED /**< The operation has been canceled */ 65 } pa_operation_state_t; 66 67 /** An invalid index */ 68 #define PA_INVALID_INDEX ((uint32_t) -1) 69 70 /** Some special flags for contexts. \since 0.8 */ 71 typedef enum pa_context_flags { 72 PA_CONTEXT_NOAUTOSPAWN = 1 /**< Disabled autospawning of the PulseAudio daemon if required */ 73 } pa_context_flags_t; 74 75 /** The direction of a pa_stream object */ 76 typedef enum pa_stream_direction { 77 PA_STREAM_NODIRECTION, /**< Invalid direction */ 78 PA_STREAM_PLAYBACK, /**< Playback stream */ 79 PA_STREAM_RECORD, /**< Record stream */ 80 PA_STREAM_UPLOAD /**< Sample upload stream */ 81 } pa_stream_direction_t; 82 83 /** Some special flags for stream connections. \since 0.6 */ 84 typedef enum pa_stream_flags { 85 PA_STREAM_START_CORKED = 1, /**< Create the stream corked, requiring an explicit pa_stream_cork() call to uncork it. */ 86 PA_STREAM_INTERPOLATE_TIMING = 2, /**< Interpolate the latency for 87 * this stream. When enabled, 88 * pa_stream_get_latency() and 89 * pa_stream_get_time() will try 90 * to estimate the current 91 * record/playback time based on 92 * the local time that passed 93 * since the last timing info 94 * update. Using this option 95 * has the advantage of not 96 * requiring a whole roundtrip 97 * when the current 98 * playback/recording time is 99 * needed. Consider using this 100 * option when requesting 101 * latency information 102 * frequently. This is 103 * especially useful on long 104 * latency network 105 * connections. It makes a lot 106 * of sense to combine this 107 * option with 108 * PA_STREAM_AUTO_TIMING_UPDATE. */ 109 PA_STREAM_NOT_MONOTONOUS = 4, /**< Don't force the time to 110 * increase monotonically. If 111 * this option is enabled, 112 * pa_stream_get_time() will not 113 * necessarily return always 114 * monotonically increasing time 115 * values on each call. This may 116 * confuse applications which 117 * cannot deal with time going 118 * 'backwards', but has the 119 * advantage that bad transport 120 * latency estimations that 121 * caused the time to to jump 122 * ahead can be corrected 123 * quickly, without the need to 124 * wait. */ 125 PA_STREAM_AUTO_TIMING_UPDATE = 8, /**< If set timing update requests 126 * are issued periodically 127 * automatically. Combined with 128 * PA_STREAM_INTERPOLATE_TIMING 129 * you will be able to query the 130 * current time and latency with 131 * pa_stream_get_time() and 132 * pa_stream_get_latency() at 133 * all times without a packet 134 * round trip.*/ 135 PA_STREAM_NO_REMAP_CHANNELS = 16, /**< Don't remap channels by 136 * their name, instead map them 137 * simply by their 138 * index. Implies 139 * PA_STREAM_NO_REMIX_CHANNELS. Only 140 * supported when the server is 141 * at least PA 0.9.8. It is 142 * ignored on older 143 * servers.\since 0.9.8 */ 144 PA_STREAM_NO_REMIX_CHANNELS = 32, /**< When remapping channels by 145 * name, don't upmix or downmix 146 * them to related 147 * channels. Copy them into 148 * matching channels of the 149 * device 1:1. Only supported 150 * when the server is at least 151 * PA 0.9.8. It is ignored on 152 * older servers. \since 153 * 0.9.8 */ 154 PA_STREAM_FIX_FORMAT = 64, /**< Use the sample format of the 155 * sink/device this stream is being 156 * connected to, and possibly ignore 157 * the format the sample spec contains 158 * -- but you still have to pass a 159 * valid value in it as a hint to 160 * PulseAudio what would suit your 161 * stream best. If this is used you 162 * should query the used sample format 163 * after creating the stream by using 164 * pa_stream_get_sample_spec(). Also, 165 * if you specified manual buffer 166 * metrics it is recommended to update 167 * them with 168 * pa_stream_set_buffer_attr() to 169 * compensate for the changed frame 170 * sizes. Only supported when the 171 * server is at least PA 0.9.8. It is 172 * ignored on older servers. \since 173 * 0.9.8 */ 174 175 PA_STREAM_FIX_RATE = 128, /**< Use the sample rate of the sink, 176 * and possibly ignore the rate the 177 * sample spec contains. Usage similar 178 * to PA_STREAM_FIX_FORMAT.Only 179 * supported when the server is at least 180 * PA 0.9.8. It is ignored on older 181 * servers. \since 0.9.8 */ 182 183 PA_STREAM_FIX_CHANNELS = 256, /**< Use the number of channels and 184 * the channel map of the sink, and 185 * possibly ignore the number of 186 * channels and the map the sample spec 187 * and the passed channel map 188 * contains. Usage similar to 189 * PA_STREAM_FIX_FORMAT. Only supported 190 * when the server is at least PA 191 * 0.9.8. It is ignored on older 192 * servers. \since 0.9.8 */ 193 PA_STREAM_DONT_MOVE = 512, /**< Don't allow moving of this stream to 194 * another sink/device. Useful if you use 195 * any of the PA_STREAM_FIX_ flags and 196 * want to make sure that resampling 197 * never takes place -- which might 198 * happen if the stream is moved to 199 * another sink/source whith a different 200 * sample spec/channel map. Only 201 * supported when the server is at least 202 * PA 0.9.8. It is ignored on older 203 * servers. \since 0.9.8 */ 204 PA_STREAM_VARIABLE_RATE = 1024, /**< Allow dynamic changing of the 205 * sampling rate during playback 206 * with 207 * pa_stream_update_sample_rate(). Only 208 * supported when the server is at 209 * least PA 0.9.8. It is ignored 210 * on older servers. \since 211 * 0.9.8 */ 212 } pa_stream_flags_t; 213 214 /** Playback and record buffer metrics */ 215 typedef struct pa_buffer_attr { 216 uint32_t maxlength; /**< Maximum length of the buffer */ 217 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 */ 218 uint32_t prebuf; /**< Playback only: pre-buffering. The server does not start with playback before at least prebug bytes are available in the buffer */ 219 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 */ 220 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. */ 221 } pa_buffer_attr; 222 223 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */ 224 enum { 225 PA_OK = 0, /**< No error */ 226 PA_ERR_ACCESS, /**< Access failure */ 227 PA_ERR_COMMAND, /**< Unknown command */ 228 PA_ERR_INVALID, /**< Invalid argument */ 229 PA_ERR_EXIST, /**< Entity exists */ 230 PA_ERR_NOENTITY, /**< No such entity */ 231 PA_ERR_CONNECTIONREFUSED, /**< Connection refused */ 232 PA_ERR_PROTOCOL, /**< Protocol error */ 233 PA_ERR_TIMEOUT, /**< Timeout */ 234 PA_ERR_AUTHKEY, /**< No authorization key */ 235 PA_ERR_INTERNAL, /**< Internal error */ 236 PA_ERR_CONNECTIONTERMINATED, /**< Connection terminated */ 237 PA_ERR_KILLED, /**< Entity killed */ 238 PA_ERR_INVALIDSERVER, /**< Invalid server */ 239 PA_ERR_MODINITFAILED, /**< Module initialization failed */ 240 PA_ERR_BADSTATE, /**< Bad state */ 241 PA_ERR_NODATA, /**< No data */ 242 PA_ERR_VERSION, /**< Incompatible protocol version \since 0.8 */ 243 PA_ERR_TOOLARGE, /**< Data too large \since 0.8.1 */ 244 PA_ERR_NOTSUPPORTED, /**< Operation not supported \since 0.9.5 */ 245 PA_ERR_MAX /**< Not really an error but the first invalid error code */ 246 }; 247 248 /** Subscription event mask, as used by pa_context_subscribe() */ 249 typedef enum pa_subscription_mask { 250 PA_SUBSCRIPTION_MASK_NULL = 0, /**< No events */ 251 PA_SUBSCRIPTION_MASK_SINK = 1, /**< Sink events */ 252 PA_SUBSCRIPTION_MASK_SOURCE = 2, /**< Source events */ 253 PA_SUBSCRIPTION_MASK_SINK_INPUT = 4, /**< Sink input events */ 254 PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 8, /**< Source output events */ 255 PA_SUBSCRIPTION_MASK_MODULE = 16, /**< Module events */ 256 PA_SUBSCRIPTION_MASK_CLIENT = 32, /**< Client events */ 257 PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64, /**< Sample cache events */ 258 PA_SUBSCRIPTION_MASK_SERVER = 128, /**< Other global server changes. \since 0.4 */ 259 PA_SUBSCRIPTION_MASK_AUTOLOAD = 256, /**< Autoload table events. \since 0.5 */ 260 PA_SUBSCRIPTION_MASK_ALL = 511 /**< Catch all events \since 0.8 */ 261 } pa_subscription_mask_t; 262 263 /** Subscription event types, as used by pa_context_subscribe() */ 264 typedef enum pa_subscription_event_type { 265 PA_SUBSCRIPTION_EVENT_SINK = 0, /**< Event type: Sink */ 266 PA_SUBSCRIPTION_EVENT_SOURCE = 1, /**< Event type: Source */ 267 PA_SUBSCRIPTION_EVENT_SINK_INPUT = 2, /**< Event type: Sink input */ 268 PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 3, /**< Event type: Source output */ 269 PA_SUBSCRIPTION_EVENT_MODULE = 4, /**< Event type: Module */ 270 PA_SUBSCRIPTION_EVENT_CLIENT = 5, /**< Event type: Client */ 271 PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6, /**< Event type: Sample cache item */ 272 PA_SUBSCRIPTION_EVENT_SERVER = 7, /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. \since 0.4 */ 273 PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8, /**< Event type: Autoload table changes. \since 0.5 */ 274 PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */ 275 276 PA_SUBSCRIPTION_EVENT_NEW = 0, /**< A new object was created */ 277 PA_SUBSCRIPTION_EVENT_CHANGE = 16, /**< A property of the object was modified */ 278 PA_SUBSCRIPTION_EVENT_REMOVE = 32, /**< An object was removed */ 279 PA_SUBSCRIPTION_EVENT_TYPE_MASK = 16+32 /**< A mask to extract the event operation from an event value */ 280 } pa_subscription_event_type_t; 281 282 /** Return one if an event type t matches an event mask bitfield */ 283 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK)))) 284 285 /** A structure for all kinds of timing information of a stream. See 286 * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The 287 * total output latency a sample that is written with 288 * pa_stream_write() takes to be played may be estimated by 289 * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined 290 * as pa_bytes_to_usec(write_index-read_index)) The output buffer 291 * which buffer_usec relates to may be manipulated freely (with 292 * pa_stream_write()'s seek argument, pa_stream_flush() and friends), 293 * the buffers sink_usec and source_usec relate to are first-in 294 * first-out (FIFO) buffers which cannot be flushed or manipulated in 295 * any way. The total input latency a sample that is recorded takes to 296 * be delivered to the application is: 297 * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of 298 * sign issues!) When connected to a monitor source sink_usec contains 299 * the latency of the owning sink. The two latency estimations 300 * described here are implemented in pa_stream_get_latency().*/ 301 typedef struct pa_timing_info { 302 struct timeval timestamp; /**< The time when this timing info structure was current */ 303 int synchronized_clocks; /**< Non-zero if the local and the 304 * remote machine have synchronized 305 * clocks. If synchronized clocks are 306 * detected transport_usec becomes much 307 * more reliable. However, the code that 308 * detects synchronized clocks is very 309 * limited und unreliable itself. \since 310 * 0.5 */ 311 312 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. */ 313 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*/ 314 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 */ 315 316 int playing; /**< Non-zero when the stream is currently playing. Only for playback streams. */ 317 318 int write_index_corrupt; /**< Non-zero if write_index is not 319 * up-to-date because a local write 320 * command that corrupted it has been 321 * issued in the time since this latency 322 * info was current . Only write 323 * commands with SEEK_RELATIVE_ON_READ 324 * and SEEK_RELATIVE_END can corrupt 325 * write_index. \since 0.8 */ 326 int64_t write_index; /**< Current write index into the 327 * playback buffer in bytes. Think twice before 328 * using this for seeking purposes: it 329 * might be out of date a the time you 330 * want to use it. Consider using 331 * PA_SEEK_RELATIVE instead. \since 332 * 0.8 */ 333 334 int read_index_corrupt; /**< Non-zero if read_index is not 335 * up-to-date because a local pause or 336 * flush request that corrupted it has 337 * been issued in the time since this 338 * latency info was current. \since 0.8 */ 339 340 int64_t read_index; /**< Current read index into the 341 * playback buffer in bytes. Think twice before 342 * using this for seeking purposes: it 343 * might be out of date a the time you 344 * want to use it. Consider using 345 * PA_SEEK_RELATIVE_ON_READ 346 * instead. \since 0.8 */ 347 } pa_timing_info; 348 349 /** A structure for the spawn api. This may be used to integrate auto 350 * spawned daemons into your application. For more information see 351 * pa_context_connect(). When spawning a new child process the 352 * waitpid() is used on the child's PID. The spawn routine will not 353 * block or ignore SIGCHLD signals, since this cannot be done in a 354 * thread compatible way. You might have to do this in 355 * prefork/postfork. \since 0.4 */ 356 typedef struct pa_spawn_api { 357 void (*prefork)(void); /**< Is called just before the fork in the parent process. May be NULL. */ 358 void (*postfork)(void); /**< Is called immediately after the fork in the parent process. May be NULL.*/ 359 void (*atfork)(void); /**< Is called immediately after the 360 * fork in the child process. May be 361 * NULL. It is not safe to close all 362 * file descriptors in this function 363 * unconditionally, since a UNIX socket 364 * (created using socketpair()) is 365 * passed to the new process. */ 366 } pa_spawn_api; 367 368 /** Seek type for pa_stream_write(). \since 0.8*/ 369 typedef enum pa_seek_mode { 370 PA_SEEK_RELATIVE = 0, /**< Seek relatively to the write index */ 371 PA_SEEK_ABSOLUTE = 1, /**< Seek relatively to the start of the buffer queue */ 372 PA_SEEK_RELATIVE_ON_READ = 2, /**< Seek relatively to the read index. */ 373 PA_SEEK_RELATIVE_END = 3 /**< Seek relatively to the current end of the buffer queue. */ 374 } pa_seek_mode_t; 375 376 /** Special sink flags. \since 0.8 */ 377 typedef enum pa_sink_flags { 378 PA_SINK_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */ 379 PA_SINK_LATENCY = 2, /**< Supports latency querying */ 380 PA_SINK_HARDWARE = 4, /**< Is a hardware sink of some kind, in contrast to "virtual"/software sinks \since 0.9.3 */ 381 PA_SINK_NETWORK = 8 /**< Is a networked sink of some kind. \since 0.9.7 */ 382 } pa_sink_flags_t; 383 384 /** Special source flags. \since 0.8 */ 385 typedef enum pa_source_flags { 386 PA_SOURCE_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */ 387 PA_SOURCE_LATENCY = 2, /**< Supports latency querying */ 388 PA_SOURCE_HARDWARE = 4, /**< Is a hardware source of some kind, in contrast to "virtual"/software source \since 0.9.3 */ 389 PA_SOURCE_NETWORK = 8 /**< Is a networked sink of some kind. \since 0.9.7 */ 390 } pa_source_flags_t; 391 392 /** A generic free() like callback prototype */ 393 typedef void (*pa_free_cb_t)(void *p); 394 395 PA_C_DECL_END 396 397 #endif 398
