code.delx.au - pulseaudio/blob - src/pulse/def.h

   1 #ifndef foodefhfoo
   2 #define foodefhfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of PulseAudio.
   8
   9   Copyright 2004-2006 Lennart Poettering
  10   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
  11
  12   PulseAudio is free software; you can redistribute it and/or modify
  13   it under the terms of the GNU Lesser General Public License as
  14   published by the Free Software Foundation; either version 2.1 of the
  15   License, or (at your option) any later version.
  16
  17   PulseAudio is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public
  23   License along with PulseAudio; if not, write to the Free Software
  24   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  25   USA.
  26 ***/
  27
  28 #include <inttypes.h>
  29 #include <sys/time.h>
  30 #include <time.h>
  31
  32 #include <pulse/cdecl.h>
  33 #include <pulse/sample.h>
  34
  35 /** \file
  36  * Global definitions */
  37
  38 PA_C_DECL_BEGIN
  39
  40 /** The state of a connection context */
  41 typedef enum pa_context_state {
  42     PA_CONTEXT_UNCONNECTED,    /**< The context hasn't been connected yet */
  43     PA_CONTEXT_CONNECTING,     /**< A connection is being established */
  44     PA_CONTEXT_AUTHORIZING,    /**< The client is authorizing itself to the daemon */
  45     PA_CONTEXT_SETTING_NAME,   /**< The client is passing its application name to the daemon */
  46     PA_CONTEXT_READY,          /**< The connection is established, the context is ready to execute operations */
  47     PA_CONTEXT_FAILED,         /**< The connection failed or was disconnected */
  48     PA_CONTEXT_TERMINATED      /**< The connection was terminated cleanly */
  49 } pa_context_state_t;
  50
  51 /** The state of a stream */
  52 typedef enum pa_stream_state {
  53     PA_STREAM_UNCONNECTED, /**< The stream is not yet connected to any sink or source */
  54     PA_STREAM_CREATING,     /**< The stream is being created */
  55     PA_STREAM_READY,        /**< The stream is established, you may pass audio data to it now */
  56     PA_STREAM_FAILED,       /**< An error occured that made the stream invalid */
  57     PA_STREAM_TERMINATED    /**< The stream has been terminated cleanly */
  58 } pa_stream_state_t;
  59
  60 /** The state of an operation */
  61 typedef enum pa_operation_state {
  62     PA_OPERATION_RUNNING,      /**< The operation is still running */
  63     PA_OPERATION_DONE,         /**< The operation has been completed */
  64     PA_OPERATION_CANCELED      /**< The operation has been canceled */
  65 } pa_operation_state_t;
  66
  67 /** An invalid index */
  68 #define PA_INVALID_INDEX ((uint32_t) -1)
  69
  70 /** Some special flags for contexts. */
  71 typedef enum pa_context_flags {
  72     PA_CONTEXT_NOAUTOSPAWN = 1 /**< Disabled autospawning of the PulseAudio daemon if required */
  73 } pa_context_flags_t;
  74
  75 /** The direction of a pa_stream object */
  76 typedef enum pa_stream_direction {
  77     PA_STREAM_NODIRECTION,   /**< Invalid direction */
  78     PA_STREAM_PLAYBACK,      /**< Playback stream */
  79     PA_STREAM_RECORD,        /**< Record stream */
  80     PA_STREAM_UPLOAD         /**< Sample upload stream */
  81 } pa_stream_direction_t;
  82
  83 /** Some special flags for stream connections. */
  84 typedef enum pa_stream_flags {
  85     PA_STREAM_START_CORKED = 1,       /**< Create the stream corked, requiring an explicit pa_stream_cork() call to uncork it. */
  86     PA_STREAM_INTERPOLATE_TIMING = 2, /**< Interpolate the latency for
  87                                        * this stream. When enabled,
  88                                        * pa_stream_get_latency() and
  89                                        * pa_stream_get_time() will try
  90                                        * to estimate the current
  91                                        * record/playback time based on
  92                                        * the local time that passed
  93                                        * since the last timing info
  94                                        * update.  Using this option
  95                                        * has the advantage of not
  96                                        * requiring a whole roundtrip
  97                                        * when the current
  98                                        * playback/recording time is
  99                                        * needed. Consider using this
 100                                        * option when requesting
 101                                        * latency information
 102                                        * frequently. This is
 103                                        * especially useful on long
 104                                        * latency network
 105                                        * connections. It makes a lot
 106                                        * of sense to combine this
 107                                        * option with
 108                                        * PA_STREAM_AUTO_TIMING_UPDATE. */
 109     PA_STREAM_NOT_MONOTONOUS = 4,    /**< Don't force the time to
 110                                       * increase monotonically. If
 111                                       * this option is enabled,
 112                                       * pa_stream_get_time() will not
 113                                       * necessarily return always
 114                                       * monotonically increasing time
 115                                       * values on each call. This may
 116                                       * confuse applications which
 117                                       * cannot deal with time going
 118                                       * 'backwards', but has the
 119                                       * advantage that bad transport
 120                                       * latency estimations that
 121                                       * caused the time to to jump
 122                                       * ahead can be corrected
 123                                       * quickly, without the need to
 124                                       * wait. */
 125     PA_STREAM_AUTO_TIMING_UPDATE = 8, /**< If set timing update requests
 126                                        * are issued periodically
 127                                        * automatically. Combined with
 128                                        * PA_STREAM_INTERPOLATE_TIMING
 129                                        * you will be able to query the
 130                                        * current time and latency with
 131                                        * pa_stream_get_time() and
 132                                        * pa_stream_get_latency() at
 133                                        * all times without a packet
 134                                        * round trip.*/
 135     PA_STREAM_NO_REMAP_CHANNELS = 16, /**< Don't remap channels by
 136                                        * their name, instead map them
 137                                        * simply by their
 138                                        * index. Implies
 139                                        * PA_STREAM_NO_REMIX_CHANNELS. Only
 140                                        * supported when the server is
 141                                        * at least PA 0.9.8. It is
 142                                        * ignored on older
 143                                        * servers.\since 0.9.8 */
 144     PA_STREAM_NO_REMIX_CHANNELS = 32, /**< When remapping channels by
 145                                        * name, don't upmix or downmix
 146                                        * them to related
 147                                        * channels. Copy them into
 148                                        * matching channels of the
 149                                        * device 1:1. Only supported
 150                                        * when the server is at least
 151                                        * PA 0.9.8. It is ignored on
 152                                        * older servers. \since
 153                                        * 0.9.8 */
 154     PA_STREAM_FIX_FORMAT = 64, /**< Use the sample format of the
 155                                 * sink/device this stream is being
 156                                 * connected to, and possibly ignore
 157                                 * the format the sample spec contains
 158                                 * -- but you still have to pass a
 159                                 * valid value in it as a hint to
 160                                 * PulseAudio what would suit your
 161                                 * stream best. If this is used you
 162                                 * should query the used sample format
 163                                 * after creating the stream by using
 164                                 * pa_stream_get_sample_spec(). Also,
 165                                 * if you specified manual buffer
 166                                 * metrics it is recommended to update
 167                                 * them with
 168                                 * pa_stream_set_buffer_attr() to
 169                                 * compensate for the changed frame
 170                                 * sizes. Only supported when the
 171                                 * server is at least PA 0.9.8. It is
 172                                 * ignored on older servers. \since
 173                                 * 0.9.8 */
 174
 175     PA_STREAM_FIX_RATE = 128, /**< Use the sample rate of the sink,
 176                                * and possibly ignore the rate the
 177                                * sample spec contains. Usage similar
 178                                * to PA_STREAM_FIX_FORMAT.Only
 179                                * supported when the server is at least
 180                                * PA 0.9.8. It is ignored on older
 181                                * servers. \since 0.9.8 */
 182
 183     PA_STREAM_FIX_CHANNELS = 256, /**< Use the number of channels and
 184                                * the channel map of the sink, and
 185                                * possibly ignore the number of
 186                                * channels and the map the sample spec
 187                                * and the passed channel map
 188                                * contains. Usage similar to
 189                                * PA_STREAM_FIX_FORMAT. Only supported
 190                                * when the server is at least PA
 191                                * 0.9.8. It is ignored on older
 192                                * servers. \since 0.9.8 */
 193     PA_STREAM_DONT_MOVE = 512, /**< Don't allow moving of this stream to
 194                               * another sink/device. Useful if you use
 195                               * any of the PA_STREAM_FIX_ flags and
 196                               * want to make sure that resampling
 197                               * never takes place -- which might
 198                               * happen if the stream is moved to
 199                               * another sink/source whith a different
 200                               * sample spec/channel map. Only
 201                               * supported when the server is at least
 202                               * PA 0.9.8. It is ignored on older
 203                               * servers. \since 0.9.8 */
 204     PA_STREAM_VARIABLE_RATE = 1024, /**< Allow dynamic changing of the
 205                                      * sampling rate during playback
 206                                      * with
 207                                      * pa_stream_update_sample_rate(). Only
 208                                      * supported when the server is at
 209                                      * least PA 0.9.8. It is ignored
 210                                      * on older servers. \since
 211                                      * 0.9.8 */
 212     PA_STREAM_PEAK_DETECT = 2048, /**< Find peaks instead of
 213                                    * resampling. \since 0.9.11 */
 214
 215     PA_STREAM_START_MUTED = 4096,  /**< Create in muted state. \since 0.9.11 */
 216
 217
 218     PA_STREAM_ADJUST_LATENCY = 8192, /**< Try to adjust the latency of
 219                                       * the sink/source based on the
 220                                       * requested buffer metrics and
 221                                       * adjust buffer metrics
 222                                       * accordingly. \since 0.9.11 */
 223 } pa_stream_flags_t;
 224
 225 /** Playback and record buffer metrics */
 226 typedef struct pa_buffer_attr {
 227     uint32_t maxlength;      /**< Maximum length of the
 228                               * buffer. Setting this to 0 will
 229                               * initialize this to the maximum value
 230                               * supported by server, which is
 231                               * recommended. */
 232     uint32_t tlength;        /**< Playback only: target length of the
 233                               * buffer. The server tries to assure
 234                               * that at least tlength bytes are always
 235                               * available in the buffer. It is
 236                               * recommended to set this to 0, which
 237                               * will initialize this to a value that
 238                               * is deemed sensible by the
 239                               * server. However, this value will
 240                               * default to something like 2s, i.e. for
 241                               * applications that have specific
 242                               * latency requirements this value should
 243                               * be set to the maximum latency that the
 244                               * application can deal with.  */
 245     uint32_t prebuf;         /**< Playback only: pre-buffering. The
 246                               * server does not start with playback
 247                               * before at least prebug bytes are
 248                               * available in the buffer. It is
 249                               * recommended to set this to 0, which
 250                               * will initialize this to the same value
 251                               * as tlength, whatever that may be. */
 252     uint32_t minreq;         /**< Playback only: minimum request. The
 253                               * server does not request less than
 254                               * minreq bytes from the client, instead
 255                               * waits until the buffer is free enough
 256                               * to request more bytes at once. It is
 257                               * recommended to set this to 0, which
 258                               * will initialize this to a value that
 259                               * is deemed sensible by the server. */
 260     uint32_t fragsize;       /**< Recording only: fragment size. The
 261                               * server sends data in blocks of
 262                               * fragsize bytes size. Large values
 263                               * deminish interactivity with other
 264                               * operations on the connection context
 265                               * but decrease control overhead. It is
 266                               * recommended to set this to 0, which
 267                               * will initialize this to a value that
 268                               * is deemed sensible by the
 269                               * server. However, this value will
 270                               * default to something like 2s, i.e. for
 271                               * applications that have specific
 272                               * latency requirements this value should
 273                               * be set to the maximum latency that the
 274                               * application can deal with. */
 275 } pa_buffer_attr;
 276
 277 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
 278 enum {
 279     PA_OK = 0,                     /**< No error */
 280     PA_ERR_ACCESS,                 /**< Access failure */
 281     PA_ERR_COMMAND,                /**< Unknown command */
 282     PA_ERR_INVALID,                /**< Invalid argument */
 283     PA_ERR_EXIST,                  /**< Entity exists */
 284     PA_ERR_NOENTITY,               /**< No such entity */
 285     PA_ERR_CONNECTIONREFUSED,      /**< Connection refused */
 286     PA_ERR_PROTOCOL,               /**< Protocol error */
 287     PA_ERR_TIMEOUT,                /**< Timeout */
 288     PA_ERR_AUTHKEY,                /**< No authorization key */
 289     PA_ERR_INTERNAL,               /**< Internal error */
 290     PA_ERR_CONNECTIONTERMINATED,   /**< Connection terminated */
 291     PA_ERR_KILLED,                 /**< Entity killed */
 292     PA_ERR_INVALIDSERVER,          /**< Invalid server */
 293     PA_ERR_MODINITFAILED,          /**< Module initialization failed */
 294     PA_ERR_BADSTATE,               /**< Bad state */
 295     PA_ERR_NODATA,                 /**< No data */
 296     PA_ERR_VERSION,                /**< Incompatible protocol version */
 297     PA_ERR_TOOLARGE,               /**< Data too large */
 298     PA_ERR_NOTSUPPORTED,           /**< Operation not supported \since 0.9.5 */
 299     PA_ERR_MAX                     /**< Not really an error but the first invalid error code */
 300 };
 301
 302 /** Subscription event mask, as used by pa_context_subscribe() */
 303 typedef enum pa_subscription_mask {
 304     PA_SUBSCRIPTION_MASK_NULL = 0,               /**< No events */
 305     PA_SUBSCRIPTION_MASK_SINK = 1,               /**< Sink events */
 306     PA_SUBSCRIPTION_MASK_SOURCE = 2,             /**< Source events */
 307     PA_SUBSCRIPTION_MASK_SINK_INPUT = 4,         /**< Sink input events */
 308     PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 8,      /**< Source output events */
 309     PA_SUBSCRIPTION_MASK_MODULE = 16,            /**< Module events */
 310     PA_SUBSCRIPTION_MASK_CLIENT = 32,            /**< Client events */
 311     PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64,      /**< Sample cache events */
 312     PA_SUBSCRIPTION_MASK_SERVER = 128,           /**< Other global server changes. */
 313     PA_SUBSCRIPTION_MASK_AUTOLOAD = 256,         /**< Autoload table events. */
 314     PA_SUBSCRIPTION_MASK_ALL = 511               /**< Catch all events */
 315 } pa_subscription_mask_t;
 316
 317 /** Subscription event types, as used by pa_context_subscribe() */
 318 typedef enum pa_subscription_event_type {
 319     PA_SUBSCRIPTION_EVENT_SINK = 0,           /**< Event type: Sink */
 320     PA_SUBSCRIPTION_EVENT_SOURCE = 1,         /**< Event type: Source */
 321     PA_SUBSCRIPTION_EVENT_SINK_INPUT = 2,     /**< Event type: Sink input */
 322     PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 3,  /**< Event type: Source output */
 323     PA_SUBSCRIPTION_EVENT_MODULE = 4,         /**< Event type: Module */
 324     PA_SUBSCRIPTION_EVENT_CLIENT = 5,         /**< Event type: Client */
 325     PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6,   /**< Event type: Sample cache item */
 326     PA_SUBSCRIPTION_EVENT_SERVER = 7,         /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. */
 327     PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8,       /**< Event type: Autoload table changes. */
 328     PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */
 329
 330     PA_SUBSCRIPTION_EVENT_NEW = 0,            /**< A new object was created */
 331     PA_SUBSCRIPTION_EVENT_CHANGE = 16,        /**< A property of the object was modified */
 332     PA_SUBSCRIPTION_EVENT_REMOVE = 32,        /**< An object was removed */
 333     PA_SUBSCRIPTION_EVENT_TYPE_MASK = 16+32   /**< A mask to extract the event operation from an event value */
 334 } pa_subscription_event_type_t;
 335
 336 /** Return one if an event type t matches an event mask bitfield */
 337 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
 338
 339 /** A structure for all kinds of timing information of a stream. See
 340  * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
 341  * total output latency a sample that is written with
 342  * pa_stream_write() takes to be played may be estimated by
 343  * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
 344  * as pa_bytes_to_usec(write_index-read_index)) The output buffer
 345  * which buffer_usec relates to may be manipulated freely (with
 346  * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
 347  * the buffers sink_usec and source_usec relate to are first-in
 348  * first-out (FIFO) buffers which cannot be flushed or manipulated in
 349  * any way. The total input latency a sample that is recorded takes to
 350  * be delivered to the application is:
 351  * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
 352  * sign issues!) When connected to a monitor source sink_usec contains
 353  * the latency of the owning sink. The two latency estimations
 354  * described here are implemented in pa_stream_get_latency(). Please
 355  * note that this structure can be extended as part of evolutionary
 356  * API updates at any time in any new release.*/
 357 typedef struct pa_timing_info {
 358     struct timeval timestamp; /**< The time when this timing info structure was current */
 359     int synchronized_clocks;  /**< Non-zero if the local and the
 360                                * remote machine have synchronized
 361                                * clocks. If synchronized clocks are
 362                                * detected transport_usec becomes much
 363                                * more reliable. However, the code that
 364                                * detects synchronized clocks is very
 365                                * limited und unreliable itself. */
 366
 367     pa_usec_t sink_usec;      /**< Time in usecs a sample takes to be played on the sink. For playback streams and record streams connected to a monitor source. */
 368     pa_usec_t source_usec;    /**< Time in usecs a sample takes from being recorded to being delivered to the application. Only for record streams. */
 369     pa_usec_t transport_usec; /**< Estimated time in usecs a sample takes to be transferred to/from the daemon. For both playback and record streams. */
 370
 371     int playing;              /**< Non-zero when the stream is currently playing. Only for playback streams. */
 372
 373     int write_index_corrupt;  /**< Non-zero if write_index is not
 374                                * up-to-date because a local write
 375                                * command that corrupted it has been
 376                                * issued in the time since this latency
 377                                * info was current . Only write
 378                                * commands with SEEK_RELATIVE_ON_READ
 379                                * and SEEK_RELATIVE_END can corrupt
 380                                * write_index. */
 381     int64_t write_index;      /**< Current write index into the
 382                                * playback buffer in bytes. Think twice before
 383                                * using this for seeking purposes: it
 384                                * might be out of date a the time you
 385                                * want to use it. Consider using
 386                                * PA_SEEK_RELATIVE instead.  */
 387
 388     int read_index_corrupt;   /**< Non-zero if read_index is not
 389                                * up-to-date because a local pause or
 390                                * flush request that corrupted it has
 391                                * been issued in the time since this
 392                                * latency info was current. */
 393
 394     int64_t read_index;       /**< Current read index into the
 395                                * playback buffer in bytes. Think twice before
 396                                * using this for seeking purposes: it
 397                                * might be out of date a the time you
 398                                * want to use it. Consider using
 399                                * PA_SEEK_RELATIVE_ON_READ
 400                                * instead. */
 401
 402     pa_usec_t configured_sink_usec;   /**< The static configured latency for
 403                                 * the sink. \since 0.9.11 */
 404     pa_usec_t configured_source_usec; /**< The static configured latency for
 405                                 * the source. \since 0.9.11 */
 406 } pa_timing_info;
 407
 408 /** A structure for the spawn api. This may be used to integrate auto
 409  * spawned daemons into your application. For more information see
 410  * pa_context_connect(). When spawning a new child process the
 411  * waitpid() is used on the child's PID. The spawn routine will not
 412  * block or ignore SIGCHLD signals, since this cannot be done in a
 413  * thread compatible way. You might have to do this in
 414  * prefork/postfork. */
 415 typedef struct pa_spawn_api {
 416     void (*prefork)(void);     /**< Is called just before the fork in the parent process. May be NULL. */
 417     void (*postfork)(void);    /**< Is called immediately after the fork in the parent process. May be NULL.*/
 418     void (*atfork)(void);      /**< Is called immediately after the
 419                                 * fork in the child process. May be
 420                                 * NULL. It is not safe to close all
 421                                 * file descriptors in this function
 422                                 * unconditionally, since a UNIX socket
 423                                 * (created using socketpair()) is
 424                                 * passed to the new process. */
 425 } pa_spawn_api;
 426
 427 /** Seek type for pa_stream_write(). */
 428 typedef enum pa_seek_mode {
 429     PA_SEEK_RELATIVE = 0,           /**< Seek relatively to the write index */
 430     PA_SEEK_ABSOLUTE = 1,           /**< Seek relatively to the start of the buffer queue */
 431     PA_SEEK_RELATIVE_ON_READ = 2,   /**< Seek relatively to the read index.  */
 432     PA_SEEK_RELATIVE_END = 3        /**< Seek relatively to the current end of the buffer queue. */
 433 } pa_seek_mode_t;
 434
 435 /** Special sink flags. */
 436 typedef enum pa_sink_flags {
 437     PA_SINK_HW_VOLUME_CTRL = 1,   /**< Supports hardware volume control */
 438     PA_SINK_LATENCY = 2,          /**< Supports latency querying */
 439     PA_SINK_HARDWARE = 4,         /**< Is a hardware sink of some kind, in contrast to "virtual"/software sinks \since 0.9.3 */
 440     PA_SINK_NETWORK = 8,          /**< Is a networked sink of some kind. \since 0.9.7 */
 441     PA_SINK_HW_MUTE_CTRL = 16,    /**< Supports hardware mute control \since 0.9.11 */
 442     PA_SINK_DECIBEL_VOLUME = 32   /**< Volume can be translated to dB with pa_sw_volume_to_dB() \since 0.9.11 */
 443 } pa_sink_flags_t;
 444
 445 /** Special source flags.  */
 446 typedef enum pa_source_flags {
 447     PA_SOURCE_HW_VOLUME_CTRL = 1,  /**< Supports hardware volume control */
 448     PA_SOURCE_LATENCY = 2,         /**< Supports latency querying */
 449     PA_SOURCE_HARDWARE = 4,        /**< Is a hardware source of some kind, in contrast to "virtual"/software source \since 0.9.3 */
 450     PA_SOURCE_NETWORK = 8,         /**< Is a networked sink of some kind. \since 0.9.7 */
 451     PA_SOURCE_HW_MUTE_CTRL = 16,   /**< Supports hardware mute control \since 0.9.11 */
 452     PA_SOURCE_DECIBEL_VOLUME = 32  /**< Volume can be translated to dB with pa_sw_volume_to_dB() \since 0.9.11 */
 453 } pa_source_flags_t;
 454
 455 /** A generic free() like callback prototype */
 456 typedef void (*pa_free_cb_t)(void *p);
 457
 458 PA_C_DECL_END
 459
 460 #endif