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