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
  29 #include <pulse/cdecl.h>
  30 #include <pulse/sample.h>
  31 #include <pulse/version.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_UNCONNECTED PA_CONTEXT_UNCONNECTED
  60 #define PA_CONTEXT_CONNECTING PA_CONTEXT_CONNECTING
  61 #define PA_CONTEXT_AUTHORIZING PA_CONTEXT_AUTHORIZING
  62 #define PA_CONTEXT_SETTING_NAME PA_CONTEXT_SETTING_NAME
  63 #define PA_CONTEXT_READY PA_CONTEXT_READY
  64 #define PA_CONTEXT_FAILED PA_CONTEXT_FAILED
  65 #define PA_CONTEXT_TERMINATED PA_CONTEXT_TERMINATED
  66 #define PA_CONTEXT_IS_GOOD PA_CONTEXT_IS_GOOD
  67 /** \endcond */
  68
  69 /** The state of a stream */
  70 typedef enum pa_stream_state {
  71     PA_STREAM_UNCONNECTED,  /**< The stream is not yet connected to any sink or source */
  72     PA_STREAM_CREATING,     /**< The stream is being created */
  73     PA_STREAM_READY,        /**< The stream is established, you may pass audio data to it now */
  74     PA_STREAM_FAILED,       /**< An error occurred that made the stream invalid */
  75     PA_STREAM_TERMINATED    /**< The stream has been terminated cleanly */
  76 } pa_stream_state_t;
  77
  78 /** Return non-zero if the passed state is one of the connected states. \since 0.9.11 */
  79 static inline int PA_STREAM_IS_GOOD(pa_stream_state_t x) {
  80     return
  81         x == PA_STREAM_CREATING ||
  82         x == PA_STREAM_READY;
  83 }
  84
  85 /** \cond fulldocs */
  86 #define PA_STREAM_UNCONNECTED PA_STREAM_UNCONNECTED
  87 #define PA_STREAM_CREATING PA_STREAM_CREATING
  88 #define PA_STREAM_READY PA_STREAM_READY
  89 #define PA_STREAM_FAILED PA_STREAM_FAILED
  90 #define PA_STREAM_TERMINATED PA_STREAM_TERMINATED
  91 #define PA_STREAM_IS_GOOD PA_STREAM_IS_GOOD
  92 /** \endcond */
  93
  94 /** The state of an operation */
  95 typedef enum pa_operation_state {
  96     PA_OPERATION_RUNNING,
  97     /**< The operation is still running */
  98     PA_OPERATION_DONE,
  99     /**< The operation has completed */
 100     PA_OPERATION_CANCELLED
 101     /**< The operation has been cancelled. Operations may get cancelled by the
 102      * application, or as a result of the context getting disconneted while the
 103      * operation is pending. */
 104 } pa_operation_state_t;
 105
 106 /** \cond fulldocs */
 107 #define PA_OPERATION_RUNNING PA_OPERATION_RUNNING
 108 #define PA_OPERATION_DONE PA_OPERATION_DONE
 109 #define PA_OPERATION_CANCELED PA_OPERATION_CANCELLED
 110 #define PA_OPERATION_CANCELLED PA_OPERATION_CANCELLED
 111 /** \endcond */
 112
 113 /** An invalid index */
 114 #define PA_INVALID_INDEX ((uint32_t) -1)
 115
 116 /** Some special flags for contexts. */
 117 typedef enum pa_context_flags {
 118     PA_CONTEXT_NOFLAGS = 0x0000U,
 119     /**< Flag to pass when no specific options are needed (used to avoid casting)  \since 0.9.19 */
 120     PA_CONTEXT_NOAUTOSPAWN = 0x0001U,
 121     /**< Disabled autospawning of the PulseAudio daemon if required */
 122     PA_CONTEXT_NOFAIL = 0x0002U
 123     /**< Don't fail if the daemon is not available when pa_context_connect() is called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon to appear.  \since 0.9.15 */
 124 } pa_context_flags_t;
 125
 126 /** \cond fulldocs */
 127 /* Allow clients to check with #ifdef for those flags */
 128 #define PA_CONTEXT_NOAUTOSPAWN PA_CONTEXT_NOAUTOSPAWN
 129 #define PA_CONTEXT_NOFAIL PA_CONTEXT_NOFAIL
 130 /** \endcond */
 131
 132 /** Direction bitfield - while we currently do not expose anything bidirectional,
 133   one should test against the bit instead of the value (e.g.\ if (d & PA_DIRECTION_OUTPUT)),
 134   because we might add bidirectional stuff in the future. \since 2.0
 135 */
 136 typedef enum pa_direction {
 137     PA_DIRECTION_OUTPUT = 0x0001U,  /**< Output direction */
 138     PA_DIRECTION_INPUT = 0x0002U    /**< Input direction */
 139 } pa_direction_t;
 140
 141 /** \cond fulldocs */
 142 #define PA_DIRECTION_OUTPUT PA_DIRECTION_OUTPUT
 143 #define PA_DIRECTION_INPUT PA_DIRECTION_INPUT
 144 /** \endcond */
 145
 146 /** The type of device we are dealing with */
 147 typedef enum pa_device_type {
 148     PA_DEVICE_TYPE_SINK,     /**< Playback device */
 149     PA_DEVICE_TYPE_SOURCE    /**< Recording device */
 150 } pa_device_type_t;
 151
 152 /** \cond fulldocs */
 153 #define PA_DEVICE_TYPE_SINK PA_DEVICE_TYPE_SINK
 154 #define PA_DEVICE_TYPE_SOURCE PA_DEVICE_TYPE_SOURCE
 155 /** \endcond */
 156
 157 /** The direction of a pa_stream object */
 158 typedef enum pa_stream_direction {
 159     PA_STREAM_NODIRECTION,   /**< Invalid direction */
 160     PA_STREAM_PLAYBACK,      /**< Playback stream */
 161     PA_STREAM_RECORD,        /**< Record stream */
 162     PA_STREAM_UPLOAD         /**< Sample upload stream */
 163 } pa_stream_direction_t;
 164
 165 /** \cond fulldocs */
 166 #define PA_STREAM_NODIRECTION PA_STREAM_NODIRECTION
 167 #define PA_STREAM_PLAYBACK PA_STREAM_PLAYBACK
 168 #define PA_STREAM_RECORD PA_STREAM_RECORD
 169 #define PA_STREAM_UPLOAD PA_STREAM_UPLOAD
 170 /** \endcond */
 171
 172 /** Some special flags for stream connections. */
 173 typedef enum pa_stream_flags {
 174
 175     PA_STREAM_NOFLAGS = 0x0000U,
 176     /**< Flag to pass when no specific options are needed (used to avoid casting)  \since 0.9.19 */
 177
 178     PA_STREAM_START_CORKED = 0x0001U,
 179     /**< Create the stream corked, requiring an explicit
 180      * pa_stream_cork() call to uncork it. */
 181
 182     PA_STREAM_INTERPOLATE_TIMING = 0x0002U,
 183     /**< Interpolate the latency for this stream. When enabled,
 184      * pa_stream_get_latency() and pa_stream_get_time() will try to
 185      * estimate the current record/playback time based on the local
 186      * time that passed since the last timing info update.  Using this
 187      * option has the advantage of not requiring a whole roundtrip
 188      * when the current playback/recording time is needed. Consider
 189      * using this option when requesting latency information
 190      * frequently. This is especially useful on long latency network
 191      * connections. It makes a lot of sense to combine this option
 192      * with PA_STREAM_AUTO_TIMING_UPDATE. */
 193
 194     PA_STREAM_NOT_MONOTONIC = 0x0004U,
 195     /**< Don't force the time to increase monotonically. If this
 196      * option is enabled, pa_stream_get_time() will not necessarily
 197      * return always monotonically increasing time values on each
 198      * call. This may confuse applications which cannot deal with time
 199      * going 'backwards', but has the advantage that bad transport
 200      * latency estimations that caused the time to to jump ahead can
 201      * be corrected quickly, without the need to wait. (Please note
 202      * that this flag was named PA_STREAM_NOT_MONOTONOUS in releases
 203      * prior to 0.9.11. The old name is still defined too, for
 204      * compatibility reasons. */
 205
 206     PA_STREAM_AUTO_TIMING_UPDATE = 0x0008U,
 207     /**< If set timing update requests are issued periodically
 208      * automatically. Combined with PA_STREAM_INTERPOLATE_TIMING you
 209      * will be able to query the current time and latency with
 210      * pa_stream_get_time() and pa_stream_get_latency() at all times
 211      * without a packet round trip.*/
 212
 213     PA_STREAM_NO_REMAP_CHANNELS = 0x0010U,
 214     /**< Don't remap channels by their name, instead map them simply
 215      * by their index. Implies PA_STREAM_NO_REMIX_CHANNELS. Only
 216      * supported when the server is at least PA 0.9.8. It is ignored
 217      * on older servers.\since 0.9.8 */
 218
 219     PA_STREAM_NO_REMIX_CHANNELS = 0x0020U,
 220     /**< When remapping channels by name, don't upmix or downmix them
 221      * to related channels. Copy them into matching channels of the
 222      * device 1:1. Only supported when the server is at least PA
 223      * 0.9.8. It is ignored on older servers. \since 0.9.8 */
 224
 225     PA_STREAM_FIX_FORMAT = 0x0040U,
 226     /**< Use the sample format of the sink/device this stream is being
 227      * connected to, and possibly ignore the format the sample spec
 228      * contains -- but you still have to pass a valid value in it as a
 229      * hint to PulseAudio what would suit your stream best. If this is
 230      * used you should query the used sample format after creating the
 231      * stream by using pa_stream_get_sample_spec(). Also, if you
 232      * specified manual buffer metrics it is recommended to update
 233      * them with pa_stream_set_buffer_attr() to compensate for the
 234      * changed frame sizes. Only supported when the server is at least
 235      * PA 0.9.8. It is ignored on older servers.
 236      *
 237      * When creating streams with pa_stream_new_extended(), this flag has no
 238      * effect. If you specify a format with PCM encoding, and you want the
 239      * server to choose the sample format, then you should leave the sample
 240      * format unspecified in the pa_format_info object. This also means that
 241      * you can't use pa_format_info_from_sample_spec(), because that function
 242      * always sets the sample format.
 243      *
 244      * \since 0.9.8 */
 245
 246     PA_STREAM_FIX_RATE = 0x0080U,
 247     /**< Use the sample rate of the sink, and possibly ignore the rate
 248      * the sample spec contains. Usage similar to
 249      * PA_STREAM_FIX_FORMAT. Only supported when the server is at least
 250      * PA 0.9.8. It is ignored on older servers.
 251      *
 252      * When creating streams with pa_stream_new_extended(), this flag has no
 253      * effect. If you specify a format with PCM encoding, and you want the
 254      * server to choose the sample rate, then you should leave the rate
 255      * unspecified in the pa_format_info object. This also means that you can't
 256      * use pa_format_info_from_sample_spec(), because that function always sets
 257      * the sample rate.
 258      *
 259      * \since 0.9.8 */
 260
 261     PA_STREAM_FIX_CHANNELS = 0x0100,
 262     /**< Use the number of channels and the channel map of the sink,
 263      * and possibly ignore the number of channels and the map the
 264      * sample spec and the passed channel map contains. Usage similar
 265      * to PA_STREAM_FIX_FORMAT. Only supported when the server is at
 266      * least PA 0.9.8. It is ignored on older servers.
 267      *
 268      * When creating streams with pa_stream_new_extended(), this flag has no
 269      * effect. If you specify a format with PCM encoding, and you want the
 270      * server to choose the channel count and/or channel map, then you should
 271      * leave the channels and/or the channel map unspecified in the
 272      * pa_format_info object. This also means that you can't use
 273      * pa_format_info_from_sample_spec(), because that function always sets
 274      * the channel count (but if you only want to leave the channel map
 275      * unspecified, then pa_format_info_from_sample_spec() works, because it
 276      * accepts a NULL channel map).
 277      *
 278      * \since 0.9.8 */
 279
 280     PA_STREAM_DONT_MOVE = 0x0200U,
 281     /**< Don't allow moving of this stream to another
 282      * sink/device. Useful if you use any of the PA_STREAM_FIX_ flags
 283      * and want to make sure that resampling never takes place --
 284      * which might happen if the stream is moved to another
 285      * sink/source with a different sample spec/channel map. Only
 286      * supported when the server is at least PA 0.9.8. It is ignored
 287      * on older servers. \since 0.9.8 */
 288
 289     PA_STREAM_VARIABLE_RATE = 0x0400U,
 290     /**< Allow dynamic changing of the sampling rate during playback
 291      * with pa_stream_update_sample_rate(). Only supported when the
 292      * server is at least PA 0.9.8. It is ignored on older
 293      * servers. \since 0.9.8 */
 294
 295     PA_STREAM_PEAK_DETECT = 0x0800U,
 296     /**< Find peaks instead of resampling. \since 0.9.11 */
 297
 298     PA_STREAM_START_MUTED = 0x1000U,
 299     /**< Create in muted state. If neither PA_STREAM_START_UNMUTED nor
 300      * PA_STREAM_START_MUTED it is left to the server to decide
 301      * whether to create the stream in muted or in unmuted
 302      * state. \since 0.9.11 */
 303
 304     PA_STREAM_ADJUST_LATENCY = 0x2000U,
 305     /**< Try to adjust the latency of the sink/source based on the
 306      * requested buffer metrics and adjust buffer metrics
 307      * accordingly. Also see pa_buffer_attr. This option may not be
 308      * specified at the same time as PA_STREAM_EARLY_REQUESTS. \since
 309      * 0.9.11 */
 310
 311     PA_STREAM_EARLY_REQUESTS = 0x4000U,
 312     /**< Enable compatibility mode for legacy clients that rely on a
 313      * "classic" hardware device fragment-style playback model. If
 314      * this option is set, the minreq value of the buffer metrics gets
 315      * a new meaning: instead of just specifying that no requests
 316      * asking for less new data than this value will be made to the
 317      * client it will also guarantee that requests are generated as
 318      * early as this limit is reached. This flag should only be set in
 319      * very few situations where compatibility with a fragment-based
 320      * playback model needs to be kept and the client applications
 321      * cannot deal with data requests that are delayed to the latest
 322      * moment possible. (Usually these are programs that use usleep()
 323      * or a similar call in their playback loops instead of sleeping
 324      * on the device itself.) Also see pa_buffer_attr. This option may
 325      * not be specified at the same time as
 326      * PA_STREAM_ADJUST_LATENCY. \since 0.9.12 */
 327
 328     PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND = 0x8000U,
 329     /**< If set this stream won't be taken into account when it is
 330      * checked whether the device this stream is connected to should
 331      * auto-suspend. \since 0.9.15 */
 332
 333     PA_STREAM_START_UNMUTED = 0x10000U,
 334     /**< Create in unmuted state. If neither PA_STREAM_START_UNMUTED
 335      * nor PA_STREAM_START_MUTED it is left to the server to decide
 336      * whether to create the stream in muted or in unmuted
 337      * state. \since 0.9.15 */
 338
 339     PA_STREAM_FAIL_ON_SUSPEND = 0x20000U,
 340     /**< If the sink/source this stream is connected to is suspended
 341      * during the creation of this stream, cause it to fail. If the
 342      * sink/source is being suspended during creation of this stream,
 343      * make sure this stream is terminated. \since 0.9.15 */
 344
 345     PA_STREAM_RELATIVE_VOLUME = 0x40000U,
 346     /**< If a volume is passed when this stream is created, consider
 347      * it relative to the sink's current volume, never as absolute
 348      * device volume. If this is not specified the volume will be
 349      * consider absolute when the sink is in flat volume mode,
 350      * relative otherwise. \since 0.9.20 */
 351
 352     PA_STREAM_PASSTHROUGH = 0x80000U,
 353     /**< Used to tag content that will be rendered by passthrough sinks.
 354      * The data will be left as is and not reformatted, resampled.
 355      * \since 1.0 */
 356
 357     PA_STREAM_START_RAMP_MUTED = 0x100000U
 358     /**< Used to tag content that the stream will be started ramp volume
 359      * muted so that you can nicely fade it in */
 360
 361 } pa_stream_flags_t;
 362
 363 /** \cond fulldocs */
 364
 365 /* English is an evil language */
 366 #define PA_STREAM_NOT_MONOTONOUS PA_STREAM_NOT_MONOTONIC
 367
 368 /* Allow clients to check with #ifdef for those flags */
 369 #define PA_STREAM_START_CORKED PA_STREAM_START_CORKED
 370 #define PA_STREAM_INTERPOLATE_TIMING PA_STREAM_INTERPOLATE_TIMING
 371 #define PA_STREAM_NOT_MONOTONIC PA_STREAM_NOT_MONOTONIC
 372 #define PA_STREAM_AUTO_TIMING_UPDATE PA_STREAM_AUTO_TIMING_UPDATE
 373 #define PA_STREAM_NO_REMAP_CHANNELS PA_STREAM_NO_REMAP_CHANNELS
 374 #define PA_STREAM_NO_REMIX_CHANNELS PA_STREAM_NO_REMIX_CHANNELS
 375 #define PA_STREAM_FIX_FORMAT PA_STREAM_FIX_FORMAT
 376 #define PA_STREAM_FIX_RATE PA_STREAM_FIX_RATE
 377 #define PA_STREAM_FIX_CHANNELS PA_STREAM_FIX_CHANNELS
 378 #define PA_STREAM_DONT_MOVE PA_STREAM_DONT_MOVE
 379 #define PA_STREAM_VARIABLE_RATE PA_STREAM_VARIABLE_RATE
 380 #define PA_STREAM_PEAK_DETECT PA_STREAM_PEAK_DETECT
 381 #define PA_STREAM_START_MUTED PA_STREAM_START_MUTED
 382 #define PA_STREAM_ADJUST_LATENCY PA_STREAM_ADJUST_LATENCY
 383 #define PA_STREAM_EARLY_REQUESTS PA_STREAM_EARLY_REQUESTS
 384 #define PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND PA_STREAM_DONT_INHIBIT_AUTO_SUSPEND
 385 #define PA_STREAM_START_UNMUTED PA_STREAM_START_UNMUTED
 386 #define PA_STREAM_FAIL_ON_SUSPEND PA_STREAM_FAIL_ON_SUSPEND
 387 #define PA_STREAM_RELATIVE_VOLUME PA_STREAM_RELATIVE_VOLUME
 388 #define PA_STREAM_PASSTHROUGH PA_STREAM_PASSTHROUGH
 389 #define PA_STREAM_START_RAMP_MUTED PA_STREAM_START_RAMP_MUTED
 390
 391 /** \endcond */
 392
 393 /** Playback and record buffer metrics */
 394 typedef struct pa_buffer_attr {
 395     uint32_t maxlength;
 396     /**< Maximum length of the buffer in bytes. Setting this to (uint32_t) -1
 397      * will initialize this to the maximum value supported by server,
 398      * which is recommended.
 399      *
 400      * In strict low-latency playback scenarios you might want to set this to
 401      * a lower value, likely together with the PA_STREAM_ADJUST_LATENCY flag.
 402      * If you do so, you ensure that the latency doesn't grow beyond what is
 403      * acceptable for the use case, at the cost of getting more underruns if
 404      * the latency is lower than what the server can reliably handle. */
 405
 406     uint32_t tlength;
 407     /**< Playback only: target length of the buffer. The server tries
 408      * to assure that at least tlength bytes are always available in
 409      * the per-stream server-side playback buffer. It is recommended
 410      * to set this to (uint32_t) -1, which will initialize this to a
 411      * value that is deemed sensible by the server. However, this
 412      * value will default to something like 2s, i.e. for applications
 413      * that have specific latency requirements this value should be
 414      * set to the maximum latency that the application can deal
 415      * with. When PA_STREAM_ADJUST_LATENCY is not set this value will
 416      * influence only the per-stream playback buffer size. When
 417      * PA_STREAM_ADJUST_LATENCY is set the overall latency of the sink
 418      * plus the playback buffer size is configured to this value. Set
 419      * PA_STREAM_ADJUST_LATENCY if you are interested in adjusting the
 420      * overall latency. Don't set it if you are interested in
 421      * configuring the server-side per-stream playback buffer
 422      * size. */
 423
 424     uint32_t prebuf;
 425     /**< Playback only: pre-buffering. The server does not start with
 426      * playback before at least prebuf bytes are available in the
 427      * buffer. It is recommended to set this to (uint32_t) -1, which
 428      * will initialize this to the same value as tlength, whatever
 429      * that may be. Initialize to 0 to enable manual start/stop
 430      * control of the stream. This means that playback will not stop
 431      * on underrun and playback will not start automatically. Instead
 432      * pa_stream_cork() needs to be called explicitly. If you set
 433      * this value to 0 you should also set PA_STREAM_START_CORKED. */
 434
 435     uint32_t minreq;
 436     /**< Playback only: minimum request. The server does not request
 437      * less than minreq bytes from the client, instead waits until the
 438      * buffer is free enough to request more bytes at once. It is
 439      * recommended to set this to (uint32_t) -1, which will initialize
 440      * this to a value that is deemed sensible by the server. This
 441      * should be set to a value that gives PulseAudio enough time to
 442      * move the data from the per-stream playback buffer into the
 443      * hardware playback buffer. */
 444
 445     uint32_t fragsize;
 446     /**< Recording only: fragment size. The server sends data in
 447      * blocks of fragsize bytes size. Large values diminish
 448      * interactivity with other operations on the connection context
 449      * but decrease control overhead. It is recommended to set this to
 450      * (uint32_t) -1, which will initialize this to a value that is
 451      * deemed sensible by the server. However, this value will default
 452      * to something like 2s, i.e. for applications that have specific
 453      * latency requirements this value should be set to the maximum
 454      * latency that the application can deal with. If
 455      * PA_STREAM_ADJUST_LATENCY is set the overall source latency will
 456      * be adjusted according to this value. If it is not set the
 457      * source latency is left unmodified. */
 458
 459 } pa_buffer_attr;
 460
 461 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
 462 typedef enum pa_error_code {
 463     PA_OK = 0,                     /**< No error */
 464     PA_ERR_ACCESS,                 /**< Access failure */
 465     PA_ERR_COMMAND,                /**< Unknown command */
 466     PA_ERR_INVALID,                /**< Invalid argument */
 467     PA_ERR_EXIST,                  /**< Entity exists */
 468     PA_ERR_NOENTITY,               /**< No such entity */
 469     PA_ERR_CONNECTIONREFUSED,      /**< Connection refused */
 470     PA_ERR_PROTOCOL,               /**< Protocol error */
 471     PA_ERR_TIMEOUT,                /**< Timeout */
 472     PA_ERR_AUTHKEY,                /**< No authorization key */
 473     PA_ERR_INTERNAL,               /**< Internal error */
 474     PA_ERR_CONNECTIONTERMINATED,   /**< Connection terminated */
 475     PA_ERR_KILLED,                 /**< Entity killed */
 476     PA_ERR_INVALIDSERVER,          /**< Invalid server */
 477     PA_ERR_MODINITFAILED,          /**< Module initialization failed */
 478     PA_ERR_BADSTATE,               /**< Bad state */
 479     PA_ERR_NODATA,                 /**< No data */
 480     PA_ERR_VERSION,                /**< Incompatible protocol version */
 481     PA_ERR_TOOLARGE,               /**< Data too large */
 482     PA_ERR_NOTSUPPORTED,           /**< Operation not supported \since 0.9.5 */
 483     PA_ERR_UNKNOWN,                /**< The error code was unknown to the client */
 484     PA_ERR_NOEXTENSION,            /**< Extension does not exist. \since 0.9.12 */
 485     PA_ERR_OBSOLETE,               /**< Obsolete functionality. \since 0.9.15 */
 486     PA_ERR_NOTIMPLEMENTED,         /**< Missing implementation. \since 0.9.15 */
 487     PA_ERR_FORKED,                 /**< The caller forked without calling execve() and tried to reuse the context. \since 0.9.15 */
 488     PA_ERR_IO,                     /**< An IO error happened. \since 0.9.16 */
 489     PA_ERR_BUSY,                   /**< Device or resource busy. \since 0.9.17 */
 490     PA_ERR_MAX                     /**< Not really an error but the first invalid error code */
 491 } pa_error_code_t;
 492
 493 /** \cond fulldocs */
 494 #define PA_OK PA_OK
 495 #define PA_ERR_ACCESS PA_ERR_ACCESS
 496 #define PA_ERR_COMMAND PA_ERR_COMMAND
 497 #define PA_ERR_INVALID PA_ERR_INVALID
 498 #define PA_ERR_EXIST PA_ERR_EXIST
 499 #define PA_ERR_NOENTITY PA_ERR_NOENTITY
 500 #define PA_ERR_CONNECTIONREFUSED PA_ERR_CONNECTIONREFUSED
 501 #define PA_ERR_PROTOCOL PA_ERR_PROTOCOL
 502 #define PA_ERR_TIMEOUT PA_ERR_TIMEOUT
 503 #define PA_ERR_AUTHKEY PA_ERR_AUTHKEY
 504 #define PA_ERR_INTERNAL PA_ERR_INTERNAL
 505 #define PA_ERR_CONNECTIONTERMINATED PA_ERR_CONNECTIONTERMINATED
 506 #define PA_ERR_KILLED PA_ERR_KILLED
 507 #define PA_ERR_INVALIDSERVER PA_ERR_INVALIDSERVER
 508 #define PA_ERR_MODINITFAILED PA_ERR_MODINITFAILED
 509 #define PA_ERR_BADSTATE PA_ERR_BADSTATE
 510 #define PA_ERR_NODATA PA_ERR_NODATA
 511 #define PA_ERR_VERSION PA_ERR_VERSION
 512 #define PA_ERR_TOOLARGE PA_ERR_TOOLARGE
 513 #define PA_ERR_NOTSUPPORTED PA_ERR_NOTSUPPORTED
 514 #define PA_ERR_UNKNOWN PA_ERR_UNKNOWN
 515 #define PA_ERR_NOEXTENSION PA_ERR_NOEXTENSION
 516 #define PA_ERR_OBSOLETE PA_ERR_OBSOLETE
 517 #define PA_ERR_NOTIMPLEMENTED PA_ERR_NOTIMPLEMENTED
 518 #define PA_ERR_FORKED PA_ERR_FORKED
 519 #define PA_ERR_MAX PA_ERR_MAX
 520 /** \endcond */
 521
 522 /** Subscription event mask, as used by pa_context_subscribe() */
 523 typedef enum pa_subscription_mask {
 524     PA_SUBSCRIPTION_MASK_NULL = 0x0000U,
 525     /**< No events */
 526
 527     PA_SUBSCRIPTION_MASK_SINK = 0x0001U,
 528     /**< Sink events */
 529
 530     PA_SUBSCRIPTION_MASK_SOURCE = 0x0002U,
 531     /**< Source events */
 532
 533     PA_SUBSCRIPTION_MASK_SINK_INPUT = 0x0004U,
 534     /**< Sink input events */
 535
 536     PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 0x0008U,
 537     /**< Source output events */
 538
 539     PA_SUBSCRIPTION_MASK_MODULE = 0x0010U,
 540     /**< Module events */
 541
 542     PA_SUBSCRIPTION_MASK_CLIENT = 0x0020U,
 543     /**< Client events */
 544
 545     PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 0x0040U,
 546     /**< Sample cache events */
 547
 548     PA_SUBSCRIPTION_MASK_SERVER = 0x0080U,
 549     /**< Other global server changes. */
 550
 551 /** \cond fulldocs */
 552     PA_SUBSCRIPTION_MASK_AUTOLOAD = 0x0100U,
 553     /**< \deprecated Autoload table events. */
 554 /** \endcond */
 555
 556     PA_SUBSCRIPTION_MASK_CARD = 0x0200U,
 557     /**< Card events. \since 0.9.15 */
 558
 559     PA_SUBSCRIPTION_MASK_ALL = 0x02ffU
 560     /**< Catch all events */
 561 } pa_subscription_mask_t;
 562
 563 /** Subscription event types, as used by pa_context_subscribe() */
 564 typedef enum pa_subscription_event_type {
 565     PA_SUBSCRIPTION_EVENT_SINK = 0x0000U,
 566     /**< Event type: Sink */
 567
 568     PA_SUBSCRIPTION_EVENT_SOURCE = 0x0001U,
 569     /**< Event type: Source */
 570
 571     PA_SUBSCRIPTION_EVENT_SINK_INPUT = 0x0002U,
 572     /**< Event type: Sink input */
 573
 574     PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 0x0003U,
 575     /**< Event type: Source output */
 576
 577     PA_SUBSCRIPTION_EVENT_MODULE = 0x0004U,
 578     /**< Event type: Module */
 579
 580     PA_SUBSCRIPTION_EVENT_CLIENT = 0x0005U,
 581     /**< Event type: Client */
 582
 583     PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 0x0006U,
 584     /**< Event type: Sample cache item */
 585
 586     PA_SUBSCRIPTION_EVENT_SERVER = 0x0007U,
 587     /**< Event type: Global server change, only occurring with PA_SUBSCRIPTION_EVENT_CHANGE. */
 588
 589 /** \cond fulldocs */
 590     PA_SUBSCRIPTION_EVENT_AUTOLOAD = 0x0008U,
 591     /**< \deprecated Event type: Autoload table changes. */
 592 /** \endcond */
 593
 594     PA_SUBSCRIPTION_EVENT_CARD = 0x0009U,
 595     /**< Event type: Card \since 0.9.15 */
 596
 597     PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 0x000FU,
 598     /**< A mask to extract the event type from an event value */
 599
 600     PA_SUBSCRIPTION_EVENT_NEW = 0x0000U,
 601     /**< A new object was created */
 602
 603     PA_SUBSCRIPTION_EVENT_CHANGE = 0x0010U,
 604     /**< A property of the object was modified */
 605
 606     PA_SUBSCRIPTION_EVENT_REMOVE = 0x0020U,
 607     /**< An object was removed */
 608
 609     PA_SUBSCRIPTION_EVENT_TYPE_MASK = 0x0030U
 610     /**< A mask to extract the event operation from an event value */
 611
 612 } pa_subscription_event_type_t;
 613
 614 /** Return one if an event type t matches an event mask bitfield */
 615 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
 616
 617 /** \cond fulldocs */
 618 #define PA_SUBSCRIPTION_MASK_NULL PA_SUBSCRIPTION_MASK_NULL
 619 #define PA_SUBSCRIPTION_MASK_SINK PA_SUBSCRIPTION_MASK_SINK
 620 #define PA_SUBSCRIPTION_MASK_SOURCE PA_SUBSCRIPTION_MASK_SOURCE
 621 #define PA_SUBSCRIPTION_MASK_SINK_INPUT PA_SUBSCRIPTION_MASK_SINK_INPUT
 622 #define PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT
 623 #define PA_SUBSCRIPTION_MASK_MODULE PA_SUBSCRIPTION_MASK_MODULE
 624 #define PA_SUBSCRIPTION_MASK_CLIENT PA_SUBSCRIPTION_MASK_CLIENT
 625 #define PA_SUBSCRIPTION_MASK_SAMPLE_CACHE PA_SUBSCRIPTION_MASK_SAMPLE_CACHE
 626 #define PA_SUBSCRIPTION_MASK_SERVER PA_SUBSCRIPTION_MASK_SERVER
 627 #define PA_SUBSCRIPTION_MASK_AUTOLOAD PA_SUBSCRIPTION_MASK_AUTOLOAD
 628 #define PA_SUBSCRIPTION_MASK_CARD PA_SUBSCRIPTION_MASK_CARD
 629 #define PA_SUBSCRIPTION_MASK_ALL PA_SUBSCRIPTION_MASK_ALL
 630 #define PA_SUBSCRIPTION_EVENT_SINK PA_SUBSCRIPTION_EVENT_SINK
 631 #define PA_SUBSCRIPTION_EVENT_SOURCE PA_SUBSCRIPTION_EVENT_SOURCE
 632 #define PA_SUBSCRIPTION_EVENT_SINK_INPUT PA_SUBSCRIPTION_EVENT_SINK_INPUT
 633 #define PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT
 634 #define PA_SUBSCRIPTION_EVENT_MODULE PA_SUBSCRIPTION_EVENT_MODULE
 635 #define PA_SUBSCRIPTION_EVENT_CLIENT PA_SUBSCRIPTION_EVENT_CLIENT
 636 #define PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE
 637 #define PA_SUBSCRIPTION_EVENT_SERVER PA_SUBSCRIPTION_EVENT_SERVER
 638 #define PA_SUBSCRIPTION_EVENT_AUTOLOAD PA_SUBSCRIPTION_EVENT_AUTOLOAD
 639 #define PA_SUBSCRIPTION_EVENT_CARD PA_SUBSCRIPTION_EVENT_CARD
 640 #define PA_SUBSCRIPTION_EVENT_FACILITY_MASK PA_SUBSCRIPTION_EVENT_FACILITY_MASK
 641 #define PA_SUBSCRIPTION_EVENT_NEW PA_SUBSCRIPTION_EVENT_NEW
 642 #define PA_SUBSCRIPTION_EVENT_CHANGE PA_SUBSCRIPTION_EVENT_CHANGE
 643 #define PA_SUBSCRIPTION_EVENT_REMOVE PA_SUBSCRIPTION_EVENT_REMOVE
 644 #define PA_SUBSCRIPTION_EVENT_TYPE_MASK PA_SUBSCRIPTION_EVENT_TYPE_MASK
 645 /** \endcond */
 646
 647 /** A structure for all kinds of timing information of a stream. See
 648  * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
 649  * total output latency a sample that is written with
 650  * pa_stream_write() takes to be played may be estimated by
 651  * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
 652  * as pa_bytes_to_usec(write_index-read_index)) The output buffer
 653  * which buffer_usec relates to may be manipulated freely (with
 654  * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
 655  * the buffers sink_usec and source_usec relate to are first-in
 656  * first-out (FIFO) buffers which cannot be flushed or manipulated in
 657  * any way. The total input latency a sample that is recorded takes to
 658  * be delivered to the application is:
 659  * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
 660  * sign issues!) When connected to a monitor source sink_usec contains
 661  * the latency of the owning sink. The two latency estimations
 662  * described here are implemented in pa_stream_get_latency(). Please
 663  * note that this structure can be extended as part of evolutionary
 664  * API updates at any time in any new release.*/
 665 typedef struct pa_timing_info {
 666     struct timeval timestamp;
 667     /**< The time when this timing info structure was current */
 668
 669     int synchronized_clocks;
 670     /**< Non-zero if the local and the remote machine have
 671      * synchronized clocks. If synchronized clocks are detected
 672      * transport_usec becomes much more reliable. However, the code
 673      * that detects synchronized clocks is very limited and unreliable
 674      * itself. */
 675
 676     pa_usec_t sink_usec;
 677     /**< Time in usecs a sample takes to be played on the sink. For
 678      * playback streams and record streams connected to a monitor
 679      * source. */
 680
 681     pa_usec_t source_usec;
 682     /**< Time in usecs a sample takes from being recorded to being
 683      * delivered to the application. Only for record streams. */
 684
 685     pa_usec_t transport_usec;
 686     /**< Estimated time in usecs a sample takes to be transferred
 687      * to/from the daemon. For both playback and record streams. */
 688
 689     int playing;
 690     /**< Non-zero when the stream is currently not underrun and data
 691      * is being passed on to the device. Only for playback
 692      * streams. This field does not say whether the data is actually
 693      * already being played. To determine this check whether
 694      * since_underrun (converted to usec) is larger than sink_usec.*/
 695
 696     int write_index_corrupt;
 697     /**< Non-zero if write_index is not up-to-date because a local
 698      * write command that corrupted it has been issued in the time
 699      * since this latency info was current . Only write commands with
 700      * SEEK_RELATIVE_ON_READ and SEEK_RELATIVE_END can corrupt
 701      * write_index. */
 702
 703     int64_t write_index;
 704     /**< Current write index into the playback buffer in bytes. Think
 705      * twice before using this for seeking purposes: it might be out
 706      * of date a the time you want to use it. Consider using
 707      * PA_SEEK_RELATIVE instead. */
 708
 709     int read_index_corrupt;
 710     /**< Non-zero if read_index is not up-to-date because a local
 711      * pause or flush request that corrupted it has been issued in the
 712      * time since this latency info was current. */
 713
 714     int64_t read_index;
 715     /**< Current read index into the playback buffer in bytes. Think
 716      * twice before using this for seeking purposes: it might be out
 717      * of date a the time you want to use it. Consider using
 718      * PA_SEEK_RELATIVE_ON_READ instead. */
 719
 720     pa_usec_t configured_sink_usec;
 721     /**< The configured latency for the sink. \since 0.9.11 */
 722
 723     pa_usec_t configured_source_usec;
 724     /**< The configured latency for the source. \since 0.9.11 */
 725
 726     int64_t since_underrun;
 727     /**< Bytes that were handed to the sink since the last underrun
 728      * happened, or since playback started again after the last
 729      * underrun. playing will tell you which case it is. \since
 730      * 0.9.11 */
 731
 732 } pa_timing_info;
 733
 734 /** A structure for the spawn api. This may be used to integrate auto
 735  * spawned daemons into your application. For more information see
 736  * pa_context_connect(). When spawning a new child process the
 737  * waitpid() is used on the child's PID. The spawn routine will not
 738  * block or ignore SIGCHLD signals, since this cannot be done in a
 739  * thread compatible way. You might have to do this in
 740  * prefork/postfork. */
 741 typedef struct pa_spawn_api {
 742     void (*prefork)(void);
 743     /**< Is called just before the fork in the parent process. May be
 744      * NULL. */
 745
 746     void (*postfork)(void);
 747     /**< Is called immediately after the fork in the parent
 748      * process. May be NULL.*/
 749
 750     void (*atfork)(void);
 751     /**< Is called immediately after the fork in the child
 752      * process. May be NULL. It is not safe to close all file
 753      * descriptors in this function unconditionally, since a UNIX
 754      * socket (created using socketpair()) is passed to the new
 755      * process. */
 756 } pa_spawn_api;
 757
 758 /** Seek type for pa_stream_write(). */
 759 typedef enum pa_seek_mode {
 760     PA_SEEK_RELATIVE = 0,
 761     /**< Seek relatively to the write index */
 762
 763     PA_SEEK_ABSOLUTE = 1,
 764     /**< Seek relatively to the start of the buffer queue */
 765
 766     PA_SEEK_RELATIVE_ON_READ = 2,
 767     /**< Seek relatively to the read index.  */
 768
 769     PA_SEEK_RELATIVE_END = 3
 770     /**< Seek relatively to the current end of the buffer queue. */
 771 } pa_seek_mode_t;
 772
 773 /** \cond fulldocs */
 774 #define PA_SEEK_RELATIVE PA_SEEK_RELATIVE
 775 #define PA_SEEK_ABSOLUTE PA_SEEK_ABSOLUTE
 776 #define PA_SEEK_RELATIVE_ON_READ PA_SEEK_RELATIVE_ON_READ
 777 #define PA_SEEK_RELATIVE_END PA_SEEK_RELATIVE_END
 778 /** \endcond */
 779
 780 /** Special sink flags. */
 781 typedef enum pa_sink_flags {
 782     PA_SINK_NOFLAGS = 0x0000U,
 783     /**< Flag to pass when no specific options are needed (used to avoid casting)  \since 0.9.19 */
 784
 785     PA_SINK_HW_VOLUME_CTRL = 0x0001U,
 786     /**< Supports hardware volume control. This is a dynamic flag and may
 787      * change at runtime after the sink has initialized */
 788
 789     PA_SINK_LATENCY = 0x0002U,
 790     /**< Supports latency querying */
 791
 792     PA_SINK_HARDWARE = 0x0004U,
 793     /**< Is a hardware sink of some kind, in contrast to
 794      * "virtual"/software sinks \since 0.9.3 */
 795
 796     PA_SINK_NETWORK = 0x0008U,
 797     /**< Is a networked sink of some kind. \since 0.9.7 */
 798
 799     PA_SINK_HW_MUTE_CTRL = 0x0010U,
 800     /**< Supports hardware mute control. This is a dynamic flag and may
 801      * change at runtime after the sink has initialized \since 0.9.11 */
 802
 803     PA_SINK_DECIBEL_VOLUME = 0x0020U,
 804     /**< Volume can be translated to dB with pa_sw_volume_to_dB(). This is a
 805      * dynamic flag and may change at runtime after the sink has initialized
 806      * \since 0.9.11 */
 807
 808     PA_SINK_FLAT_VOLUME = 0x0040U,
 809     /**< This sink is in flat volume mode, i.e.\ always the maximum of
 810      * the volume of all connected inputs. \since 0.9.15 */
 811
 812     PA_SINK_DYNAMIC_LATENCY = 0x0080U,
 813     /**< The latency can be adjusted dynamically depending on the
 814      * needs of the connected streams. \since 0.9.15 */
 815
 816     PA_SINK_SET_FORMATS = 0x0100U,
 817     /**< The sink allows setting what formats are supported by the connected
 818      * hardware. The actual functionality to do this might be provided by an
 819      * extension. \since 1.0 */
 820
 821 #ifdef __INCLUDED_FROM_PULSE_AUDIO
 822 /** \cond fulldocs */
 823     /* PRIVATE: Server-side values -- do not try to use these at client-side.
 824      * The server will filter out these flags anyway, so you should never see
 825      * these flags in sinks. */
 826
 827     PA_SINK_SHARE_VOLUME_WITH_MASTER = 0x1000000U,
 828     /**< This sink shares the volume with the master sink (used by some filter
 829      * sinks). */
 830
 831     PA_SINK_DEFERRED_VOLUME = 0x2000000U,
 832     /**< The HW volume changes are syncronized with SW volume. */
 833 /** \endcond */
 834 #endif
 835
 836 } pa_sink_flags_t;
 837
 838 /** \cond fulldocs */
 839 #define PA_SINK_HW_VOLUME_CTRL PA_SINK_HW_VOLUME_CTRL
 840 #define PA_SINK_LATENCY PA_SINK_LATENCY
 841 #define PA_SINK_HARDWARE PA_SINK_HARDWARE
 842 #define PA_SINK_NETWORK PA_SINK_NETWORK
 843 #define PA_SINK_HW_MUTE_CTRL PA_SINK_HW_MUTE_CTRL
 844 #define PA_SINK_DECIBEL_VOLUME PA_SINK_DECIBEL_VOLUME
 845 #define PA_SINK_FLAT_VOLUME PA_SINK_FLAT_VOLUME
 846 #define PA_SINK_DYNAMIC_LATENCY PA_SINK_DYNAMIC_LATENCY
 847 #define PA_SINK_SET_FORMATS PA_SINK_SET_FORMATS
 848 #ifdef __INCLUDED_FROM_PULSE_AUDIO
 849 #define PA_SINK_CLIENT_FLAGS_MASK 0xFFFFFF
 850 #endif
 851
 852 /** \endcond */
 853
 854 /** Sink state. \since 0.9.15 */
 855 typedef enum pa_sink_state { /* enum serialized in u8 */
 856     PA_SINK_INVALID_STATE = -1,
 857     /**< This state is used when the server does not support sink state introspection \since 0.9.15 */
 858
 859     PA_SINK_RUNNING = 0,
 860     /**< Running, sink is playing and used by at least one non-corked sink-input \since 0.9.15 */
 861
 862     PA_SINK_IDLE = 1,
 863     /**< When idle, the sink is playing but there is no non-corked sink-input attached to it \since 0.9.15 */
 864
 865     PA_SINK_SUSPENDED = 2,
 866     /**< When suspended, actual sink access can be closed, for instance \since 0.9.15 */
 867
 868 /** \cond fulldocs */
 869     /* PRIVATE: Server-side values -- DO NOT USE THIS ON THE CLIENT
 870      * SIDE! These values are *not* considered part of the official PA
 871      * API/ABI. If you use them your application might break when PA
 872      * is upgraded. Also, please note that these values are not useful
 873      * on the client side anyway. */
 874
 875     PA_SINK_INIT = -2,
 876     /**< Initialization state */
 877
 878     PA_SINK_UNLINKED = -3
 879     /**< The state when the sink is getting unregistered and removed from client access */
 880 /** \endcond */
 881
 882 } pa_sink_state_t;
 883
 884 /** Returns non-zero if sink is playing: running or idle. \since 0.9.15 */
 885 static inline int PA_SINK_IS_OPENED(pa_sink_state_t x) {
 886     return x == PA_SINK_RUNNING || x == PA_SINK_IDLE;
 887 }
 888
 889 /** Returns non-zero if sink is running. \since 1.0 */
 890 static inline int PA_SINK_IS_RUNNING(pa_sink_state_t x) {
 891     return x == PA_SINK_RUNNING;
 892 }
 893
 894 /** \cond fulldocs */
 895 #define PA_SINK_INVALID_STATE PA_SINK_INVALID_STATE
 896 #define PA_SINK_RUNNING PA_SINK_RUNNING
 897 #define PA_SINK_IDLE PA_SINK_IDLE
 898 #define PA_SINK_SUSPENDED PA_SINK_SUSPENDED
 899 #define PA_SINK_INIT PA_SINK_INIT
 900 #define PA_SINK_UNLINKED PA_SINK_UNLINKED
 901 #define PA_SINK_IS_OPENED PA_SINK_IS_OPENED
 902 /** \endcond */
 903
 904 /** Special source flags.  */
 905 typedef enum pa_source_flags {
 906     PA_SOURCE_NOFLAGS = 0x0000U,
 907     /**< Flag to pass when no specific options are needed (used to avoid casting)  \since 0.9.19 */
 908
 909     PA_SOURCE_HW_VOLUME_CTRL = 0x0001U,
 910     /**< Supports hardware volume control. This is a dynamic flag and may
 911      * change at runtime after the source has initialized */
 912
 913     PA_SOURCE_LATENCY = 0x0002U,
 914     /**< Supports latency querying */
 915
 916     PA_SOURCE_HARDWARE = 0x0004U,
 917     /**< Is a hardware source of some kind, in contrast to
 918      * "virtual"/software source \since 0.9.3 */
 919
 920     PA_SOURCE_NETWORK = 0x0008U,
 921     /**< Is a networked source of some kind. \since 0.9.7 */
 922
 923     PA_SOURCE_HW_MUTE_CTRL = 0x0010U,
 924     /**< Supports hardware mute control. This is a dynamic flag and may
 925      * change at runtime after the source has initialized \since 0.9.11 */
 926
 927     PA_SOURCE_DECIBEL_VOLUME = 0x0020U,
 928     /**< Volume can be translated to dB with pa_sw_volume_to_dB(). This is a
 929      * dynamic flag and may change at runtime after the source has initialized
 930      * \since 0.9.11 */
 931
 932     PA_SOURCE_DYNAMIC_LATENCY = 0x0040U,
 933     /**< The latency can be adjusted dynamically depending on the
 934      * needs of the connected streams. \since 0.9.15 */
 935
 936     PA_SOURCE_FLAT_VOLUME = 0x0080U,
 937     /**< This source is in flat volume mode, i.e.\ always the maximum of
 938      * the volume of all connected outputs. \since 1.0 */
 939
 940 #ifdef __INCLUDED_FROM_PULSE_AUDIO
 941 /** \cond fulldocs */
 942     /* PRIVATE: Server-side values -- do not try to use these at client-side.
 943      * The server will filter out these flags anyway, so you should never see
 944      * these flags in sources. */
 945
 946     PA_SOURCE_SHARE_VOLUME_WITH_MASTER = 0x1000000U,
 947     /**< This source shares the volume with the master source (used by some filter
 948      * sources). */
 949
 950     PA_SOURCE_DEFERRED_VOLUME = 0x2000000U,
 951     /**< The HW volume changes are syncronized with SW volume. */
 952 #endif
 953 } pa_source_flags_t;
 954
 955 /** \cond fulldocs */
 956 #define PA_SOURCE_HW_VOLUME_CTRL PA_SOURCE_HW_VOLUME_CTRL
 957 #define PA_SOURCE_LATENCY PA_SOURCE_LATENCY
 958 #define PA_SOURCE_HARDWARE PA_SOURCE_HARDWARE
 959 #define PA_SOURCE_NETWORK PA_SOURCE_NETWORK
 960 #define PA_SOURCE_HW_MUTE_CTRL PA_SOURCE_HW_MUTE_CTRL
 961 #define PA_SOURCE_DECIBEL_VOLUME PA_SOURCE_DECIBEL_VOLUME
 962 #define PA_SOURCE_DYNAMIC_LATENCY PA_SOURCE_DYNAMIC_LATENCY
 963 #define PA_SOURCE_FLAT_VOLUME PA_SOURCE_FLAT_VOLUME
 964 #ifdef __INCLUDED_FROM_PULSE_AUDIO
 965 #define PA_SOURCE_CLIENT_FLAGS_MASK 0xFFFFFF
 966 #endif
 967
 968 /** \endcond */
 969
 970 /** Source state. \since 0.9.15 */
 971 typedef enum pa_source_state {
 972     PA_SOURCE_INVALID_STATE = -1,
 973     /**< This state is used when the server does not support source state introspection \since 0.9.15 */
 974
 975     PA_SOURCE_RUNNING = 0,
 976     /**< Running, source is recording and used by at least one non-corked source-output \since 0.9.15 */
 977
 978     PA_SOURCE_IDLE = 1,
 979     /**< When idle, the source is still recording but there is no non-corked source-output \since 0.9.15 */
 980
 981     PA_SOURCE_SUSPENDED = 2,
 982     /**< When suspended, actual source access can be closed, for instance \since 0.9.15 */
 983
 984 /** \cond fulldocs */
 985     /* PRIVATE: Server-side values -- DO NOT USE THIS ON THE CLIENT
 986      * SIDE! These values are *not* considered part of the official PA
 987      * API/ABI. If you use them your application might break when PA
 988      * is upgraded. Also, please note that these values are not useful
 989      * on the client side anyway. */
 990
 991     PA_SOURCE_INIT = -2,
 992     /**< Initialization state */
 993
 994     PA_SOURCE_UNLINKED = -3
 995     /**< The state when the source is getting unregistered and removed from client access */
 996 /** \endcond */
 997
 998 } pa_source_state_t;
 999
1000 /** Returns non-zero if source is recording: running or idle. \since 0.9.15 */
1001 static inline int PA_SOURCE_IS_OPENED(pa_source_state_t x) {
1002     return x == PA_SOURCE_RUNNING || x == PA_SOURCE_IDLE;
1003 }
1004
1005 /** Returns non-zero if source is running \since 1.0 */
1006 static inline int PA_SOURCE_IS_RUNNING(pa_source_state_t x) {
1007     return x == PA_SOURCE_RUNNING;
1008 }
1009
1010 /** \cond fulldocs */
1011 #define PA_SOURCE_INVALID_STATE PA_SOURCE_INVALID_STATE
1012 #define PA_SOURCE_RUNNING PA_SOURCE_RUNNING
1013 #define PA_SOURCE_IDLE PA_SOURCE_IDLE
1014 #define PA_SOURCE_SUSPENDED PA_SOURCE_SUSPENDED
1015 #define PA_SOURCE_INIT PA_SOURCE_INIT
1016 #define PA_SOURCE_UNLINKED PA_SOURCE_UNLINKED
1017 #define PA_SOURCE_IS_OPENED PA_SOURCE_IS_OPENED
1018 /** \endcond */
1019
1020 /** A generic free() like callback prototype */
1021 typedef void (*pa_free_cb_t)(void *p);
1022
1023 /** A stream policy/meta event requesting that an application should
1024  * cork a specific stream. See pa_stream_event_cb_t for more
1025  * information. \since 0.9.15 */
1026 #define PA_STREAM_EVENT_REQUEST_CORK "request-cork"
1027
1028 /** A stream policy/meta event requesting that an application should
1029  * cork a specific stream. See pa_stream_event_cb_t for more
1030  * information, \since 0.9.15 */
1031 #define PA_STREAM_EVENT_REQUEST_UNCORK "request-uncork"
1032
1033 /** A stream event notifying that the stream is going to be
1034  * disconnected because the underlying sink changed and no longer
1035  * supports the format that was originally negotiated. Clients need
1036  * to connect a new stream to renegotiate a format and continue
1037  * playback. \since 1.0 */
1038 #define PA_STREAM_EVENT_FORMAT_LOST "format-lost"
1039
1040 #ifndef __INCLUDED_FROM_PULSE_AUDIO
1041 /** Port availability / jack detection status
1042  * \since 2.0 */
1043 typedef enum pa_port_available {
1044     PA_PORT_AVAILABLE_UNKNOWN = 0, /**< This port does not support jack detection \since 2.0 */
1045     PA_PORT_AVAILABLE_NO = 1,      /**< This port is not available, likely because the jack is not plugged in. \since 2.0 */
1046     PA_PORT_AVAILABLE_YES = 2,     /**< This port is available, likely because the jack is plugged in. \since 2.0 */
1047 } pa_port_available_t;
1048
1049 /** \cond fulldocs */
1050 #define PA_PORT_AVAILABLE_UNKNOWN PA_PORT_AVAILABLE_UNKNOWN
1051 #define PA_PORT_AVAILABLE_NO PA_PORT_AVAILABLE_NO
1052 #define PA_PORT_AVAILABLE_YES PA_PORT_AVAILABLE_YES
1053
1054 /** \endcond */
1055 #endif
1056
1057 /** \cond fulldocs */
1058 #define PA_VOLUMER_RAMP_TYPE_LINEAR PA_VOLUMER_RAMP_TYPE_LINEAR
1059 #define PA_VOLUMER_RAMP_TYPE_LOGARITHMIC PA_VOLUMER_RAMP_TYPE_LOGARITHMIC
1060 #define PA_VOLUMER_RAMP_TYPE_CUBIC PA_VOLUMER_RAMP_TYPE_CUBIC
1061 /** \endcond */
1062
1063 PA_C_DECL_END
1064
1065 #endif