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_LATENCY = 2 /**< Interpolate the latency for
  84                                        * this stream. When enabled,
  85                                        * you can use
  86                                        * pa_stream_interpolated_xxx()
  87                                        * for synchronization. Using
  88                                        * these functions instead of
  89                                        * pa_stream_get_latency() has
  90                                        * the advantage of not
  91                                        * requiring a whole roundtrip
  92                                        * for responses. Consider using
  93                                        * this option when frequently
  94                                        * requesting latency
  95                                        * information. This is
  96                                        * especially useful on long latency
  97                                        * network connections. */
  98 } pa_stream_flags_t;
  99
 100 /** Playback and record buffer metrics */
 101 typedef struct pa_buffer_attr {
 102     uint32_t maxlength;      /**< Maximum length of the buffer */
 103     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 */
 104     uint32_t prebuf;         /**< Playback only: pre-buffering. The server does not start with playback before at least prebug bytes are available in the buffer */
 105     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 */
 106     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. */
 107 } pa_buffer_attr;
 108
 109 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
 110 enum {
 111     PA_OK = 0,                     /**< No error */
 112     PA_ERR_ACCESS,                 /**< Access failure */
 113     PA_ERR_COMMAND,                /**< Unknown command */
 114     PA_ERR_INVALID,                /**< Invalid argument */
 115     PA_ERR_EXIST,                  /**< Entity exists */
 116     PA_ERR_NOENTITY,               /**< No such entity */
 117     PA_ERR_CONNECTIONREFUSED,      /**< Connection refused */
 118     PA_ERR_PROTOCOL,               /**< Protocol error */
 119     PA_ERR_TIMEOUT,                /**< Timeout */
 120     PA_ERR_AUTHKEY,                /**< No authorization key */
 121     PA_ERR_INTERNAL,               /**< Internal error */
 122     PA_ERR_CONNECTIONTERMINATED,   /**< Connection terminated */
 123     PA_ERR_KILLED,                 /**< Entity killed */
 124     PA_ERR_INVALIDSERVER,          /**< Invalid server */
 125     PA_ERR_MODINITFAILED,          /**< Module initialization failed */
 126     PA_ERR_BADSTATE,               /**< Bad state */
 127     PA_ERR_NODATA,                 /**< No data */
 128     PA_ERR_MAX                     /**< Not really an error but the first invalid error code */
 129 };
 130
 131 /** Subscription event mask, as used by pa_context_subscribe() */
 132 typedef enum pa_subscription_mask {
 133     PA_SUBSCRIPTION_MASK_NULL = 0,               /**< No events */
 134     PA_SUBSCRIPTION_MASK_SINK = 1,               /**< Sink events */
 135     PA_SUBSCRIPTION_MASK_SOURCE = 2,             /**< Source events */
 136     PA_SUBSCRIPTION_MASK_SINK_INPUT = 4,         /**< Sink input events */
 137     PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 8,      /**< Source output events */
 138     PA_SUBSCRIPTION_MASK_MODULE = 16,            /**< Module events */
 139     PA_SUBSCRIPTION_MASK_CLIENT = 32,            /**< Client events */
 140     PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64,      /**< Sample cache events */
 141     PA_SUBSCRIPTION_MASK_SERVER = 128,           /**< Other global server changes. \since 0.4 */
 142     PA_SUBSCRIPTION_MASK_AUTOLOAD = 256          /**< Autoload table events. \since 0.5 */
 143 } pa_subscription_mask_t;
 144
 145 /** Subscription event types, as used by pa_context_subscribe() */
 146 typedef enum pa_subscription_event_type {
 147     PA_SUBSCRIPTION_EVENT_SINK = 0,           /**< Event type: Sink */
 148     PA_SUBSCRIPTION_EVENT_SOURCE = 1,         /**< Event type: Source */
 149     PA_SUBSCRIPTION_EVENT_SINK_INPUT = 2,     /**< Event type: Sink input */
 150     PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 3,  /**< Event type: Source output */
 151     PA_SUBSCRIPTION_EVENT_MODULE = 4,         /**< Event type: Module */
 152     PA_SUBSCRIPTION_EVENT_CLIENT = 5,         /**< Event type: Client */
 153     PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6,   /**< Event type: Sample cache item */
 154     PA_SUBSCRIPTION_EVENT_SERVER = 7,         /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. \since 0.4  */
 155     PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8,       /**< Event type: Autoload table changes. \since 0.5 */
 156     PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */
 157
 158     PA_SUBSCRIPTION_EVENT_NEW = 0,            /**< A new object was created */
 159     PA_SUBSCRIPTION_EVENT_CHANGE = 16,        /**< A property of the object was modified */
 160     PA_SUBSCRIPTION_EVENT_REMOVE = 32,        /**< An object was removed */
 161     PA_SUBSCRIPTION_EVENT_TYPE_MASK = 16+32   /**< A mask to extract the event operation from an event value */
 162 } pa_subscription_event_type_t;
 163
 164 /** Return one if an event type t matches an event mask bitfield */
 165 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
 166
 167 /** A structure for latency info. See pa_stream_get_latency(). The
 168  * total output latency a sample that is written with
 169  * pa_stream_write() takes to be played may be estimated by
 170  * sink_usec+buffer_usec+transport_usec. The output buffer to which
 171  * buffer_usec relates may be manipulated freely (with
 172  * pa_stream_write()'s delta argument, pa_stream_flush() and friends),
 173  * the buffers sink_usec/source_usec relates to is a first-in
 174  * first-out buffer which cannot be flushed or manipulated in any
 175  * way. The total input latency a sample that is recorded takes to be
 176  * delivered to the application is:
 177  * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
 178  * sign issues!) When connected to a monitor source sink_usec contains
 179  * the latency of the owning sink.*/
 180 typedef struct pa_latency_info {
 181     pa_usec_t buffer_usec;    /**< Time in usecs the current buffer takes to play. For both playback and record streams. */
 182     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. */
 183     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*/
 184     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 */
 185     int playing;              /**< Non-zero when the stream is currently playing. Only for playback streams. */
 186     uint32_t queue_length;    /**< Queue size in bytes. For both playback and record streams. */
 187     int synchronized_clocks;  /**< Non-zero if the local and the
 188                                * remote machine have synchronized
 189                                * clocks. If synchronized clocks are
 190                                * detected transport_usec becomes much
 191                                * more reliable. However, the code that
 192                                * detects synchronized clocks is very
 193                                * limited und unreliable itself. \since
 194                                * 0.5 */
 195     struct timeval timestamp; /**< The time when this latency info was current */
 196     uint64_t counter;         /**< The byte counter current when the latency info was requested. \since 0.6 */
 197 } pa_latency_info;
 198
 199 /** A structure for the spawn api. This may be used to integrate auto
 200  * spawned daemons into your application. For more information see
 201  * pa_context_connect(). When spawning a new child process the
 202  * waitpid() is used on the child's PID. The spawn routine will not
 203  * block or ignore SIGCHLD signals, since this cannot be done in a
 204  * thread compatible way. You might have to do this in
 205  * prefork/postfork. \since 0.4 */
 206 typedef struct pa_spawn_api {
 207     void (*prefork)(void);     /**< Is called just before the fork in the parent process. May be NULL. */
 208     void (*postfork)(void);    /**< Is called immediately after the fork in the parent process. May be NULL.*/
 209     void (*atfork)(void);      /**< Is called immediately after the
 210                                 * fork in the child process. May be
 211                                 * NULL. It is not safe to close all
 212                                 * file descriptors in this function
 213                                 * unconditionally, since a UNIX socket
 214                                 * (created using socketpair()) is
 215                                 * passed to the new process. */
 216 } pa_spawn_api;
 217
 218 /** Seek type \since 0.8*/
 219 typedef enum pa_seek_mode {
 220     PA_SEEK_RELATIVE = 0,           /**< Seek relatively to the write index */
 221     PA_SEEK_ABSOLUTE = 1,           /**< Seek relatively to the start of the buffer queue */
 222     PA_SEEK_RELATIVE_ON_READ = 2,   /**< Seek relatively to the read index */
 223     PA_SEEK_RELATIVE_END = 3,       /**< Seek relatively to the current end of the buffer queue */
 224 } pa_seek_mode_t;
 225
 226
 227 PA_C_DECL_END
 228
 229 #endif