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 (at) 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_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 } pa_stream_flags_t; 285 286 /** \cond fulldocs */ 287 288 /* English is an evil language */ 289 #define PA_STREAM_NOT_MONOTONOUS PA_STREAM_NOT_MONOTONIC 290 291 /* Allow clients to check with #ifdef for those flags */ 292 #define PA_STREAM_START_CORKED PA_STREAM_START_CORKED 293 #define PA_STREAM_INTERPOLATE_TIMING PA_STREAM_INTERPOLATE_TIMING 294 #define PA_STREAM_NOT_MONOTONIC PA_STREAM_NOT_MONOTONIC 295 #define PA_STREAM_AUTO_TIMING_UPDATE PA_STREAM_AUTO_TIMING_UPDATE 296 #define PA_STREAM_NO_REMAP_CHANNELS PA_STREAM_NO_REMAP_CHANNELS 297 #define PA_STREAM_NO_REMIX_CHANNELS PA_STREAM_NO_REMIX_CHANNELS 298 #define PA_STREAM_FIX_FORMAT PA_STREAM_FIX_FORMAT 299 #define PA_STREAM_FIX_RATE PA_STREAM_FIX_RATE 300 #define PA_STREAM_FIX_CHANNELS PA_STREAM_FIX_CHANNELS 301 #define PA_STREAM_DONT_MOVE PA_STREAM_DONT_MOVE 302 #define PA_STREAM_VARIABLE_RATE PA_STREAM_VARIABLE_RATE 303 #define PA_STREAM_PEAK_DETECT PA_STREAM_PEAK_DETECT 304 #define PA_STREAM_START_MUTED PA_STREAM_START_MUTED 305 #define PA_STREAM_ADJUST_LATENCY PA_STREAM_ADJUST_LATENCY 306 #define PA_STREAM_EARLY_REQUESTS PA_STREAM_EARLY_REQUESTS 307 #define PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND 308 #define PA_STREAM_START_UNMUTED PA_STREAM_START_UNMUTED 309 #define PA_STREAM_FAIL_ON_SUSPEND PA_STREAM_FAIL_ON_SUSPEND 310 311 /** \endcond */ 312 313 /** Playback and record buffer metrics */ 314 typedef struct pa_buffer_attr { 315 uint32_t maxlength; 316 /**< Maximum length of the buffer. Setting this to (uint32_t) -1 317 * will initialize this to the maximum value supported by server, 318 * which is recommended. */ 319 320 uint32_t tlength; 321 /**< Playback only: target length of the buffer. The server tries 322 * to assure that at least tlength bytes are always available in 323 * the per-stream server-side playback buffer. It is recommended 324 * to set this to (uint32_t) -1, which will initialize this to a 325 * value that is deemed sensible by the server. However, this 326 * value will default to something like 2s, i.e. for applications 327 * that have specific latency requirements this value should be 328 * set to the maximum latency that the application can deal 329 * with. When PA_STREAM_ADJUST_LATENCY is not set this value will 330 * influence only the per-stream playback buffer size. When 331 * PA_STREAM_ADJUST_LATENCY is set the overall latency of the sink 332 * plus the playback buffer size is configured to this value. Set 333 * PA_STREAM_ADJUST_LATENCY if you are interested in adjusting the 334 * overall latency. Don't set it if you are interested in 335 * configuring the server-side per-stream playback buffer 336 * size. */ 337 338 uint32_t prebuf; 339 /**< Playback only: pre-buffering. The server does not start with 340 * playback before at least prebuf bytes are available in the 341 * buffer. It is recommended to set this to (uint32_t) -1, which 342 * will initialize this to the same value as tlength, whatever 343 * that may be. Initialize to 0 to enable manual start/stop 344 * control of the stream. This means that playback will not stop 345 * on underrun and playback will not start automatically. Instead 346 * pa_stream_corked() needs to be called explicitly. If you set 347 * this value to 0 you should also set PA_STREAM_START_CORKED. */ 348 349 uint32_t minreq; 350 /**< Playback only: minimum request. The server does not request 351 * less than minreq bytes from the client, instead waits until the 352 * buffer is free enough to request more bytes at once. It is 353 * recommended to set this to (uint32_t) -1, which will initialize 354 * this to a value that is deemed sensible by the server. This 355 * should be set to a value that gives PulseAudio enough time to 356 * move the data from the per-stream playback buffer into the 357 * hardware playback buffer. */ 358 359 uint32_t fragsize; 360 /**< Recording only: fragment size. The server sends data in 361 * blocks of fragsize bytes size. Large values diminish 362 * interactivity with other operations on the connection context 363 * but decrease control overhead. It is recommended to set this to 364 * (uint32_t) -1, which will initialize this to a value that is 365 * deemed sensible by the server. However, this value will default 366 * to something like 2s, i.e. for applications that have specific 367 * latency requirements this value should be set to the maximum 368 * latency that the application can deal with. If 369 * PA_STREAM_ADJUST_LATENCY is set the overall source latency will 370 * be adjusted according to this value. If it is not set the 371 * source latency is left unmodified. */ 372 373 } pa_buffer_attr; 374 375 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */ 376 enum { 377 PA_OK = 0, /**< No error */ 378 PA_ERR_ACCESS, /**< Access failure */ 379 PA_ERR_COMMAND, /**< Unknown command */ 380 PA_ERR_INVALID, /**< Invalid argument */ 381 PA_ERR_EXIST, /**< Entity exists */ 382 PA_ERR_NOENTITY, /**< No such entity */ 383 PA_ERR_CONNECTIONREFUSED, /**< Connection refused */ 384 PA_ERR_PROTOCOL, /**< Protocol error */ 385 PA_ERR_TIMEOUT, /**< Timeout */ 386 PA_ERR_AUTHKEY, /**< No authorization key */ 387 PA_ERR_INTERNAL, /**< Internal error */ 388 PA_ERR_CONNECTIONTERMINATED, /**< Connection terminated */ 389 PA_ERR_KILLED, /**< Entity killed */ 390 PA_ERR_INVALIDSERVER, /**< Invalid server */ 391 PA_ERR_MODINITFAILED, /**< Module initialization failed */ 392 PA_ERR_BADSTATE, /**< Bad state */ 393 PA_ERR_NODATA, /**< No data */ 394 PA_ERR_VERSION, /**< Incompatible protocol version */ 395 PA_ERR_TOOLARGE, /**< Data too large */ 396 PA_ERR_NOTSUPPORTED, /**< Operation not supported \since 0.9.5 */ 397 PA_ERR_UNKNOWN, /**< The error code was unknown to the client */ 398 PA_ERR_NOEXTENSION, /**< Extension does not exist. \since 0.9.12 */ 399 PA_ERR_OBSOLETE, /**< Obsolete functionality. \since 0.9.15 */ 400 PA_ERR_NOTIMPLEMENTED, /**< Missing implementation. \since 0.9.15 */ 401 PA_ERR_FORKED, /**< The caller forked without calling execve() and tried to reuse the context. \since 0.9.15 */ 402 PA_ERR_IO, /**< An IO error happened. \since 0.9.16 */ 403 PA_ERR_BUSY, /**< Device or resource busy. \since 0.9.17 */ 404 PA_ERR_MAX /**< Not really an error but the first invalid error code */ 405 }; 406 407 /** \cond fulldocs */ 408 #define PA_OK PA_OK 409 #define PA_ERR_ACCESS PA_ERR_ACCESS 410 #define PA_ERR_COMMAND PA_ERR_COMMAND 411 #define PA_ERR_INVALID PA_ERR_INVALID 412 #define PA_ERR_EXIST PA_ERR_EXIST 413 #define PA_ERR_NOENTITY PA_ERR_NOENTITY 414 #define PA_ERR_CONNECTIONREFUSED PA_ERR_CONNECTIONREFUSED 415 #define PA_ERR_PROTOCOL PA_ERR_PROTOCOL 416 #define PA_ERR_TIMEOUT PA_ERR_TIMEOUT 417 #define PA_ERR_AUTHKEY PA_ERR_AUTHKEY 418 #define PA_ERR_INTERNAL PA_ERR_INTERNAL 419 #define PA_ERR_CONNECTIONTERMINATED PA_ERR_CONNECTIONTERMINATED 420 #define PA_ERR_KILLED PA_ERR_KILLED 421 #define PA_ERR_INVALIDSERVER PA_ERR_INVALIDSERVER 422 #define PA_ERR_MODINITFAILED PA_ERR_MODINITFAILED 423 #define PA_ERR_BADSTATE PA_ERR_BADSTATE 424 #define PA_ERR_NODATA PA_ERR_NODATA 425 #define PA_ERR_VERSION PA_ERR_VERSION 426 #define PA_ERR_TOOLARGE PA_ERR_TOOLARGE 427 #define PA_ERR_NOTSUPPORTED PA_ERR_NOTSUPPORTED 428 #define PA_ERR_UNKNOWN PA_ERR_UNKNOWN 429 #define PA_ERR_NOEXTENSION PA_ERR_NOEXTENSION 430 #define PA_ERR_OBSOLETE PA_ERR_OBSOLETE 431 #define PA_ERR_NOTIMPLEMENTED PA_ERR_NOTIMPLEMENTED 432 #define PA_ERR_FORKED PA_ERR_FORKED 433 #define PA_ERR_MAX PA_ERR_MAX 434 /** \endcond */ 435 436 /** Subscription event mask, as used by pa_context_subscribe() */ 437 typedef enum pa_subscription_mask { 438 PA_SUBSCRIPTION_MASK_NULL = 0x0000U, 439 /**< No events */ 440 441 PA_SUBSCRIPTION_MASK_SINK = 0x0001U, 442 /**< Sink events */ 443 444 PA_SUBSCRIPTION_MASK_SOURCE = 0x0002U, 445 /**< Source events */ 446 447 PA_SUBSCRIPTION_MASK_SINK_INPUT = 0x0004U, 448 /**< Sink input events */ 449 450 PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 0x0008U, 451 /**< Source output events */ 452 453 PA_SUBSCRIPTION_MASK_MODULE = 0x0010U, 454 /**< Module events */ 455 456 PA_SUBSCRIPTION_MASK_CLIENT = 0x0020U, 457 /**< Client events */ 458 459 PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 0x0040U, 460 /**< Sample cache events */ 461 462 PA_SUBSCRIPTION_MASK_SERVER = 0x0080U, 463 /**< Other global server changes. */ 464 465 /** \cond fulldocs */ 466 PA_SUBSCRIPTION_MASK_AUTOLOAD = 0x0100U, 467 /**< \deprecated Autoload table events. */ 468 /** \endcond */ 469 470 PA_SUBSCRIPTION_MASK_CARD = 0x0200U, 471 /**< Card events. \since 0.9.15 */ 472 473 PA_SUBSCRIPTION_MASK_ALL = 0x02ffU 474 /**< Catch all events */ 475 } pa_subscription_mask_t; 476 477 /** Subscription event types, as used by pa_context_subscribe() */ 478 typedef enum pa_subscription_event_type { 479 PA_SUBSCRIPTION_EVENT_SINK = 0x0000U, 480 /**< Event type: Sink */ 481 482 PA_SUBSCRIPTION_EVENT_SOURCE = 0x0001U, 483 /**< Event type: Source */ 484 485 PA_SUBSCRIPTION_EVENT_SINK_INPUT = 0x0002U, 486 /**< Event type: Sink input */ 487 488 PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 0x0003U, 489 /**< Event type: Source output */ 490 491 PA_SUBSCRIPTION_EVENT_MODULE = 0x0004U, 492 /**< Event type: Module */ 493 494 PA_SUBSCRIPTION_EVENT_CLIENT = 0x0005U, 495 /**< Event type: Client */ 496 497 PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 0x0006U, 498 /**< Event type: Sample cache item */ 499 500 PA_SUBSCRIPTION_EVENT_SERVER = 0x0007U, 501 /**< Event type: Global server change, only occurring with PA_SUBSCRIPTION_EVENT_CHANGE. */ 502 503 /** \cond fulldocs */ 504 PA_SUBSCRIPTION_EVENT_AUTOLOAD = 0x0008U, 505 /**< \deprecated Event type: Autoload table changes. */ 506 /** \endcond */ 507 508 PA_SUBSCRIPTION_EVENT_CARD = 0x0009U, 509 /**< Event type: Card \since 0.9.15 */ 510 511 PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 0x000FU, 512 /**< A mask to extract the event type from an event value */ 513 514 PA_SUBSCRIPTION_EVENT_NEW = 0x0000U, 515 /**< A new object was created */ 516 517 PA_SUBSCRIPTION_EVENT_CHANGE = 0x0010U, 518 /**< A property of the object was modified */ 519 520 PA_SUBSCRIPTION_EVENT_REMOVE = 0x0020U, 521 /**< An object was removed */ 522 523 PA_SUBSCRIPTION_EVENT_TYPE_MASK = 0x0030U 524 /**< A mask to extract the event operation from an event value */ 525 526 } pa_subscription_event_type_t; 527 528 /** Return one if an event type t matches an event mask bitfield */ 529 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK)))) 530 531 /** \cond fulldocs */ 532 #define PA_SUBSCRIPTION_MASK_NULL PA_SUBSCRIPTION_MASK_NULL 533 #define PA_SUBSCRIPTION_MASK_SINK PA_SUBSCRIPTION_MASK_SINK 534 #define PA_SUBSCRIPTION_MASK_SOURCE PA_SUBSCRIPTION_MASK_SOURCE 535 #define PA_SUBSCRIPTION_MASK_SINK_INPUT PA_SUBSCRIPTION_MASK_SINK_INPUT 536 #define PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT 537 #define PA_SUBSCRIPTION_MASK_MODULE PA_SUBSCRIPTION_MASK_MODULE 538 #define PA_SUBSCRIPTION_MASK_CLIENT PA_SUBSCRIPTION_MASK_CLIENT 539 #define PA_SUBSCRIPTION_MASK_SAMPLE_CACHE PA_SUBSCRIPTION_MASK_SAMPLE_CACHE 540 #define PA_SUBSCRIPTION_MASK_SERVER PA_SUBSCRIPTION_MASK_SERVER 541 #define PA_SUBSCRIPTION_MASK_AUTOLOAD PA_SUBSCRIPTION_MASK_AUTOLOAD 542 #define PA_SUBSCRIPTION_MASK_CARD PA_SUBSCRIPTION_MASK_CARD 543 #define PA_SUBSCRIPTION_MASK_ALL PA_SUBSCRIPTION_MASK_ALL 544 #define PA_SUBSCRIPTION_EVENT_SINK PA_SUBSCRIPTION_EVENT_SINK 545 #define PA_SUBSCRIPTION_EVENT_SOURCE PA_SUBSCRIPTION_EVENT_SOURCE 546 #define PA_SUBSCRIPTION_EVENT_SINK_INPUT PA_SUBSCRIPTION_EVENT_SINK_INPUT 547 #define PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT 548 #define PA_SUBSCRIPTION_EVENT_MODULE PA_SUBSCRIPTION_EVENT_MODULE 549 #define PA_SUBSCRIPTION_EVENT_CLIENT PA_SUBSCRIPTION_EVENT_CLIENT 550 #define PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE 551 #define PA_SUBSCRIPTION_EVENT_SERVER PA_SUBSCRIPTION_EVENT_SERVER 552 #define PA_SUBSCRIPTION_EVENT_AUTOLOAD PA_SUBSCRIPTION_EVENT_AUTOLOAD 553 #define PA_SUBSCRIPTION_EVENT_CARD PA_SUBSCRIPTION_EVENT_CARD 554 #define PA_SUBSCRIPTION_EVENT_FACILITY_MASK PA_SUBSCRIPTION_EVENT_FACILITY_MASK 555 #define PA_SUBSCRIPTION_EVENT_NEW PA_SUBSCRIPTION_EVENT_NEW 556 #define PA_SUBSCRIPTION_EVENT_CHANGE PA_SUBSCRIPTION_EVENT_CHANGE 557 #define PA_SUBSCRIPTION_EVENT_REMOVE PA_SUBSCRIPTION_EVENT_REMOVE 558 #define PA_SUBSCRIPTION_EVENT_TYPE_MASK PA_SUBSCRIPTION_EVENT_TYPE_MASK 559 /** \endcond */ 560 561 /** A structure for all kinds of timing information of a stream. See 562 * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The 563 * total output latency a sample that is written with 564 * pa_stream_write() takes to be played may be estimated by 565 * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined 566 * as pa_bytes_to_usec(write_index-read_index)) The output buffer 567 * which buffer_usec relates to may be manipulated freely (with 568 * pa_stream_write()'s seek argument, pa_stream_flush() and friends), 569 * the buffers sink_usec and source_usec relate to are first-in 570 * first-out (FIFO) buffers which cannot be flushed or manipulated in 571 * any way. The total input latency a sample that is recorded takes to 572 * be delivered to the application is: 573 * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of 574 * sign issues!) When connected to a monitor source sink_usec contains 575 * the latency of the owning sink. The two latency estimations 576 * described here are implemented in pa_stream_get_latency(). Please 577 * note that this structure can be extended as part of evolutionary 578 * API updates at any time in any new release.*/ 579 typedef struct pa_timing_info { 580 struct timeval timestamp; 581 /**< The time when this timing info structure was current */ 582 583 int synchronized_clocks; 584 /**< Non-zero if the local and the remote machine have 585 * synchronized clocks. If synchronized clocks are detected 586 * transport_usec becomes much more reliable. However, the code 587 * that detects synchronized clocks is very limited and unreliable 588 * itself. */ 589 590 pa_usec_t sink_usec; 591 /**< Time in usecs a sample takes to be played on the sink. For 592 * playback streams and record streams connected to a monitor 593 * source. */ 594 595 pa_usec_t source_usec; 596 /**< Time in usecs a sample takes from being recorded to being 597 * delivered to the application. Only for record streams. */ 598 599 pa_usec_t transport_usec; 600 /**< Estimated time in usecs a sample takes to be transferred 601 * to/from the daemon. For both playback and record streams. */ 602 603 int playing; 604 /**< Non-zero when the stream is currently not underrun and data 605 * is being passed on to the device. Only for playback 606 * streams. This field does not say whether the data is actually 607 * already being played. To determine this check whether 608 * since_underrun (converted to usec) is larger than sink_usec.*/ 609 610 int write_index_corrupt; 611 /**< Non-zero if write_index is not up-to-date because a local 612 * write command that corrupted it has been issued in the time 613 * since this latency info was current . Only write commands with 614 * SEEK_RELATIVE_ON_READ and SEEK_RELATIVE_END can corrupt 615 * write_index. */ 616 617 int64_t write_index; 618 /**< Current write index into the playback buffer in bytes. Think 619 * twice before using this for seeking purposes: it might be out 620 * of date a the time you want to use it. Consider using 621 * PA_SEEK_RELATIVE instead. */ 622 623 int read_index_corrupt; 624 /**< Non-zero if read_index is not up-to-date because a local 625 * pause or flush request that corrupted it has been issued in the 626 * time since this latency info was current. */ 627 628 int64_t read_index; 629 /**< Current read index into the playback buffer in bytes. Think 630 * twice before using this for seeking purposes: it might be out 631 * of date a the time you want to use it. Consider using 632 * PA_SEEK_RELATIVE_ON_READ instead. */ 633 634 pa_usec_t configured_sink_usec; 635 /**< The configured latency for the sink. \since 0.9.11 */ 636 637 pa_usec_t configured_source_usec; 638 /**< The configured latency for the source. \since 0.9.11 */ 639 640 int64_t since_underrun; 641 /**< Bytes that were handed to the sink since the last underrun 642 * happened, or since playback started again after the last 643 * underrun. playing will tell you which case it is. \since 644 * 0.9.11 */ 645 646 } pa_timing_info; 647 648 /** A structure for the spawn api. This may be used to integrate auto 649 * spawned daemons into your application. For more information see 650 * pa_context_connect(). When spawning a new child process the 651 * waitpid() is used on the child's PID. The spawn routine will not 652 * block or ignore SIGCHLD signals, since this cannot be done in a 653 * thread compatible way. You might have to do this in 654 * prefork/postfork. */ 655 typedef struct pa_spawn_api { 656 void (*prefork)(void); 657 /**< Is called just before the fork in the parent process. May be 658 * NULL. */ 659 660 void (*postfork)(void); 661 /**< Is called immediately after the fork in the parent 662 * process. May be NULL.*/ 663 664 void (*atfork)(void); 665 /**< Is called immediately after the fork in the child 666 * process. May be NULL. It is not safe to close all file 667 * descriptors in this function unconditionally, since a UNIX 668 * socket (created using socketpair()) is passed to the new 669 * process. */ 670 } pa_spawn_api; 671 672 /** Seek type for pa_stream_write(). */ 673 typedef enum pa_seek_mode { 674 PA_SEEK_RELATIVE = 0, 675 /**< Seek relatively to the write index */ 676 677 PA_SEEK_ABSOLUTE = 1, 678 /**< Seek relatively to the start of the buffer queue */ 679 680 PA_SEEK_RELATIVE_ON_READ = 2, 681 /**< Seek relatively to the read index. */ 682 683 PA_SEEK_RELATIVE_END = 3 684 /**< Seek relatively to the current end of the buffer queue. */ 685 } pa_seek_mode_t; 686 687 /** \cond fulldocs */ 688 #define PA_SEEK_RELATIVE PA_SEEK_RELATIVE 689 #define PA_SEEK_ABSOLUTE PA_SEEK_ABSOLUTE 690 #define PA_SEEK_RELATIVE_ON_READ PA_SEEK_RELATIVE_ON_READ 691 #define PA_SEEK_RELATIVE_END PA_SEEK_RELATIVE_END 692 /** \endcond */ 693 694 /** Special sink flags. */ 695 typedef enum pa_sink_flags { 696 PA_SINK_NOFLAGS = 0x0000U, 697 /**< Flag to pass when no specific options are needed (used to avoid casting) \since 0.9.19 */ 698 699 PA_SINK_HW_VOLUME_CTRL = 0x0001U, 700 /**< Supports hardware volume control */ 701 702 PA_SINK_LATENCY = 0x0002U, 703 /**< Supports latency querying */ 704 705 PA_SINK_HARDWARE = 0x0004U, 706 /**< Is a hardware sink of some kind, in contrast to 707 * "virtual"/software sinks \since 0.9.3 */ 708 709 PA_SINK_NETWORK = 0x0008U, 710 /**< Is a networked sink of some kind. \since 0.9.7 */ 711 712 PA_SINK_HW_MUTE_CTRL = 0x0010U, 713 /**< Supports hardware mute control \since 0.9.11 */ 714 715 PA_SINK_DECIBEL_VOLUME = 0x0020U, 716 /**< Volume can be translated to dB with pa_sw_volume_to_dB() 717 * \since 0.9.11 */ 718 719 PA_SINK_FLAT_VOLUME = 0x0040U, 720 /**< This sink is in flat volume mode, i.e. always the maximum of 721 * the volume of all connected inputs. \since 0.9.15 */ 722 723 PA_SINK_DYNAMIC_LATENCY = 0x0080U 724 /**< The latency can be adjusted dynamically depending on the 725 * needs of the connected streams. \since 0.9.15 */ 726 } pa_sink_flags_t; 727 728 /** \cond fulldocs */ 729 #define PA_SINK_HW_VOLUME_CTRL PA_SINK_HW_VOLUME_CTRL 730 #define PA_SINK_LATENCY PA_SINK_LATENCY 731 #define PA_SINK_HARDWARE PA_SINK_HARDWARE 732 #define PA_SINK_NETWORK PA_SINK_NETWORK 733 #define PA_SINK_HW_MUTE_CTRL PA_SINK_HW_MUTE_CTRL 734 #define PA_SINK_DECIBEL_VOLUME PA_SINK_DECIBEL_VOLUME 735 #define PA_SINK_FLAT_VOLUME PA_SINK_FLAT_VOLUME 736 #define PA_SINK_DYNAMIC_LATENCY PA_SINK_DYNAMIC_LATENCY 737 /** \endcond */ 738 739 /** Sink state. \since 0.9.15 */ 740 typedef enum pa_sink_state { /* enum serialized in u8 */ 741 PA_SINK_INVALID_STATE = -1, 742 /**< This state is used when the server does not support sink state introspection \since 0.9.15 */ 743 744 PA_SINK_RUNNING = 0, 745 /**< Running, sink is playing and used by at least one non-corked sink-input \since 0.9.15 */ 746 747 PA_SINK_IDLE = 1, 748 /**< When idle, the sink is playing but there is no non-corked sink-input attached to it \since 0.9.15 */ 749 750 PA_SINK_SUSPENDED = 2, 751 /**< When suspended, actual sink access can be closed, for instance \since 0.9.15 */ 752 753 /** \cond fulldocs */ 754 /* PRIVATE: Server-side values -- DO NOT USE THIS ON THE CLIENT 755 * SIDE! These values are *not* considered part of the official PA 756 * API/ABI. If you use them your application might break when PA 757 * is upgraded. Also, please note that these values are not useful 758 * on the client side anyway. */ 759 760 PA_SINK_INIT = -2, 761 /**< Initialization state */ 762 763 PA_SINK_UNLINKED = -3 764 /**< The state when the sink is getting unregistered and removed from client access */ 765 /** \endcond */ 766 767 } pa_sink_state_t; 768 769 /** Returns non-zero if sink is playing: running or idle. \since 0.9.15 */ 770 static inline int PA_SINK_IS_OPENED(pa_sink_state_t x) { 771 return x == PA_SINK_RUNNING || x == PA_SINK_IDLE; 772 } 773 774 /** \cond fulldocs */ 775 #define PA_SINK_INVALID_STATE PA_SINK_INVALID_STATE 776 #define PA_SINK_RUNNING PA_SINK_RUNNING 777 #define PA_SINK_IDLE PA_SINK_IDLE 778 #define PA_SINK_SUSPENDED PA_SINK_SUSPENDED 779 #define PA_SINK_INIT PA_SINK_INIT 780 #define PA_SINK_UNLINKED PA_SINK_UNLINKED 781 #define PA_SINK_IS_OPENED PA_SINK_IS_OPENED 782 /** \endcond */ 783 784 /** Special source flags. */ 785 typedef enum pa_source_flags { 786 PA_SOURCE_NOFLAGS = 0x0000U, 787 /**< Flag to pass when no specific options are needed (used to avoid casting) \since 0.9.19 */ 788 789 PA_SOURCE_HW_VOLUME_CTRL = 0x0001U, 790 /**< Supports hardware volume control */ 791 792 PA_SOURCE_LATENCY = 0x0002U, 793 /**< Supports latency querying */ 794 795 PA_SOURCE_HARDWARE = 0x0004U, 796 /**< Is a hardware source of some kind, in contrast to 797 * "virtual"/software source \since 0.9.3 */ 798 799 PA_SOURCE_NETWORK = 0x0008U, 800 /**< Is a networked source of some kind. \since 0.9.7 */ 801 802 PA_SOURCE_HW_MUTE_CTRL = 0x0010U, 803 /**< Supports hardware mute control \since 0.9.11 */ 804 805 PA_SOURCE_DECIBEL_VOLUME = 0x0020U, 806 /**< Volume can be translated to dB with pa_sw_volume_to_dB() 807 * \since 0.9.11 */ 808 809 PA_SOURCE_DYNAMIC_LATENCY = 0x0040U 810 /**< The latency can be adjusted dynamically depending on the 811 * needs of the connected streams. \since 0.9.15 */ 812 } pa_source_flags_t; 813 814 /** \cond fulldocs */ 815 #define PA_SOURCE_HW_VOLUME_CTRL PA_SOURCE_HW_VOLUME_CTRL 816 #define PA_SOURCE_LATENCY PA_SOURCE_LATENCY 817 #define PA_SOURCE_HARDWARE PA_SOURCE_HARDWARE 818 #define PA_SOURCE_NETWORK PA_SOURCE_NETWORK 819 #define PA_SOURCE_HW_MUTE_CTRL PA_SOURCE_HW_MUTE_CTRL 820 #define PA_SOURCE_DECIBEL_VOLUME PA_SOURCE_DECIBEL_VOLUME 821 #define PA_SOURCE_DYNAMIC_LATENCY PA_SOURCE_DYNAMIC_LATENCY 822 /** \endcond */ 823 824 /** Source state. \since 0.9.15 */ 825 typedef enum pa_source_state { 826 PA_SOURCE_INVALID_STATE = -1, 827 /**< This state is used when the server does not support source state introspection \since 0.9.15 */ 828 829 PA_SOURCE_RUNNING = 0, 830 /**< Running, source is recording and used by at least one non-corked source-output \since 0.9.15 */ 831 832 PA_SOURCE_IDLE = 1, 833 /**< When idle, the source is still recording but there is no non-corked source-output \since 0.9.15 */ 834 835 PA_SOURCE_SUSPENDED = 2, 836 /**< When suspended, actual source access can be closed, for instance \since 0.9.15 */ 837 838 /** \cond fulldocs */ 839 /* PRIVATE: Server-side values -- DO NOT USE THIS ON THE CLIENT 840 * SIDE! These values are *not* considered part of the official PA 841 * API/ABI. If you use them your application might break when PA 842 * is upgraded. Also, please note that these values are not useful 843 * on the client side anyway. */ 844 845 PA_SOURCE_INIT = -2, 846 /**< Initialization state */ 847 848 PA_SOURCE_UNLINKED = -3 849 /**< The state when the source is getting unregistered and removed from client access */ 850 /** \endcond */ 851 852 } pa_source_state_t; 853 854 /** Returns non-zero if source is recording: running or idle. \since 0.9.15 */ 855 static inline int PA_SOURCE_IS_OPENED(pa_source_state_t x) { 856 return x == PA_SOURCE_RUNNING || x == PA_SOURCE_IDLE; 857 } 858 859 /** \cond fulldocs */ 860 #define PA_SOURCE_INVALID_STATE PA_SOURCE_INVALID_STATE 861 #define PA_SOURCE_RUNNING PA_SOURCE_RUNNING 862 #define PA_SOURCE_IDLE PA_SOURCE_IDLE 863 #define PA_SOURCE_SUSPENDED PA_SOURCE_SUSPENDED 864 #define PA_SOURCE_INIT PA_SOURCE_INIT 865 #define PA_SOURCE_UNLINKED PA_SOURCE_UNLINKED 866 #define PA_SOURCE_IS_OPENED PA_SOURCE_IS_OPENED 867 /** \endcond */ 868 869 /** A generic free() like callback prototype */ 870 typedef void (*pa_free_cb_t)(void *p); 871 872 /** A stream policy/meta event requesting that an application should 873 * cork a specific stream. See pa_stream_event_cb_t for more 874 * information, \since 0.9.15 */ 875 #define PA_STREAM_EVENT_REQUEST_CORK "request-cork" 876 877 /** A stream policy/meta event requesting that an application should 878 * cork a specific stream. See pa_stream_event_cb_t for more 879 * information, \since 0.9.15 */ 880 #define PA_STREAM_EVENT_REQUEST_UNCORK "request-uncork" 881 882 PA_C_DECL_END 883 884 #endif 885