def.h

#ifndef foodefhfoo#define foodefhfoo/* $Id: def.h 2067 2007-11-21 01:30:40Z lennart $ *//*** This file is part of PulseAudio. Copyright 2004-2006 Lennart Poettering Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB PulseAudio is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. PulseAudio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with PulseAudio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.***/#include <inttypes.h>#include <sys/time.h>#include <time.h>#include <pulse/cdecl.h>#include <pulse/sample.h>/** \file * Global definitions */PA_C_DECL_BEGIN/** The state of a connection context */00041typedefenumpa_context_state {
00042PA_CONTEXT_UNCONNECTED, /**< The context hasn't been connected yet */00043PA_CONTEXT_CONNECTING, /**< A connection is being established */00044PA_CONTEXT_AUTHORIZING, /**< The client is authorizing itself to the daemon */00045PA_CONTEXT_SETTING_NAME, /**< The client is passing its application name to the daemon */00046PA_CONTEXT_READY, /**< The connection is established, the context is ready to execute operations */00047PA_CONTEXT_FAILED, /**< The connection failed or was disconnected */00048PA_CONTEXT_TERMINATED/**< The connection was terminated cleanly */
} pa_context_state_t;
/** The state of a stream */00052typedefenumpa_stream_state {
00053PA_STREAM_UNCONNECTED, /**< The stream is not yet connected to any sink or source */00054PA_STREAM_CREATING, /**< The stream is being created */00055PA_STREAM_READY, /**< The stream is established, you may pass audio data to it now */00056PA_STREAM_FAILED, /**< An error occured that made the stream invalid */00057PA_STREAM_TERMINATED/**< The stream has been terminated cleanly */
} pa_stream_state_t;
/** The state of an operation */00061typedefenumpa_operation_state {
00062PA_OPERATION_RUNNING, /**< The operation is still running */00063PA_OPERATION_DONE, /**< The operation has been completed */00064PA_OPERATION_CANCELED/**< The operation has been canceled */
} pa_operation_state_t;
/** An invalid index */00068#define PA_INVALID_INDEX ((uint32_t) -1)/** Some special flags for contexts. \since 0.8 */00071typedefenumpa_context_flags {
00072PA_CONTEXT_NOAUTOSPAWN = 1 /**< Disabled autospawning of the PulseAudio daemon if required */
} pa_context_flags_t;
/** The direction of a pa_stream object */00076typedefenumpa_stream_direction {
00077PA_STREAM_NODIRECTION, /**< Invalid direction */00078PA_STREAM_PLAYBACK, /**< Playback stream */00079PA_STREAM_RECORD, /**< Record stream */00080PA_STREAM_UPLOAD/**< Sample upload stream */
} pa_stream_direction_t;
/** Some special flags for stream connections. \since 0.6 */00084typedefenumpa_stream_flags {
00085PA_STREAM_START_CORKED = 1, /**< Create the stream corked, requiring an explicit pa_stream_cork() call to uncork it. */00086PA_STREAM_INTERPOLATE_TIMING = 2, /**< Interpolate the latency for * this stream. When enabled, * pa_stream_get_latency() and * pa_stream_get_time() will try * to estimate the current * record/playback time based on * the local time that passed * since the last timing info * update. Using this option * has the advantage of not * requiring a whole roundtrip * when the current * playback/recording time is * needed. Consider using this * option when requesting * latency information * frequently. This is * especially useful on long * latency network * connections. It makes a lot * of sense to combine this * option with * PA_STREAM_AUTO_TIMING_UPDATE. */00109PA_STREAM_NOT_MONOTONOUS = 4, /**< Don't force the time to * increase monotonically. If * this option is enabled, * pa_stream_get_time() will not * necessarily return always * monotonically increasing time * values on each call. This may * confuse applications which * cannot deal with time going * 'backwards', but has the * advantage that bad transport * latency estimations that * caused the time to to jump * ahead can be corrected * quickly, without the need to * wait. */00125PA_STREAM_AUTO_TIMING_UPDATE = 8, /**< If set timing update requests * are issued periodically * automatically. Combined with * PA_STREAM_INTERPOLATE_TIMING * you will be able to query the * current time and latency with * pa_stream_get_time() and * pa_stream_get_latency() at * all times without a packet * round trip.*/00135PA_STREAM_NO_REMAP_CHANNELS = 16, /**< Don't remap channels by * their name, instead map them * simply by their * index. Implies * PA_STREAM_NO_REMIX_CHANNELS. Only * supported when the server is * at least PA 0.9.8. It is * ignored on older * servers.\since 0.9.8 */00144PA_STREAM_NO_REMIX_CHANNELS = 32, /**< When remapping channels by * name, don't upmix or downmix * them to related * channels. Copy them into * matching channels of the * device 1:1. Only supported * when the server is at least * PA 0.9.8. It is ignored on * older servers. \since * 0.9.8 */00154PA_STREAM_FIX_FORMAT = 64, /**< Use the sample format of the * sink/device this stream is being * connected to, and possibly ignore * the format the sample spec contains * -- but you still have to pass a * valid value in it as a hint to * PulseAudio what would suit your * stream best. If this is used you * should query the used sample format * after creating the stream by using * pa_stream_get_sample_spec(). Also, * if you specified manual buffer * metrics it is recommended to update * them with * pa_stream_set_buffer_attr() to * compensate for the changed frame * sizes. Only supported when the * server is at least PA 0.9.8. It is * ignored on older servers. \since * 0.9.8 */00175PA_STREAM_FIX_RATE = 128, /**< Use the sample rate of the sink, * and possibly ignore the rate the * sample spec contains. Usage similar * to PA_STREAM_FIX_FORMAT.Only * supported when the server is at least * PA 0.9.8. It is ignored on older * servers. \since 0.9.8 */00183PA_STREAM_FIX_CHANNELS = 256, /**< Use the number of channels and * the channel map of the sink, and * possibly ignore the number of * channels and the map the sample spec * and the passed channel map * contains. Usage similar to * PA_STREAM_FIX_FORMAT. Only supported * when the server is at least PA * 0.9.8. It is ignored on older * servers. \since 0.9.8 */00193PA_STREAM_DONT_MOVE = 512, /**< Don't allow moving of this stream to * another sink/device. Useful if you use * any of the PA_STREAM_FIX_ flags and * want to make sure that resampling * never takes place -- which might * happen if the stream is moved to * another sink/source whith a different * sample spec/channel map. Only * supported when the server is at least * PA 0.9.8. It is ignored on older * servers. \since 0.9.8 */00204PA_STREAM_VARIABLE_RATE = 1024, /**< Allow dynamic changing of the * sampling rate during playback * with * pa_stream_update_sample_rate(). Only * supported when the server is at * least PA 0.9.8. It is ignored * on older servers. \since * 0.9.8 */
} pa_stream_flags_t;
/** Playback and record buffer metrics */00215typedefstruct pa_buffer_attr {
00216 uint32_t maxlength; /**< Maximum length of the buffer */00217 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 */00218 uint32_t prebuf; /**< Playback only: pre-buffering. The server does not start with playback before at least prebug bytes are available in the buffer */00219 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 */00220 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. */
} pa_buffer_attr;
/** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */enum {
00225PA_OK = 0, /**< No error */00226PA_ERR_ACCESS, /**< Access failure */00227PA_ERR_COMMAND, /**< Unknown command */00228PA_ERR_INVALID, /**< Invalid argument */00229PA_ERR_EXIST, /**< Entity exists */00230PA_ERR_NOENTITY, /**< No such entity */00231PA_ERR_CONNECTIONREFUSED, /**< Connection refused */00232PA_ERR_PROTOCOL, /**< Protocol error */00233PA_ERR_TIMEOUT, /**< Timeout */00234PA_ERR_AUTHKEY, /**< No authorization key */00235PA_ERR_INTERNAL, /**< Internal error */00236PA_ERR_CONNECTIONTERMINATED, /**< Connection terminated */00237PA_ERR_KILLED, /**< Entity killed */00238PA_ERR_INVALIDSERVER, /**< Invalid server */00239PA_ERR_MODINITFAILED, /**< Module initialization failed */00240PA_ERR_BADSTATE, /**< Bad state */00241PA_ERR_NODATA, /**< No data */00242PA_ERR_VERSION, /**< Incompatible protocol version \since 0.8 */00243PA_ERR_TOOLARGE, /**< Data too large \since 0.8.1 */00244PA_ERR_NOTSUPPORTED, /**< Operation not supported \since 0.9.5 */00245PA_ERR_MAX/**< Not really an error but the first invalid error code */
};
/** Subscription event mask, as used by pa_context_subscribe() */00249typedefenumpa_subscription_mask {
00250PA_SUBSCRIPTION_MASK_NULL = 0, /**< No events */00251PA_SUBSCRIPTION_MASK_SINK = 1, /**< Sink events */00252PA_SUBSCRIPTION_MASK_SOURCE = 2, /**< Source events */00253PA_SUBSCRIPTION_MASK_SINK_INPUT = 4, /**< Sink input events */00254PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 8, /**< Source output events */00255PA_SUBSCRIPTION_MASK_MODULE = 16, /**< Module events */00256PA_SUBSCRIPTION_MASK_CLIENT = 32, /**< Client events */00257PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64, /**< Sample cache events */00258PA_SUBSCRIPTION_MASK_SERVER = 128, /**< Other global server changes. \since 0.4 */00259PA_SUBSCRIPTION_MASK_AUTOLOAD = 256, /**< Autoload table events. \since 0.5 */00260PA_SUBSCRIPTION_MASK_ALL = 511 /**< Catch all events \since 0.8 */
} pa_subscription_mask_t;
/** Subscription event types, as used by pa_context_subscribe() */00264typedefenumpa_subscription_event_type {
00265PA_SUBSCRIPTION_EVENT_SINK = 0, /**< Event type: Sink */00266PA_SUBSCRIPTION_EVENT_SOURCE = 1, /**< Event type: Source */00267PA_SUBSCRIPTION_EVENT_SINK_INPUT = 2, /**< Event type: Sink input */00268PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 3, /**< Event type: Source output */00269PA_SUBSCRIPTION_EVENT_MODULE = 4, /**< Event type: Module */00270PA_SUBSCRIPTION_EVENT_CLIENT = 5, /**< Event type: Client */00271PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6, /**< Event type: Sample cache item */00272PA_SUBSCRIPTION_EVENT_SERVER = 7, /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. \since 0.4 */00273PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8, /**< Event type: Autoload table changes. \since 0.5 */00274PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */00276PA_SUBSCRIPTION_EVENT_NEW = 0, /**< A new object was created */00277PA_SUBSCRIPTION_EVENT_CHANGE = 16, /**< A property of the object was modified */00278PA_SUBSCRIPTION_EVENT_REMOVE = 32, /**< An object was removed */00279PA_SUBSCRIPTION_EVENT_TYPE_MASK = 16+32 /**< A mask to extract the event operation from an event value */
} pa_subscription_event_type_t;
/** Return one if an event type t matches an event mask bitfield */00283#define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))/** A structure for all kinds of timing information of a stream. See * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The * total output latency a sample that is written with * pa_stream_write() takes to be played may be estimated by * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined * as pa_bytes_to_usec(write_index-read_index)) The output buffer * which buffer_usec relates to may be manipulated freely (with * pa_stream_write()'s seek argument, pa_stream_flush() and friends), * the buffers sink_usec and source_usec relate to are first-in * first-out (FIFO) buffers which cannot be flushed or manipulated in * any way. The total input latency a sample that is recorded takes to * be delivered to the application is: * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of * sign issues!) When connected to a monitor source sink_usec contains * the latency of the owning sink. The two latency estimations * described here are implemented in pa_stream_get_latency().*/00301typedefstruct pa_timing_info {
00302struct timeval timestamp; /**< The time when this timing info structure was current */00303intsynchronized_clocks; /**< Non-zero if the local and the * remote machine have synchronized * clocks. If synchronized clocks are * detected transport_usec becomes much * more reliable. However, the code that * detects synchronized clocks is very * limited und unreliable itself. \since * 0.5 */00312pa_usec_tsink_usec; /**< Time in usecs a sample takes to be played on the sink. For playback streams and record streams connected to a monitor source. */00313pa_usec_tsource_usec; /**< Time in usecs a sample takes from being recorded to being delivered to the application. Only for record streams. \since 0.5*/00314pa_usec_ttransport_usec; /**< Estimated time in usecs a sample takes to be transferred to/from the daemon. For both playback and record streams. \since 0.5 */00316intplaying; /**< Non-zero when the stream is currently playing. Only for playback streams. */00318intwrite_index_corrupt; /**< Non-zero if write_index is not * up-to-date because a local write * command that corrupted it has been * issued in the time since this latency * info was current . Only write * commands with SEEK_RELATIVE_ON_READ * and SEEK_RELATIVE_END can corrupt * write_index. \since 0.8 */00326 int64_t write_index; /**< Current write index into the * playback buffer in bytes. Think twice before * using this for seeking purposes: it * might be out of date a the time you * want to use it. Consider using * PA_SEEK_RELATIVE instead. \since * 0.8 */00334intread_index_corrupt; /**< Non-zero if read_index is not * up-to-date because a local pause or * flush request that corrupted it has * been issued in the time since this * latency info was current. \since 0.8 */00340 int64_t read_index; /**< Current read index into the * playback buffer in bytes. Think twice before * using this for seeking purposes: it * might be out of date a the time you * want to use it. Consider using * PA_SEEK_RELATIVE_ON_READ * instead. \since 0.8 */
} pa_timing_info;
/** A structure for the spawn api. This may be used to integrate auto * spawned daemons into your application. For more information see * pa_context_connect(). When spawning a new child process the * waitpid() is used on the child's PID. The spawn routine will not * block or ignore SIGCHLD signals, since this cannot be done in a * thread compatible way. You might have to do this in * prefork/postfork. \since 0.4 */00356typedefstruct pa_spawn_api {
void (*prefork)(void); /**< Is called just before the fork in the parent process. May be NULL. */
void (*postfork)(void); /**< Is called immediately after the fork in the parent process. May be NULL.*/
void (*atfork)(void); /**< Is called immediately after the * fork in the child process. May be * NULL. It is not safe to close all * file descriptors in this function * unconditionally, since a UNIX socket * (created using socketpair()) is * passed to the new process. */
} pa_spawn_api;
/** Seek type for pa_stream_write(). \since 0.8*/00369typedefenumpa_seek_mode {
00370PA_SEEK_RELATIVE = 0, /**< Seek relatively to the write index */00371PA_SEEK_ABSOLUTE = 1, /**< Seek relatively to the start of the buffer queue */00372PA_SEEK_RELATIVE_ON_READ = 2, /**< Seek relatively to the read index. */00373PA_SEEK_RELATIVE_END = 3 /**< Seek relatively to the current end of the buffer queue. */
} pa_seek_mode_t;
/** Special sink flags. \since 0.8 */00377typedefenumpa_sink_flags {
00378PA_SINK_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */00379PA_SINK_LATENCY = 2, /**< Supports latency querying */00380PA_SINK_HARDWARE = 4, /**< Is a hardware sink of some kind, in contrast to "virtual"/software sinks \since 0.9.3 */00381PA_SINK_NETWORK = 8 /**< Is a networked sink of some kind. \since 0.9.7 */
} pa_sink_flags_t;
/** Special source flags. \since 0.8 */00385typedefenumpa_source_flags {
00386PA_SOURCE_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */00387PA_SOURCE_LATENCY = 2, /**< Supports latency querying */00388PA_SOURCE_HARDWARE = 4, /**< Is a hardware source of some kind, in contrast to "virtual"/software source \since 0.9.3 */00389PA_SOURCE_NETWORK = 8 /**< Is a networked sink of some kind. \since 0.9.7 */
} pa_source_flags_t;
/** A generic free() like callback prototype */00393typedef void (*pa_free_cb_t)(void *p);
PA_C_DECL_END#endif