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