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

   1 #ifndef foodefhfoo
   2 #define foodefhfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of polypaudio.
   8
   9   polypaudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as
  11   published by the Free Software Foundation; either version 2.1 of the
  12   License, or (at your option) any later version.
  13
  14   polypaudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public
  20   License along with polypaudio; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 #include <inttypes.h>
  26 #include <sys/time.h>
  27 #include <time.h>
  28
  29 #include <polyp/cdecl.h>
  30 #include <polyp/sample.h>
  31
  32 /** \file
  33  * Global definitions */
  34
  35 PA_C_DECL_BEGIN
  36
  37 /** The state of a connection context */
  38 typedef enum pa_context_state {
  39     PA_CONTEXT_UNCONNECTED,    /**< The context hasn't been connected yet */
  40     PA_CONTEXT_CONNECTING,     /**< A connection is being established */
  41     PA_CONTEXT_AUTHORIZING,    /**< The client is authorizing itself to the daemon */
  42     PA_CONTEXT_SETTING_NAME,   /**< The client is passing its application name to the daemon */
  43     PA_CONTEXT_READY,          /**< The connection is established, the context is ready to execute operations */
  44     PA_CONTEXT_FAILED,         /**< The connection failed or was disconnected */
  45     PA_CONTEXT_TERMINATED      /**< The connection was terminated cleanly */
  46 } pa_context_state_t;
  47
  48 /** The state of a stream */
  49 typedef enum pa_stream_state {
  50     PA_STREAM_UNCONNECTED, /**< The stream is not yet connected to any sink or source */
  51     PA_STREAM_CREATING,     /**< The stream is being created */
  52     PA_STREAM_READY,        /**< The stream is established, you may pass audio data to it now */
  53     PA_STREAM_FAILED,       /**< An error occured that made the stream invalid */
  54     PA_STREAM_TERMINATED    /**< The stream has been terminated cleanly */
  55 } pa_stream_state_t;
  56
  57 /** The state of an operation */
  58 typedef enum pa_operation_state {
  59     PA_OPERATION_RUNNING,      /**< The operation is still running */
  60     PA_OPERATION_DONE,         /**< The operation has been completed */
  61     PA_OPERATION_CANCELED      /**< The operation has been canceled */
  62 } pa_operation_state_t;
  63
  64 /** An invalid index */
  65 #define PA_INVALID_INDEX ((uint32_t) -1)
  66
  67 /** Some special flags for contexts. \since 0.8 */
  68 typedef enum pa_context_flags {
  69     PA_CONTEXT_NOAUTOSPAWN = 1 /**< Disabled autospawning of the polypaudio daemon if required */
  70 } pa_context_flags_t;
  71
  72 /** The direction of a pa_stream object */
  73 typedef enum pa_stream_direction {
  74     PA_STREAM_NODIRECTION,   /**< Invalid direction */
  75     PA_STREAM_PLAYBACK,      /**< Playback stream */
  76     PA_STREAM_RECORD,        /**< Record stream */
  77     PA_STREAM_UPLOAD         /**< Sample upload stream */
  78 } pa_stream_direction_t;
  79
  80 /** Some special flags for stream connections. \since 0.6 */
  81 typedef enum pa_stream_flags {
  82     PA_STREAM_START_CORKED = 1,       /**< Create the stream corked, requiring an explicit pa_stream_cork() call to uncork it. */
  83     PA_STREAM_INTERPOLATE_TIMING = 2, /**< Interpolate the latency for
  84                                        * this stream. When enabled,
  85                                        * pa_stream_get_latency() and pa_stream_get_time()
  86                                        * will try to estimate the
  87                                        * current record/playback time
  88                                        * based on the local time that
  89                                        * passed since the last timing
  90                                        * info update. In addition
  91                                        * timing update requests are
  92                                        * issued periodically
  93                                        * automatically. Using this
  94                                        * option has the advantage of
  95                                        * not requiring a whole
  96                                        * roundtrip when the current
  97                                        * playback/recording time is
  98                                        * needed. Consider using this
  99                                        * option when requesting
 100                                        * latency information
 101                                        * frequently. This is
 102                                        * especially useful on long
 103                                        * latency network
 104                                        * connections. */
 105     PA_STREAM_NOT_MONOTONOUS = 4,    /**< Don't force the time to
 106                                       * increase monotonically. If
 107                                       * this option is enabled,
 108                                       * pa_stream_get_time() will not
 109                                       * necessarily return always
 110                                       * monotonically increasing time
 111                                       * values on each call. This may
 112                                       * confuse applications which
 113                                       * cannot deal with time going
 114                                       * 'backwards', but has the
 115                                       * advantage that bad transport
 116                                       * latency estimations that
 117                                       * caused the time to to jump
 118                                       * ahead can be corrected
 119                                       * quickly, without the need to
 120                                       * wait. */
 121 } pa_stream_flags_t;
 122
 123 /** Playback and record buffer metrics */
 124 typedef struct pa_buffer_attr {
 125     uint32_t maxlength;      /**< Maximum length of the buffer */
 126     uint32_t tlength;        /**< Playback only: target length of the buffer. The server tries to assure that at least tlength bytes are always available in the buffer */
 127     uint32_t prebuf;         /**< Playback only: pre-buffering. The server does not start with playback before at least prebug bytes are available in the buffer */
 128     uint32_t minreq;         /**< Playback only: minimum request. The server does not request less than minreq bytes from the client, instead waints until the buffer is free enough to request more bytes at once */
 129     uint32_t fragsize;       /**< Recording only: fragment size. The server sends data in blocks of fragsize bytes size. Large values deminish interactivity with other operations on the connection context but decrease control overhead. */
 130 } pa_buffer_attr;
 131
 132 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
 133 enum {
 134     PA_OK = 0,                     /**< No error */
 135     PA_ERR_ACCESS,                 /**< Access failure */
 136     PA_ERR_COMMAND,                /**< Unknown command */
 137     PA_ERR_INVALID,                /**< Invalid argument */
 138     PA_ERR_EXIST,                  /**< Entity exists */
 139     PA_ERR_NOENTITY,               /**< No such entity */
 140     PA_ERR_CONNECTIONREFUSED,      /**< Connection refused */
 141     PA_ERR_PROTOCOL,               /**< Protocol error */
 142     PA_ERR_TIMEOUT,                /**< Timeout */
 143     PA_ERR_AUTHKEY,                /**< No authorization key */
 144     PA_ERR_INTERNAL,               /**< Internal error */
 145     PA_ERR_CONNECTIONTERMINATED,   /**< Connection terminated */
 146     PA_ERR_KILLED,                 /**< Entity killed */
 147     PA_ERR_INVALIDSERVER,          /**< Invalid server */
 148     PA_ERR_MODINITFAILED,          /**< Module initialization failed */
 149     PA_ERR_BADSTATE,               /**< Bad state */
 150     PA_ERR_NODATA,                 /**< No data */
 151     PA_ERR_VERSION,                /**< Incompatible protocol version \since 0.8 */
 152     PA_ERR_MAX                     /**< Not really an error but the first invalid error code */
 153 };
 154
 155 /** Subscription event mask, as used by pa_context_subscribe() */
 156 typedef enum pa_subscription_mask {
 157     PA_SUBSCRIPTION_MASK_NULL = 0,               /**< No events */
 158     PA_SUBSCRIPTION_MASK_SINK = 1,               /**< Sink events */
 159     PA_SUBSCRIPTION_MASK_SOURCE = 2,             /**< Source events */
 160     PA_SUBSCRIPTION_MASK_SINK_INPUT = 4,         /**< Sink input events */
 161     PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 8,      /**< Source output events */
 162     PA_SUBSCRIPTION_MASK_MODULE = 16,            /**< Module events */
 163     PA_SUBSCRIPTION_MASK_CLIENT = 32,            /**< Client events */
 164     PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64,      /**< Sample cache events */
 165     PA_SUBSCRIPTION_MASK_SERVER = 128,           /**< Other global server changes. \since 0.4 */
 166     PA_SUBSCRIPTION_MASK_AUTOLOAD = 256,         /**< Autoload table events. \since 0.5 */
 167     PA_SUBSCRIPTION_MASK_ALL = 511               /**< Catch all events \since 0.8 */
 168 } pa_subscription_mask_t;
 169
 170 /** Subscription event types, as used by pa_context_subscribe() */
 171 typedef enum pa_subscription_event_type {
 172     PA_SUBSCRIPTION_EVENT_SINK = 0,           /**< Event type: Sink */
 173     PA_SUBSCRIPTION_EVENT_SOURCE = 1,         /**< Event type: Source */
 174     PA_SUBSCRIPTION_EVENT_SINK_INPUT = 2,     /**< Event type: Sink input */
 175     PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 3,  /**< Event type: Source output */
 176     PA_SUBSCRIPTION_EVENT_MODULE = 4,         /**< Event type: Module */
 177     PA_SUBSCRIPTION_EVENT_CLIENT = 5,         /**< Event type: Client */
 178     PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6,   /**< Event type: Sample cache item */
 179     PA_SUBSCRIPTION_EVENT_SERVER = 7,         /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. \since 0.4  */
 180     PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8,       /**< Event type: Autoload table changes. \since 0.5 */
 181     PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */
 182
 183     PA_SUBSCRIPTION_EVENT_NEW = 0,            /**< A new object was created */
 184     PA_SUBSCRIPTION_EVENT_CHANGE = 16,        /**< A property of the object was modified */
 185     PA_SUBSCRIPTION_EVENT_REMOVE = 32,        /**< An object was removed */
 186     PA_SUBSCRIPTION_EVENT_TYPE_MASK = 16+32   /**< A mask to extract the event operation from an event value */
 187 } pa_subscription_event_type_t;
 188
 189 /** Return one if an event type t matches an event mask bitfield */
 190 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
 191
 192 /** A structure for all kinds of timing information of a stream. See
 193  * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
 194  * total output latency a sample that is written with
 195  * pa_stream_write() takes to be played may be estimated by
 196  * sink_usec+buffer_usec+transport_usec. The output buffer to which
 197  * buffer_usec relates may be manipulated freely (with
 198  * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
 199  * the buffers sink_usec and source_usec relate to are first-in
 200  * first-out (FIFO) buffers which cannot be flushed or manipulated in any
 201  * way. The total input latency a sample that is recorded takes to be
 202  * delivered to the application is:
 203  * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
 204  * sign issues!) When connected to a monitor source sink_usec contains
 205  * the latency of the owning sink. The two latency estimations
 206  * described here are implemented in pa_stream_get_latency().*/
 207 typedef struct pa_timing_info {
 208     struct timeval timestamp; /**< The time when this timing info structure was current */
 209     int synchronized_clocks;  /**< Non-zero if the local and the
 210                                * remote machine have synchronized
 211                                * clocks. If synchronized clocks are
 212                                * detected transport_usec becomes much
 213                                * more reliable. However, the code that
 214                                * detects synchronized clocks is very
 215                                * limited und unreliable itself. \since
 216                                * 0.5 */
 217
 218     pa_usec_t buffer_usec;    /**< Time in usecs the current buffer takes to play. For both playback and record streams. */
 219     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. */
 220     pa_usec_t source_usec;    /**< Time in usecs a sample takes from being recorded to being delivered to the application. Only for record streams. \since 0.5*/
 221     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. \since 0.5 */
 222
 223     int playing;              /**< Non-zero when the stream is currently playing. Only for playback streams. */
 224
 225     int write_index_corrupt;  /**< Non-zero if write_index is not
 226                                * up-to-date because a local write
 227                                * command that corrupted it has been
 228                                * issued in the time since this latency
 229                                * info was current . Only write
 230                                * commands with SEEK_RELATIVE_ON_READ
 231                                * and SEEK_RELATIVE_END can corrupt
 232                                * write_index. */
 233     int64_t write_index;      /**< Current write index into the
 234                                * playback buffer in bytes. Think twice before
 235                                * using this for seeking purposes: it
 236                                * might be out of date a the time you
 237                                * want to use it. Consider using
 238                                * PA_SEEK_RELATIVE instead. \since
 239                                * 0.8 */
 240     int64_t read_index;       /**< Current read index into the
 241                                * playback buffer in bytes. Think twice before
 242                                * using this for seeking purposes: it
 243                                * might be out of date a the time you
 244                                * want to use it. Consider using
 245                                * PA_SEEK_RELATIVE_ON_READ
 246                                * instead. \since 0.8 */
 247 } pa_timing_info;
 248
 249 /** A structure for the spawn api. This may be used to integrate auto
 250  * spawned daemons into your application. For more information see
 251  * pa_context_connect(). When spawning a new child process the
 252  * waitpid() is used on the child's PID. The spawn routine will not
 253  * block or ignore SIGCHLD signals, since this cannot be done in a
 254  * thread compatible way. You might have to do this in
 255  * prefork/postfork. \since 0.4 */
 256 typedef struct pa_spawn_api {
 257     void (*prefork)(void);     /**< Is called just before the fork in the parent process. May be NULL. */
 258     void (*postfork)(void);    /**< Is called immediately after the fork in the parent process. May be NULL.*/
 259     void (*atfork)(void);      /**< Is called immediately after the
 260                                 * fork in the child process. May be
 261                                 * NULL. It is not safe to close all
 262                                 * file descriptors in this function
 263                                 * unconditionally, since a UNIX socket
 264                                 * (created using socketpair()) is
 265                                 * passed to the new process. */
 266 } pa_spawn_api;
 267
 268 /** Seek type for pa_stream_write(). \since 0.8*/
 269 typedef enum pa_seek_mode {
 270     PA_SEEK_RELATIVE = 0,           /**< Seek relatively to the write index */
 271     PA_SEEK_ABSOLUTE = 1,           /**< Seek relatively to the start of the buffer queue */
 272     PA_SEEK_RELATIVE_ON_READ = 2,   /**< Seek relatively to the read index.  */
 273     PA_SEEK_RELATIVE_END = 3,       /**< Seek relatively to the current end of the buffer queue. */
 274 } pa_seek_mode_t;
 275
 276 /** Special sink flags. \since 0.8  */
 277 typedef enum pa_sink_flags {
 278     PA_SINK_HW_VOLUME_CTRL = 1,   /**< Supports hardware volume control */
 279     PA_SINK_LATENCY = 2           /**< Supports latency querying */
 280 } pa_sink_flags_t;
 281
 282 /** Special source flags. \since 0.8  */
 283 typedef enum pa_source_flags {
 284     PA_SOURCE_HW_VOLUME_CTRL = 1,  /**< Supports hardware volume control */
 285     PA_SOURCE_LATENCY = 2          /**< Supports latency querying */
 286 } pa_source_flags_t;
 287
 288 PA_C_DECL_END
 289
 290 #endif