src/pulse/def.h

   1 #ifndef foodefhfoo
   2 #define foodefhfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2004-2006 Lennart Poettering
   8   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
   9
  10   PulseAudio is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU Lesser General Public License as
  12   published by the Free Software Foundation; either version 2.1 of the
  13   License, or (at your option) any later version.
  14
  15   PulseAudio is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public
  21   License along with PulseAudio; if not, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include <inttypes.h>
  27 #include <sys/time.h>
  28 #include <time.h>
  29
  30 #include <pulse/cdecl.h>
  31 #include <pulse/sample.h>
  32
  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_IS_GOOD PA_CONTEXT_IS_GOOD
  60 /** \endcond */
  61
  62 /** The state of a stream */
  63 typedef enum pa_stream_state {
  64     PA_STREAM_UNCONNECTED,  /**< The stream is not yet connected to any sink or source */
  65     PA_STREAM_CREATING,     /**< The stream is being created */
  66     PA_STREAM_READY,        /**< The stream is established, you may pass audio data to it now */
  67     PA_STREAM_FAILED,       /**< An error occured that made the stream invalid */
  68     PA_STREAM_TERMINATED    /**< The stream has been terminated cleanly */
  69 } pa_stream_state_t;
  70
  71 /** Return non-zero if the passed state is one of the connected states. \since 0.9.11 */
  72 static inline int PA_STREAM_IS_GOOD(pa_stream_state_t x) {
  73     return
  74         x == PA_STREAM_CREATING ||
  75         x == PA_STREAM_READY;
  76 }
  77
  78 /** \cond fulldocs */
  79 #define PA_STREAM_IS_GOOD PA_STREAM_IS_GOOD
  80 /** \endcond */
  81
  82 /** The state of an operation */
  83 typedef enum pa_operation_state {
  84     PA_OPERATION_RUNNING,      /**< The operation is still running */
  85     PA_OPERATION_DONE,         /**< The operation has been completed */
  86     PA_OPERATION_CANCELED      /**< The operation has been canceled */
  87 } pa_operation_state_t;
  88
  89 /** An invalid index */
  90 #define PA_INVALID_INDEX ((uint32_t) -1)
  91
  92 /** Some special flags for contexts. */
  93 typedef enum pa_context_flags {
  94     PA_CONTEXT_NOAUTOSPAWN = 1
  95     /**< Disabled autospawning of the PulseAudio daemon if required */
  96 } pa_context_flags_t;
  97
  98 /** \cond fulldocs */
  99 /* Allow clients to check with #ifdef for those flags */
 100 #define PA_CONTEXT_NOAUTOSPAWN PA_CONTEXT_NOAUTOSPAWN
 101 /** \endcond */
 102
 103 /** The direction of a pa_stream object */
 104 typedef enum pa_stream_direction {
 105     PA_STREAM_NODIRECTION,   /**< Invalid direction */
 106     PA_STREAM_PLAYBACK,      /**< Playback stream */
 107     PA_STREAM_RECORD,        /**< Record stream */
 108     PA_STREAM_UPLOAD         /**< Sample upload stream */
 109 } pa_stream_direction_t;
 110
 111 /** Some special flags for stream connections. */
 112 typedef enum pa_stream_flags {
 113
 114     PA_STREAM_START_CORKED = 0x0001U,
 115     /**< Create the stream corked, requiring an explicit
 116      * pa_stream_cork() call to uncork it. */
 117
 118     PA_STREAM_INTERPOLATE_TIMING = 0x0002U,
 119     /**< Interpolate the latency for this stream. When enabled,
 120      * pa_stream_get_latency() and pa_stream_get_time() will try to
 121      * estimate the current record/playback time based on the local
 122      * time that passed since the last timing info update.  Using this
 123      * option has the advantage of not requiring a whole roundtrip
 124      * when the current playback/recording time is needed. Consider
 125      * using this option when requesting latency information
 126      * frequently. This is especially useful on long latency network
 127      * connections. It makes a lot of sense to combine this option
 128      * with PA_STREAM_AUTO_TIMING_UPDATE. */
 129
 130     PA_STREAM_NOT_MONOTONIC = 0x0004U,
 131     /**< Don't force the time to increase monotonically. If this
 132      * option is enabled, pa_stream_get_time() will not necessarily
 133      * return always monotonically increasing time values on each
 134      * call. This may confuse applications which cannot deal with time
 135      * going 'backwards', but has the advantage that bad transport
 136      * latency estimations that caused the time to to jump ahead can
 137      * be corrected quickly, without the need to wait. (Please note
 138      * that this flag was named PA_STREAM_NOT_MONOTONOUS in releases
 139      * prior to 0.9.11. The old name is still defined too, for
 140      * compatibility reasons. */
 141
 142     PA_STREAM_AUTO_TIMING_UPDATE = 0x0008U,
 143     /**< If set timing update requests are issued periodically
 144      * automatically. Combined with PA_STREAM_INTERPOLATE_TIMING you
 145      * will be able to query the current time and latency with
 146      * pa_stream_get_time() and pa_stream_get_latency() at all times
 147      * without a packet round trip.*/
 148
 149     PA_STREAM_NO_REMAP_CHANNELS = 0x0010U,
 150     /**< Don't remap channels by their name, instead map them simply
 151      * by their index. Implies PA_STREAM_NO_REMIX_CHANNELS. Only
 152      * supported when the server is at least PA 0.9.8. It is ignored
 153      * on older servers.\since 0.9.8 */
 154
 155     PA_STREAM_NO_REMIX_CHANNELS = 0x0020U,
 156     /**< When remapping channels by name, don't upmix or downmix them
 157      * to related channels. Copy them into matching channels of the
 158      * device 1:1. Only supported when the server is at least PA
 159      * 0.9.8. It is ignored on older servers. \since 0.9.8 */
 160
 161     PA_STREAM_FIX_FORMAT = 0x0040U,
 162     /**< Use the sample format of the sink/device this stream is being
 163      * connected to, and possibly ignore the format the sample spec
 164      * contains -- but you still have to pass a valid value in it as a
 165      * hint to PulseAudio what would suit your stream best. If this is
 166      * used you should query the used sample format after creating the
 167      * stream by using pa_stream_get_sample_spec(). Also, if you
 168      * specified manual buffer metrics it is recommended to update
 169      * them with pa_stream_set_buffer_attr() to compensate for the
 170      * changed frame sizes. Only supported when the server is at least
 171      * PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
 172
 173     PA_STREAM_FIX_RATE = 0x0080U,
 174     /**< Use the sample rate of the sink, and possibly ignore the rate
 175      * the sample spec contains. Usage similar to
 176      * PA_STREAM_FIX_FORMAT.Only supported when the server is at least
 177      * PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
 178
 179     PA_STREAM_FIX_CHANNELS = 0x0100,
 180     /**< Use the number of channels and the channel map of the sink,
 181      * and possibly ignore the number of channels and the map the
 182      * sample spec and the passed channel map contains. Usage similar
 183      * to PA_STREAM_FIX_FORMAT. Only supported when the server is at
 184      * least PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
 185
 186     PA_STREAM_DONT_MOVE = 0x0200U,
 187     /**< Don't allow moving of this stream to another
 188      * sink/device. Useful if you use any of the PA_STREAM_FIX_ flags
 189      * and want to make sure that resampling never takes place --
 190      * which might happen if the stream is moved to another
 191      * sink/source whith a different sample spec/channel map. Only
 192      * supported when the server is at least PA 0.9.8. It is ignored
 193      * on older servers. \since 0.9.8 */
 194
 195     PA_STREAM_VARIABLE_RATE = 0x0400U,
 196     /**< Allow dynamic changing of the sampling rate during playback
 197      * with pa_stream_update_sample_rate(). Only supported when the
 198      * server is at least PA 0.9.8. It is ignored on older
 199      * servers. \since 0.9.8 */
 200
 201     PA_STREAM_PEAK_DETECT = 0x0800U,
 202     /**< Find peaks instead of resampling. \since 0.9.11 */
 203
 204     PA_STREAM_START_MUTED = 0x1000U,
 205     /**< Create in muted state. If neither PA_STREAM_START_UNMUTED nor
 206      * PA_STREAM_START_MUTED it is left to the server to decide
 207      * whether to create the stream in muted or in unmuted
 208      * state. \since 0.9.11 */
 209
 210     PA_STREAM_ADJUST_LATENCY = 0x2000U,
 211     /**< Try to adjust the latency of the sink/source based on the
 212      * requested buffer metrics and adjust buffer metrics
 213      * accordingly. Also see pa_buffer_attr. This option may not be
 214      * specified at the same time as PA_STREAM_EARLY_REQUESTS. \since
 215      * 0.9.11 */
 216
 217     PA_STREAM_EARLY_REQUESTS = 0x4000U,
 218     /**< Enable compatibility mode for legacy clients that rely on a
 219      * "classic" hardware device fragment-style playback model. If
 220      * this option is set, the minreq value of the buffer metrics gets
 221      * a new meaning: instead of just specifying that no requests
 222      * asking for less new data than this value will be made to the
 223      * client it will also guarantee that requests are generated as
 224      * early as this limit is reached. This flag should only be set in
 225      * very few situations where compatiblity with a fragment-based
 226      * playback model needs to be kept and the client applications
 227      * cannot deal with data requests that are delayed to the latest
 228      * moment possible. (Usually these are programs that use usleep()
 229      * or a similar call in their playback loops instead of sleeping
 230      * on the device itself.) Also see pa_buffer_attr. This option may
 231      * not be specified at the same time as
 232      * PA_STREAM_ADJUST_LATENCY. \since 0.9.12 */
 233
 234     PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND = 0x8000U,
 235     /**< If set this stream won't be taken into account when we it is
 236      * checked whether the device this stream is connected to should
 237      * auto-suspend. \ since 0.9.14 */
 238
 239     PA_STREAM_START_UNMUTED = 0x10000U
 240     /**< Create in unmuted state. If neither PA_STREAM_START_UNMUTED
 241      * nor PA_STREAM_START_MUTED it is left to the server to decide
 242      * whether to create the stream in muted or in unmuted
 243      * state. \since 0.9.14 */
 244
 245 } pa_stream_flags_t;
 246
 247 /** \cond fulldocs */
 248
 249 /* English is an evil language */
 250 #define PA_STREAM_NOT_MONOTONOUS PA_STREAM_NOT_MONOTONIC
 251
 252 /* Allow clients to check with #ifdef for those flags */
 253 #define PA_STREAM_START_CORKED PA_STREAM_START_CORKED
 254 #define PA_STREAM_INTERPOLATE_TIMING PA_STREAM_INTERPOLATE_TIMING
 255 #define PA_STREAM_NOT_MONOTONIC PA_STREAM_NOT_MONOTONIC
 256 #define PA_STREAM_AUTO_TIMING_UPDATE PA_STREAM_AUTO_TIMING_UPDATE
 257 #define PA_STREAM_NO_REMAP_CHANNELS PA_STREAM_NO_REMAP_CHANNELS
 258 #define PA_STREAM_NO_REMIX_CHANNELS PA_STREAM_NO_REMIX_CHANNELS
 259 #define PA_STREAM_FIX_FORMAT PA_STREAM_FIX_FORMAT
 260 #define PA_STREAM_FIX_RATE PA_STREAM_FIX_RATE
 261 #define PA_STREAM_FIX_CHANNELS PA_STREAM_FIX_CHANNELS
 262 #define PA_STREAM_DONT_MOVE PA_STREAM_DONT_MOVE
 263 #define PA_STREAM_VARIABLE_RATE PA_STREAM_VARIABLE_RATE
 264 #define PA_STREAM_PEAK_DETECT PA_STREAM_PEAK_DETECT
 265 #define PA_STREAM_START_MUTED PA_STREAM_START_MUTED
 266 #define PA_STREAM_ADJUST_LATENCY PA_STREAM_ADJUST_LATENCY
 267 #define PA_STREAM_EARLY_REQUESTS PA_STREAM_EARLY_REQUESTS
 268 #define PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND
 269 #define PA_STREAM_START_UNMUTED PA_STREAM_START_UNMUTED
 270
 271 /** \endcond */
 272
 273 /** Playback and record buffer metrics */
 274 typedef struct pa_buffer_attr {
 275     uint32_t maxlength;
 276     /**< Maximum length of the buffer. Setting this to (uint32_t) -1
 277      * will initialize this to the maximum value supported by server,
 278      * which is recommended. */
 279
 280     uint32_t tlength;
 281     /**< Playback only: target length of the buffer. The server tries
 282      * to assure that at least tlength bytes are always available in
 283      * the per-stream server-side playback buffer. It is recommended
 284      * to set this to (uint32_t) -1, which will initialize this to a
 285      * value that is deemed sensible by the server. However, this
 286      * value will default to something like 2s, i.e. for applications
 287      * that have specific latency requirements this value should be
 288      * set to the maximum latency that the application can deal
 289      * with. When PA_STREAM_ADJUST_LATENCY is not set this value will
 290      * influence only the per-stream playback buffer size. When
 291      * PA_STREAM_ADJUST_LATENCY is set the overall latency of the sink
 292      * plus the playback buffer size is configured to this value. Set
 293      * PA_STREAM_ADJUST_LATENCY if you are interested in adjusting the
 294      * overall latency. Don't set it if you are interested in
 295      * configuring the server-sider per-stream playback buffer
 296      * size. */
 297
 298     uint32_t prebuf;
 299     /**< Playback only: pre-buffering. The server does not start with
 300      * playback before at least prebug bytes are available in the
 301      * buffer. It is recommended to set this to (uint32_t) -1, which
 302      * will initialize this to the same value as tlength, whatever
 303      * that may be. Initialize to 0 to enable manual start/stop
 304      * control of the stream. This means that playback will not stop
 305      * on underrun and playback will not start automatically. Instead
 306      * pa_stream_corked() needs to be called explicitly. If you set
 307      * this value to 0 you should also set PA_STREAM_START_CORKED. */
 308
 309     uint32_t minreq;
 310     /**< Playback only: minimum request. The server does not request
 311      * less than minreq bytes from the client, instead waits until the
 312      * buffer is free enough to request more bytes at once. It is
 313      * recommended to set this to (uint32_t) -1, which will initialize
 314      * this to a value that is deemed sensible by the server. This
 315      * should be set to a value that gives PulseAudio enough time to
 316      * move the data from the per-stream playback buffer into the
 317      * hardware playback buffer. */
 318
 319     uint32_t fragsize;
 320     /**< Recording only: fragment size. The server sends data in
 321      * blocks of fragsize bytes size. Large values deminish
 322      * interactivity with other operations on the connection context
 323      * but decrease control overhead. It is recommended to set this to
 324      * (uint32_t) -1, which will initialize this to a value that is
 325      * deemed sensible by the server. However, this value will default
 326      * to something like 2s, i.e. for applications that have specific
 327      * latency requirements this value should be set to the maximum
 328      * latency that the application can deal with. If
 329      * PA_STREAM_ADJUST_LATENCY is set the overall source latency will
 330      * be adjusted according to this value. If it is not set the
 331      * source latency is left unmodified. */
 332
 333 } pa_buffer_attr;
 334
 335 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
 336 enum {
 337     PA_OK = 0,                     /**< No error */
 338     PA_ERR_ACCESS,                 /**< Access failure */
 339     PA_ERR_COMMAND,                /**< Unknown command */
 340     PA_ERR_INVALID,                /**< Invalid argument */
 341     PA_ERR_EXIST,                  /**< Entity exists */
 342     PA_ERR_NOENTITY,               /**< No such entity */
 343     PA_ERR_CONNECTIONREFUSED,      /**< Connection refused */
 344     PA_ERR_PROTOCOL,               /**< Protocol error */
 345     PA_ERR_TIMEOUT,                /**< Timeout */
 346     PA_ERR_AUTHKEY,                /**< No authorization key */
 347     PA_ERR_INTERNAL,               /**< Internal error */
 348     PA_ERR_CONNECTIONTERMINATED,   /**< Connection terminated */
 349     PA_ERR_KILLED,                 /**< Entity killed */
 350     PA_ERR_INVALIDSERVER,          /**< Invalid server */
 351     PA_ERR_MODINITFAILED,          /**< Module initialization failed */
 352     PA_ERR_BADSTATE,               /**< Bad state */
 353     PA_ERR_NODATA,                 /**< No data */
 354     PA_ERR_VERSION,                /**< Incompatible protocol version */
 355     PA_ERR_TOOLARGE,               /**< Data too large */
 356     PA_ERR_NOTSUPPORTED,           /**< Operation not supported \since 0.9.5 */
 357     PA_ERR_UNKNOWN,                /**< The error code was unknown to the client */
 358     PA_ERR_NOEXTENSION,            /**< Extension does not exist. \since 0.9.12 */
 359     PA_ERR_MAX                     /**< Not really an error but the first invalid error code */
 360 };
 361
 362 /** Subscription event mask, as used by pa_context_subscribe() */
 363 typedef enum pa_subscription_mask {
 364     PA_SUBSCRIPTION_MASK_NULL = 0x0000U,
 365     /**< No events */
 366
 367     PA_SUBSCRIPTION_MASK_SINK = 0x0001U,
 368     /**< Sink events */
 369
 370     PA_SUBSCRIPTION_MASK_SOURCE = 0x0002U,
 371     /**< Source events */
 372
 373     PA_SUBSCRIPTION_MASK_SINK_INPUT = 0x0004U,
 374     /**< Sink input events */
 375
 376     PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 0x0008U,
 377     /**< Source output events */
 378
 379     PA_SUBSCRIPTION_MASK_MODULE = 0x0010U,
 380     /**< Module events */
 381
 382     PA_SUBSCRIPTION_MASK_CLIENT = 0x0020U,
 383     /**< Client events */
 384
 385     PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 0x0040U,
 386     /**< Sample cache events */
 387
 388     PA_SUBSCRIPTION_MASK_SERVER = 0x0080U,
 389     /**< Other global server changes. */
 390
 391     PA_SUBSCRIPTION_MASK_AUTOLOAD = 0x0100U,
 392     /**< Autoload table events. */
 393
 394     PA_SUBSCRIPTION_MASK_CARD = 0x0200U,
 395     /**< Card events. \since 0.9.15 */
 396
 397     PA_SUBSCRIPTION_MASK_ALL = 0x03ffU
 398     /**< Catch all events */
 399 } pa_subscription_mask_t;
 400
 401 /** Subscription event types, as used by pa_context_subscribe() */
 402 typedef enum pa_subscription_event_type {
 403     PA_SUBSCRIPTION_EVENT_SINK = 0x0000U,
 404     /**< Event type: Sink */
 405
 406     PA_SUBSCRIPTION_EVENT_SOURCE = 0x0001U,
 407     /**< Event type: Source */
 408
 409     PA_SUBSCRIPTION_EVENT_SINK_INPUT = 0x0002U,
 410     /**< Event type: Sink input */
 411
 412     PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 0x0003U,
 413     /**< Event type: Source output */
 414
 415     PA_SUBSCRIPTION_EVENT_MODULE = 0x0004U,
 416     /**< Event type: Module */
 417
 418     PA_SUBSCRIPTION_EVENT_CLIENT = 0x0005U,
 419     /**< Event type: Client */
 420
 421     PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 0x0006U,
 422     /**< Event type: Sample cache item */
 423
 424     PA_SUBSCRIPTION_EVENT_SERVER = 0x0007U,
 425     /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. */
 426
 427     PA_SUBSCRIPTION_EVENT_AUTOLOAD = 0x0008U,
 428     /**< Event type: Autoload table changes. */
 429
 430     PA_SUBSCRIPTION_EVENT_CARD = 0x0009U,
 431     /**< Event type: Card \since 0.9.15 */
 432
 433     PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 0x000FU,
 434     /**< A mask to extract the event type from an event value */
 435
 436     PA_SUBSCRIPTION_EVENT_NEW = 0x0000U,
 437     /**< A new object was created */
 438
 439     PA_SUBSCRIPTION_EVENT_CHANGE = 0x0010U,
 440     /**< A property of the object was modified */
 441
 442     PA_SUBSCRIPTION_EVENT_REMOVE = 0x0020U,
 443     /**< An object was removed */
 444
 445     PA_SUBSCRIPTION_EVENT_TYPE_MASK = 0x0030U
 446     /**< A mask to extract the event operation from an event value */
 447
 448 } pa_subscription_event_type_t;
 449
 450 /** Return one if an event type t matches an event mask bitfield */
 451 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
 452
 453 /** A structure for all kinds of timing information of a stream. See
 454  * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
 455  * total output latency a sample that is written with
 456  * pa_stream_write() takes to be played may be estimated by
 457  * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
 458  * as pa_bytes_to_usec(write_index-read_index)) The output buffer
 459  * which buffer_usec relates to may be manipulated freely (with
 460  * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
 461  * the buffers sink_usec and source_usec relate to are first-in
 462  * first-out (FIFO) buffers which cannot be flushed or manipulated in
 463  * any way. The total input latency a sample that is recorded takes to
 464  * be delivered to the application is:
 465  * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
 466  * sign issues!) When connected to a monitor source sink_usec contains
 467  * the latency of the owning sink. The two latency estimations
 468  * described here are implemented in pa_stream_get_latency(). Please
 469  * note that this structure can be extended as part of evolutionary
 470  * API updates at any time in any new release.*/
 471 typedef struct pa_timing_info {
 472     struct timeval timestamp;
 473     /**< The time when this timing info structure was current */
 474
 475     int synchronized_clocks;
 476     /**< Non-zero if the local and the remote machine have
 477      * synchronized clocks. If synchronized clocks are detected
 478      * transport_usec becomes much more reliable. However, the code
 479      * that detects synchronized clocks is very limited und unreliable
 480      * itself. */
 481
 482     pa_usec_t sink_usec;
 483     /**< Time in usecs a sample takes to be played on the sink. For
 484      * playback streams and record streams connected to a monitor
 485      * source. */
 486
 487     pa_usec_t source_usec;
 488     /**< Time in usecs a sample takes from being recorded to being
 489      * delivered to the application. Only for record streams. */
 490
 491     pa_usec_t transport_usec;
 492     /**< Estimated time in usecs a sample takes to be transferred
 493      * to/from the daemon. For both playback and record streams. */
 494
 495     int playing;
 496     /**< Non-zero when the stream is currently not underrun and data
 497      * is being passed on to the device. Only for playback
 498      * streams. This field does not say whether the data is actually
 499      * already being played. To determine this check whether
 500      * since_underrun (converted to usec) is larger than sink_usec.*/
 501
 502     int write_index_corrupt;
 503     /**< Non-zero if write_index is not up-to-date because a local
 504      * write command that corrupted it has been issued in the time
 505      * since this latency info was current . Only write commands with
 506      * SEEK_RELATIVE_ON_READ and SEEK_RELATIVE_END can corrupt
 507      * write_index. */
 508
 509     int64_t write_index;
 510     /**< Current write index into the playback buffer in bytes. Think
 511      * twice before using this for seeking purposes: it might be out
 512      * of date a the time you want to use it. Consider using
 513      * PA_SEEK_RELATIVE instead. */
 514
 515     int read_index_corrupt;
 516     /**< Non-zero if read_index is not up-to-date because a local
 517      * pause or flush request that corrupted it has been issued in the
 518      * time since this latency info was current. */
 519
 520     int64_t read_index;
 521     /**< Current read index into the playback buffer in bytes. Think
 522      * twice before using this for seeking purposes: it might be out
 523      * of date a the time you want to use it. Consider using
 524      * PA_SEEK_RELATIVE_ON_READ instead. */
 525
 526     pa_usec_t configured_sink_usec;
 527     /**< The configured latency for the sink. \since 0.9.11 */
 528
 529     pa_usec_t configured_source_usec;
 530     /**< The configured latency for * the source. \since 0.9.11 */
 531
 532     int64_t since_underrun;
 533     /**< Bytes that were handed to the sink since the last underrun
 534      * happened, or since playback started again after the last
 535      * underrun. playing will tell you which case it is. \since
 536      * 0.9.11 */
 537
 538 } pa_timing_info;
 539
 540 /** A structure for the spawn api. This may be used to integrate auto
 541  * spawned daemons into your application. For more information see
 542  * pa_context_connect(). When spawning a new child process the
 543  * waitpid() is used on the child's PID. The spawn routine will not
 544  * block or ignore SIGCHLD signals, since this cannot be done in a
 545  * thread compatible way. You might have to do this in
 546  * prefork/postfork. */
 547 typedef struct pa_spawn_api {
 548     void (*prefork)(void);
 549     /**< Is called just before the fork in the parent process. May be
 550      * NULL. */
 551
 552     void (*postfork)(void);
 553     /**< Is called immediately after the fork in the parent
 554      * process. May be NULL.*/
 555
 556     void (*atfork)(void);
 557     /**< Is called immediately after the fork in the child
 558      * process. May be NULL. It is not safe to close all file
 559      * descriptors in this function unconditionally, since a UNIX
 560      * socket (created using socketpair()) is passed to the new
 561      * process. */
 562 } pa_spawn_api;
 563
 564 /** Seek type for pa_stream_write(). */
 565 typedef enum pa_seek_mode {
 566     PA_SEEK_RELATIVE = 0,
 567     /**< Seek relatively to the write index */
 568
 569     PA_SEEK_ABSOLUTE = 1,
 570     /**< Seek relatively to the start of the buffer queue */
 571
 572     PA_SEEK_RELATIVE_ON_READ = 2,
 573     /**< Seek relatively to the read index.  */
 574
 575     PA_SEEK_RELATIVE_END = 3
 576     /**< Seek relatively to the current end of the buffer queue. */
 577 } pa_seek_mode_t;
 578
 579 /** Special sink flags. */
 580 typedef enum pa_sink_flags {
 581     PA_SINK_HW_VOLUME_CTRL = 0x0001U,
 582     /**< Supports hardware volume control */
 583
 584     PA_SINK_LATENCY = 0x0002U,
 585     /**< Supports latency querying */
 586
 587     PA_SINK_HARDWARE = 0x0004U,
 588     /**< Is a hardware sink of some kind, in contrast to
 589      * "virtual"/software sinks \since 0.9.3 */
 590
 591     PA_SINK_NETWORK = 0x0008U,
 592     /**< Is a networked sink of some kind. \since 0.9.7 */
 593
 594     PA_SINK_HW_MUTE_CTRL = 0x0010U,
 595     /**< Supports hardware mute control \since 0.9.11 */
 596
 597     PA_SINK_DECIBEL_VOLUME = 0x0020U
 598     /**< Volume can be translated to dB with pa_sw_volume_to_dB()
 599      * \since 0.9.11 */
 600 } pa_sink_flags_t;
 601
 602 /** \cond fulldocs */
 603 #define PA_SINK_HW_VOLUME_CTRL PA_SINK_HW_VOLUME_CTRL
 604 #define PA_SINK_LATENCY PA_SINK_LATENCY
 605 #define PA_SINK_HARDWARE PA_SINK_HARDWARE
 606 #define PA_SINK_NETWORK PA_SINK_NETWORK
 607 #define PA_SINK_HW_VOLUME_CTRL PA_SINK_HW_VOLUME_CTRL
 608 #define PA_SINK_DECIBEL_VOLUME PA_SINK_DECIBEL_VOLUME
 609 /** \endcond */
 610
 611 /** Special source flags.  */
 612 typedef enum pa_source_flags {
 613     PA_SOURCE_HW_VOLUME_CTRL = 0x0001U,
 614     /**< Supports hardware volume control */
 615
 616     PA_SOURCE_LATENCY = 0x0002U,
 617     /**< Supports latency querying */
 618
 619     PA_SOURCE_HARDWARE = 0x0004U,
 620     /**< Is a hardware source of some kind, in contrast to
 621      * "virtual"/software source \since 0.9.3 */
 622
 623     PA_SOURCE_NETWORK = 0x0008U,
 624     /**< Is a networked sink of some kind. \since 0.9.7 */
 625
 626     PA_SOURCE_HW_MUTE_CTRL = 0x0010U,
 627     /**< Supports hardware mute control \since 0.9.11 */
 628
 629     PA_SOURCE_DECIBEL_VOLUME = 0x0020U
 630     /**< Volume can be translated to dB with pa_sw_volume_to_dB()
 631      * \since 0.9.11 */
 632 } pa_source_flags_t;
 633
 634 /** \cond fulldocs */
 635 #define PA_SOURCE_HW_VOLUME_CTRL PA_SOURCE_HW_VOLUME_CTRL
 636 #define PA_SOURCE_LATENCY PA_SOURCE_LATENCY
 637 #define PA_SOURCE_HARDWARE PA_SOURCE_HARDWARE
 638 #define PA_SOURCE_NETWORK PA_SOURCE_NETWORK
 639 #define PA_SOURCE_HW_VOLUME_CTRL PA_SOURCE_HW_VOLUME_CTRL
 640 #define PA_SOURCE_DECIBEL_VOLUME PA_SOURCE_DECIBEL_VOLUME
 641 /** \endcond */
 642
 643 /** A generic free() like callback prototype */
 644 typedef void (*pa_free_cb_t)(void *p);
 645
 646 PA_C_DECL_END
 647
 648 #endif