| #ifndef foostreamhfoo |
| #define foostreamhfoo |
| |
| /*** |
| 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 |
| 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 <sys/types.h> |
| |
| #include <pulse/sample.h> |
| #include <pulse/format.h> |
| #include <pulse/channelmap.h> |
| #include <pulse/volume.h> |
| #include <pulse/def.h> |
| #include <pulse/cdecl.h> |
| #include <pulse/operation.h> |
| #include <pulse/context.h> |
| #include <pulse/proplist.h> |
| |
| /** \page streams Audio Streams |
| * |
| * \section overv_sec Overview |
| * |
| * Audio streams form the central functionality of the sound server. Data is |
| * routed, converted and mixed from several sources before it is passed along |
| * to a final output. Currently, there are three forms of audio streams: |
| * |
| * \li Playback streams - Data flows from the client to the server. |
| * \li Record streams - Data flows from the server to the client. |
| * \li Upload streams - Similar to playback streams, but the data is stored in |
| * the sample cache. See \ref scache for more information |
| * about controlling the sample cache. |
| * |
| * \section create_sec Creating |
| * |
| * To access a stream, a pa_stream object must be created using |
| * pa_stream_new(). At this point the audio sample format and mapping of |
| * channels must be specified. See \ref sample and \ref channelmap for more |
| * information about those structures. |
| * |
| * This first step will only create a client-side object, representing the |
| * stream. To use the stream, a server-side object must be created and |
| * associated with the local object. Depending on which type of stream is |
| * desired, a different function is needed: |
| * |
| * \li Playback stream - pa_stream_connect_playback() |
| * \li Record stream - pa_stream_connect_record() |
| * \li Upload stream - pa_stream_connect_upload() (see \ref scache) |
| * |
| * Similar to how connections are done in contexts, connecting a stream will |
| * not generate a pa_operation object. Also like contexts, the application |
| * should register a state change callback, using |
| * pa_stream_set_state_callback(), and wait for the stream to enter an active |
| * state. |
| * |
| * \subsection bufattr_subsec Buffer Attributes |
| * |
| * Playback and record streams always have a server-side buffer as |
| * part of the data flow. The size of this buffer needs to be chosen |
| * in a compromise between low latency and sensitivity for buffer |
| * overflows/underruns. |
| * |
| * The buffer metrics may be controlled by the application. They are |
| * described with a pa_buffer_attr structure which contains a number |
| * of fields: |
| * |
| * \li maxlength - The absolute maximum number of bytes that can be |
| * stored in the buffer. If this value is exceeded |
| * then data will be lost. It is recommended to pass |
| * (uint32_t) -1 here which will cause the server to |
| * fill in the maximum possible value. |
| * |
| * \li tlength - The target fill level of the playback buffer. The |
| * server will only send requests for more data as long |
| * as the buffer has less than this number of bytes of |
| * data. If you pass (uint32_t) -1 (which is |
| * recommended) here the server will choose the longest |
| * target buffer fill level possible to minimize the |
| * number of necessary wakeups and maximize drop-out |
| * safety. This can exceed 2s of buffering. For |
| * low-latency applications or applications where |
| * latency matters you should pass a proper value here. |
| * |
| * \li prebuf - Number of bytes that need to be in the buffer before |
| * playback will commence. Start of playback can be |
| * forced using pa_stream_trigger() even though the |
| * prebuffer size hasn't been reached. If a buffer |
| * underrun occurs, this prebuffering will be again |
| * enabled. If the playback shall never stop in case of a |
| * buffer underrun, this value should be set to 0. In |
| * that case the read index of the output buffer |
| * overtakes the write index, and hence the fill level of |
| * the buffer is negative. If you pass (uint32_t) -1 here |
| * (which is recommended) the server will choose the same |
| * value as tlength here. |
| * |
| * \li minreq - Minimum free number of the bytes in the playback |
| * buffer before the server will request more data. It is |
| * recommended to fill in (uint32_t) -1 here. This value |
| * influences how much time the sound server has to move |
| * data from the per-stream server-side playback buffer |
| * to the hardware playback buffer. |
| * |
| * \li fragsize - Maximum number of bytes that the server will push in |
| * one chunk for record streams. If you pass (uint32_t) |
| * -1 (which is recommended) here, the server will |
| * choose the longest fragment setting possible to |
| * minimize the number of necessary wakeups and |
| * maximize drop-out safety. This can exceed 2s of |
| * buffering. For low-latency applications or |
| * applications where latency matters you should pass a |
| * proper value here. |
| * |
| * If PA_STREAM_ADJUST_LATENCY is set, then the tlength/fragsize |
| * parameters will be interpreted slightly differently than described |
| * above when passed to pa_stream_connect_record() and |
| * pa_stream_connect_playback(): the overall latency that is comprised |
| * of both the server side playback buffer length, the hardware |
| * playback buffer length and additional latencies will be adjusted in |
| * a way that it matches tlength resp. fragsize. Set |
| * PA_STREAM_ADJUST_LATENCY if you want to control the overall |
| * playback latency for your stream. Unset it if you want to control |
| * only the latency induced by the server-side, rewritable playback |
| * buffer. The server will try to fulfill the clients latency requests |
| * as good as possible. However if the underlying hardware cannot |
| * change the hardware buffer length or only in a limited range, the |
| * actually resulting latency might be different from what the client |
| * requested. Thus, for synchronization clients always need to check |
| * the actual measured latency via pa_stream_get_latency() or a |
| * similar call, and not make any assumptions. about the latency |
| * available. The function pa_stream_get_buffer_attr() will always |
| * return the actual size of the server-side per-stream buffer in |
| * tlength/fragsize, regardless whether PA_STREAM_ADJUST_LATENCY is |
| * set or not. |
| * |
| * The server-side per-stream playback buffers are indexed by a write and a read |
| * index. The application writes to the write index and the sound |
| * device reads from the read index. The read index is increased |
| * monotonically, while the write index may be freely controlled by |
| * the application. Subtracting the read index from the write index |
| * will give you the current fill level of the buffer. The read/write |
| * indexes are 64bit values and measured in bytes, they will never |
| * wrap. The current read/write index may be queried using |
| * pa_stream_get_timing_info() (see below for more information). In |
| * case of a buffer underrun the read index is equal or larger than |
| * the write index. Unless the prebuf value is 0, PulseAudio will |
| * temporarily pause playback in such a case, and wait until the |
| * buffer is filled up to prebuf bytes again. If prebuf is 0, the |
| * read index may be larger than the write index, in which case |
| * silence is played. If the application writes data to indexes lower |
| * than the read index, the data is immediately lost. |
| * |
| * \section transfer_sec Transferring Data |
| * |
| * Once the stream is up, data can start flowing between the client and the |
| * server. Two different access models can be used to transfer the data: |
| * |
| * \li Asynchronous - The application register a callback using |
| * pa_stream_set_write_callback() and |
| * pa_stream_set_read_callback() to receive notifications |
| * that data can either be written or read. |
| * \li Polled - Query the library for available data/space using |
| * pa_stream_writable_size() and pa_stream_readable_size() and |
| * transfer data as needed. The sizes are stored locally, in the |
| * client end, so there is no delay when reading them. |
| * |
| * It is also possible to mix the two models freely. |
| * |
| * Once there is data/space available, it can be transferred using either |
| * pa_stream_write() for playback, or pa_stream_peek() / pa_stream_drop() for |
| * record. Make sure you do not overflow the playback buffers as data will be |
| * dropped. |
| * |
| * \section bufctl_sec Buffer Control |
| * |
| * The transfer buffers can be controlled through a number of operations: |
| * |
| * \li pa_stream_cork() - Start or stop the playback or recording. |
| * \li pa_stream_trigger() - Start playback immediately and do not wait for |
| * the buffer to fill up to the set trigger level. |
| * \li pa_stream_prebuf() - Reenable the playback trigger level. |
| * \li pa_stream_drain() - Wait for the playback buffer to go empty. Will |
| * return a pa_operation object that will indicate when |
| * the buffer is completely drained. |
| * \li pa_stream_flush() - Drop all data from the playback buffer and do not |
| * wait for it to finish playing. |
| * |
| * \section seek_modes Seeking in the Playback Buffer |
| * |
| * A client application may freely seek in the playback buffer. To |
| * accomplish that the pa_stream_write() function takes a seek mode |
| * and an offset argument. The seek mode is one of: |
| * |
| * \li PA_SEEK_RELATIVE - seek relative to the current write index |
| * \li PA_SEEK_ABSOLUTE - seek relative to the beginning of the playback buffer, (i.e. the first that was ever played in the stream) |
| * \li PA_SEEK_RELATIVE_ON_READ - seek relative to the current read index. Use this to write data to the output buffer that should be played as soon as possible |
| * \li PA_SEEK_RELATIVE_END - seek relative to the last byte ever written. |
| * |
| * If an application just wants to append some data to the output |
| * buffer, PA_SEEK_RELATIVE and an offset of 0 should be used. |
| * |
| * After a call to pa_stream_write() the write index will be left at |
| * the position right after the last byte of the written data. |
| * |
| * \section latency_sec Latency |
| * |
| * A major problem with networked audio is the increased latency caused by |
| * the network. To remedy this, PulseAudio supports an advanced system of |
| * monitoring the current latency. |
| * |
| * To get the raw data needed to calculate latencies, call |
| * pa_stream_get_timing_info(). This will give you a pa_timing_info |
| * structure that contains everything that is known about the server |
| * side buffer transport delays and the backend active in the |
| * server. (Besides other things it contains the write and read index |
| * values mentioned above.) |
| * |
| * This structure is updated every time a |
| * pa_stream_update_timing_info() operation is executed. (i.e. before |
| * the first call to this function the timing information structure is |
| * not available!) Since it is a lot of work to keep this structure |
| * up-to-date manually, PulseAudio can do that automatically for you: |
| * if PA_STREAM_AUTO_TIMING_UPDATE is passed when connecting the |
| * stream PulseAudio will automatically update the structure every |
| * 100ms and every time a function is called that might invalidate the |
| * previously known timing data (such as pa_stream_write() or |
| * pa_stream_flush()). Please note however, that there always is a |
| * short time window when the data in the timing information structure |
| * is out-of-date. PulseAudio tries to mark these situations by |
| * setting the write_index_corrupt and read_index_corrupt fields |
| * accordingly. |
| * |
| * The raw timing data in the pa_timing_info structure is usually hard |
| * to deal with. Therefore a simpler interface is available: |
| * you can call pa_stream_get_time() or pa_stream_get_latency(). The |
| * former will return the current playback time of the hardware since |
| * the stream has been started. The latter returns the overall time a sample |
| * that you write now takes to be played by the hardware. These two |
| * functions base their calculations on the same data that is returned |
| * by pa_stream_get_timing_info(). Hence the same rules for keeping |
| * the timing data up-to-date apply here. In case the write or read |
| * index is corrupted, these two functions will fail with |
| * PA_ERR_NODATA set. |
| * |
| * Since updating the timing info structure usually requires a full |
| * network round trip and some applications monitor the timing very |
| * often PulseAudio offers a timing interpolation system. If |
| * PA_STREAM_INTERPOLATE_TIMING is passed when connecting the stream, |
| * pa_stream_get_time() and pa_stream_get_latency() will try to |
| * interpolate the current playback time/latency by estimating the |
| * number of samples that have been played back by the hardware since |
| * the last regular timing update. It is especially useful to combine |
| * this option with PA_STREAM_AUTO_TIMING_UPDATE, which will enable |
| * you to monitor the current playback time/latency very precisely and |
| * very frequently without requiring a network round trip every time. |
| * |
| * \section flow_sec Overflow and underflow |
| * |
| * Even with the best precautions, buffers will sometime over - or |
| * underflow. To handle this gracefully, the application can be |
| * notified when this happens. Callbacks are registered using |
| * pa_stream_set_overflow_callback() and |
| * pa_stream_set_underflow_callback(). |
| * |
| * \section sync_streams Synchronizing Multiple Playback Streams |
| * |
| * PulseAudio allows applications to fully synchronize multiple |
| * playback streams that are connected to the same output device. That |
| * means the streams will always be played back sample-by-sample |
| * synchronously. If stream operations like pa_stream_cork() are |
| * issued on one of the synchronized streams, they are simultaneously |
| * issued on the others. |
| * |
| * To synchronize a stream to another, just pass the "master" stream |
| * as last argument to pa_stream_connect_playback(). To make sure that |
| * the freshly created stream doesn't start playback right-away, make |
| * sure to pass PA_STREAM_START_CORKED and - after all streams have |
| * been created - uncork them all with a single call to |
| * pa_stream_cork() for the master stream. |
| * |
| * To make sure that a particular stream doesn't stop to play when a |
| * server side buffer underrun happens on it while the other |
| * synchronized streams continue playing and hence deviate you need to |
| * pass a "prebuf" pa_buffer_attr of 0 when connecting it. |
| * |
| * \section disc_sec Disconnecting |
| * |
| * When a stream has served is purpose it must be disconnected with |
| * pa_stream_disconnect(). If you only unreference it, then it will live on |
| * and eat resources both locally and on the server until you disconnect the |
| * context. |
| * |
| */ |
| |
| /** \file |
| * Audio streams for input, output and sample upload |
| * |
| * See also \subpage streams |
| */ |
| |
| PA_C_DECL_BEGIN |
| |
| /** An opaque stream for playback or recording */ |
| typedef struct pa_stream pa_stream; |
| |
| /** A generic callback for operation completion */ |
| typedef void (*pa_stream_success_cb_t) (pa_stream*s, int success, void *userdata); |
| |
| /** A generic request callback */ |
| typedef void (*pa_stream_request_cb_t)(pa_stream *p, size_t nbytes, void *userdata); |
| |
| /** A generic notification callback */ |
| typedef void (*pa_stream_notify_cb_t)(pa_stream *p, void *userdata); |
| |
| /** A callback for asynchronous meta/policy event messages. Well known |
| * event names are PA_STREAM_EVENT_REQUEST_CORK and |
| * PA_STREAM_EVENT_REQUEST_UNCORK. The set of defined events can be |
| * extended at any time. Also, server modules may introduce additional |
| * message types so make sure that your callback function ignores messages |
| * it doesn't know. \since 0.9.15 */ |
| typedef void (*pa_stream_event_cb_t)(pa_stream *p, const char *name, pa_proplist *pl, void *userdata); |
| |
| /** Create a new, unconnected stream with the specified name and |
| * sample type. It is recommended to use pa_stream_new_with_proplist() |
| * instead and specify some initial properties. */ |
| pa_stream* pa_stream_new( |
| pa_context *c /**< The context to create this stream in */, |
| const char *name /**< A name for this stream */, |
| const pa_sample_spec *ss /**< The desired sample format */, |
| const pa_channel_map *map /**< The desired channel map, or NULL for default */); |
| |
| /** Create a new, unconnected stream with the specified name and |
| * sample type, and specify the the initial stream property |
| * list. \since 0.9.11 */ |
| pa_stream* pa_stream_new_with_proplist( |
| pa_context *c /**< The context to create this stream in */, |
| const char *name /**< A name for this stream */, |
| const pa_sample_spec *ss /**< The desired sample format */, |
| const pa_channel_map *map /**< The desired channel map, or NULL for default */, |
| pa_proplist *p /**< The initial property list */); |
| |
| /** Create a new, unconnected stream with the specified name, the set of formats |
| * this client can provide, and an initial list of properties. While |
| * connecting, the server will select the most appropriate format which the |
| * client must then provide. \since 1.0 */ |
| pa_stream *pa_stream_new_extended( |
| pa_context *c /**< The context to create this stream in */, |
| const char *name /**< A name for this stream */, |
| pa_format_info * const * formats /**< The list of formats that can be provided */, |
| unsigned int n_formats /**< The number of formats being passed in */, |
| pa_proplist *p /**< The initial property list */); |
| |
| /** Decrease the reference counter by one */ |
| void pa_stream_unref(pa_stream *s); |
| |
| /** Increase the reference counter by one */ |
| pa_stream *pa_stream_ref(pa_stream *s); |
| |
| /** Return the current state of the stream */ |
| pa_stream_state_t pa_stream_get_state(pa_stream *p); |
| |
| /** Return the context this stream is attached to */ |
| pa_context* pa_stream_get_context(pa_stream *p); |
| |
| /** Return the sink input resp. source output index this stream is |
| * identified in the server with. This is useful for usage with the |
| * introspection functions, such as pa_context_get_sink_input_info() |
| * resp. pa_context_get_source_output_info(). */ |
| uint32_t pa_stream_get_index(pa_stream *s); |
| |
| /** Return the index of the sink or source this stream is connected to |
| * in the server. This is useful for usage with the introspection |
| * functions, such as pa_context_get_sink_info_by_index() |
| * resp. pa_context_get_source_info_by_index(). Please note that |
| * streams may be moved between sinks/sources and thus it is |
| * recommended to use pa_stream_set_moved_callback() to be notified |
| * about this. This function will return with PA_ERR_NOTSUPPORTED when the |
| * server is older than 0.9.8. \since 0.9.8 */ |
| uint32_t pa_stream_get_device_index(pa_stream *s); |
| |
| /** Return the name of the sink or source this stream is connected to |
| * in the server. This is useful for usage with the introspection |
| * functions, such as pa_context_get_sink_info_by_name() |
| * resp. pa_context_get_source_info_by_name(). Please note that |
| * streams may be moved between sinks/sources and thus it is |
| * recommended to use pa_stream_set_moved_callback() to be notified |
| * about this. This function will return with PA_ERR_NOTSUPPORTED when the |
| * server is older than 0.9.8. \since 0.9.8 */ |
| const char *pa_stream_get_device_name(pa_stream *s); |
| |
| /** Return 1 if the sink or source this stream is connected to has |
| * been suspended. This will return 0 if not, and negative on |
| * error. This function will return with PA_ERR_NOTSUPPORTED when the |
| * server is older than 0.9.8. \since 0.9.8 */ |
| int pa_stream_is_suspended(pa_stream *s); |
| |
| /** Return 1 if the this stream has been corked. This will return 0 if |
| * not, and negative on error. \since 0.9.11 */ |
| int pa_stream_is_corked(pa_stream *s); |
| |
| /** Connect the stream to a sink. It is strongly recommended to pass |
| * NULL in both dev and volume and not to set either |
| * PA_STREAM_START_MUTED nor PA_STREAM_START_UNMUTED -- unless these |
| * options are directly dependent on user input or configuration. If |
| * you follow this rule then the sound server will have the full |
| * flexibility to choose the device, volume and mute status |
| * automatically, based on server-side policies, heuristics and stored |
| * information from previous uses. Also the server may choose to |
| * reconfigure audio devices to make other sinks/sources or |
| * capabilities available to be able to accept the stream. Before |
| * 0.9.20 it was not defined whether the 'volume' parameter was |
| * interpreted relative to the sink's current volume or treated as |
| * absolute device volume. Since 0.9.20 it is an absolute volume when |
| * the sink is in flat volume mode, and relative otherwise, thus |
| * making sure the volume passed here has always the same semantics as |
| * the volume passed to pa_context_set_sink_input_volume(). */ |
| int pa_stream_connect_playback( |
| pa_stream *s /**< The stream to connect to a sink */, |
| const char *dev /**< Name of the sink to connect to, or NULL for default */ , |
| const pa_buffer_attr *attr /**< Buffering attributes, or NULL for default */, |
| pa_stream_flags_t flags /**< Additional flags, or 0 for default */, |
| const pa_cvolume *volume /**< Initial volume, or NULL for default */, |
| pa_stream *sync_stream /**< Synchronize this stream with the specified one, or NULL for a standalone stream*/); |
| |
| /** Connect the stream to a source */ |
| int pa_stream_connect_record( |
| pa_stream *s /**< The stream to connect to a source */ , |
| const char *dev /**< Name of the source to connect to, or NULL for default */, |
| const pa_buffer_attr *attr /**< Buffer attributes, or NULL for default */, |
| pa_stream_flags_t flags /**< Additional flags, or 0 for default */); |
| |
| /** Disconnect a stream from a source/sink */ |
| int pa_stream_disconnect(pa_stream *s); |
| |
| /** Prepare writing data to the server (for playback streams). This |
| * function may be used to optimize the number of memory copies when |
| * doing playback ("zero-copy"). It is recommended to call this |
| * function before each call to pa_stream_write(). Pass in the address |
| * to a pointer and an address of the number of bytes you want to |
| * write. On return the two values will contain a pointer where you |
| * can place the data to write and the maximum number of bytes you can |
| * write. On return *nbytes can be smaller or have the same value as |
| * you passed in. You need to be able to handle both cases. Accessing |
| * memory beyond the returned *nbytes value is invalid. Accessing the |
| * memory returned after the following pa_stream_write() or |
| * pa_stream_cancel_write() is invalid. On invocation only *nbytes |
| * needs to be initialized, on return both *data and *nbytes will be |
| * valid. If you place (size_t) -1 in *nbytes on invocation the memory |
| * size will be chosen automatically (which is recommended to |
| * do). After placing your data in the memory area returned call |
| * pa_stream_write() with data set to an address within this memory |
| * area and an nbytes value that is smaller or equal to what was |
| * returned by this function to actually execute the write. An |
| * invocation of pa_stream_write() should follow "quickly" on |
| * pa_stream_begin_write(). It is not recommended letting an unbounded |
| * amount of time pass after calling pa_stream_begin_write() and |
| * before calling pa_stream_write(). If you want to cancel a |
| * previously called pa_stream_begin_write() without calling |
| * pa_stream_write() use pa_stream_cancel_write(). Calling |
| * pa_stream_begin_write() twice without calling pa_stream_write() or |
| * pa_stream_cancel_write() in between will return exactly the same |
| * pointer/nbytes values.\since 0.9.16 */ |
| int pa_stream_begin_write( |
| pa_stream *p, |
| void **data, |
| size_t *nbytes); |
| |
| /** Reverses the effect of pa_stream_begin_write() dropping all data |
| * that has already been placed in the memory area returned by |
| * pa_stream_begin_write(). Only valid to call if |
| * pa_stream_begin_write() was called before and neither |
| * pa_stream_cancel_write() nor pa_stream_write() have been called |
| * yet. Accessing the memory previously returned by |
| * pa_stream_begin_write() after this call is invalid. Any further |
| * explicit freeing of the memory area is not necessary. \since |
| * 0.9.16 */ |
| int pa_stream_cancel_write( |
| pa_stream *p); |
| |
| /** Write some data to the server (for playback streams), if free_cb |
| * is non-NULL this routine is called when all data has been written |
| * out and an internal reference to the specified data is kept, the |
| * data is not copied. If NULL, the data is copied into an internal |
| * buffer. The client may freely seek around in the output buffer. For |
| * most applications passing 0 and PA_SEEK_RELATIVE as arguments for |
| * offset and seek should be useful. After the write call succeeded |
| * the write index will be at the position after where this chunk of |
| * data has been written to. |
| * |
| * As an optimization for avoiding needless memory copies you may call |
| * pa_stream_begin_write() before this call and then place your audio |
| * data directly in the memory area returned by that call. Then, pass |
| * a pointer to that memory area to pa_stream_write(). After the |
| * invocation of pa_stream_write() the memory area may no longer be |
| * accessed. Any further explicit freeing of the memory area is not |
| * necessary. It is OK to write the memory area returned by |
| * pa_stream_begin_write() only partially with this call, skipping |
| * bytes both at the end and at the beginning of the reserved memory |
| * area.*/ |
| int pa_stream_write( |
| pa_stream *p /**< The stream to use */, |
| const void *data /**< The data to write */, |
| size_t nbytes /**< The length of the data to write in bytes*/, |
| pa_free_cb_t free_cb /**< A cleanup routine for the data or NULL to request an internal copy */, |
| int64_t offset, /**< Offset for seeking, must be 0 for upload streams */ |
| pa_seek_mode_t seek /**< Seek mode, must be PA_SEEK_RELATIVE for upload streams */); |
| |
| /** Read the next fragment from the buffer (for recording streams). |
| * data will point to the actual data and nbytes will contain the size |
| * of the data in bytes (which can be less or more than a complete |
| * fragment). Use pa_stream_drop() to actually remove the data from |
| * the buffer. If no data is available this will return a NULL |
| * pointer */ |
| int pa_stream_peek( |
| pa_stream *p /**< The stream to use */, |
| const void **data /**< Pointer to pointer that will point to data */, |
| size_t *nbytes /**< The length of the data read in bytes */); |
| |
| /** Remove the current fragment on record streams. It is invalid to do this without first |
| * calling pa_stream_peek(). */ |
| int pa_stream_drop(pa_stream *p); |
| |
| /** Return the number of bytes that may be written using pa_stream_write() */ |
| size_t pa_stream_writable_size(pa_stream *p); |
| |
| /** Return the number of bytes that may be read using pa_stream_peek()*/ |
| size_t pa_stream_readable_size(pa_stream *p); |
| |
| /** Drain a playback stream. Use this for notification when the |
| * playback buffer is empty after playing all the audio in the buffer. |
| * Please note that only one drain operation per stream may be issued |
| * at a time. */ |
| pa_operation* pa_stream_drain(pa_stream *s, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Request a timing info structure update for a stream. Use |
| * pa_stream_get_timing_info() to get access to the raw timing data, |
| * or pa_stream_get_time() or pa_stream_get_latency() to get cleaned |
| * up values. */ |
| pa_operation* pa_stream_update_timing_info(pa_stream *p, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called whenever the state of the stream changes */ |
| void pa_stream_set_state_callback(pa_stream *s, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called when new data may be |
| * written to the stream. */ |
| void pa_stream_set_write_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called when new data is available from the stream. |
| * Return the number of bytes read.*/ |
| void pa_stream_set_read_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called when a buffer overflow happens. (Only for playback streams) */ |
| void pa_stream_set_overflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Return at what position the latest underflow occurred, or -1 if this information is not |
| * known (e g if no underflow has occurred, or server is older than 1.0). |
| * Can be used inside the underflow callback to get information about the current underflow. |
| * (Only for playback streams) \since 1.0 */ |
| int64_t pa_stream_get_underflow_index(pa_stream *p); |
| |
| /** Set the callback function that is called when a buffer underflow happens. (Only for playback streams) */ |
| void pa_stream_set_underflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called when a the server starts |
| * playback after an underrun or on initial startup. This only informs |
| * that audio is flowing again, it is no indication that audio started |
| * to reach the speakers already. (Only for playback streams). \since |
| * 0.9.11 */ |
| void pa_stream_set_started_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called whenever a latency |
| * information update happens. Useful on PA_STREAM_AUTO_TIMING_UPDATE |
| * streams only. (Only for playback streams) */ |
| void pa_stream_set_latency_update_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called whenever the stream is |
| * moved to a different sink/source. Use pa_stream_get_device_name()or |
| * pa_stream_get_device_index() to query the new sink/source. This |
| * notification is only generated when the server is at least |
| * 0.9.8. \since 0.9.8 */ |
| void pa_stream_set_moved_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called whenever the sink/source |
| * this stream is connected to is suspended or resumed. Use |
| * pa_stream_is_suspended() to query the new suspend status. Please |
| * note that the suspend status might also change when the stream is |
| * moved between devices. Thus if you call this function you very |
| * likely want to call pa_stream_set_moved_callback, too. This |
| * notification is only generated when the server is at least |
| * 0.9.8. \since 0.9.8 */ |
| void pa_stream_set_suspended_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called whenever a meta/policy |
| * control event is received.\since 0.9.15 */ |
| void pa_stream_set_event_callback(pa_stream *p, pa_stream_event_cb_t cb, void *userdata); |
| |
| /** Set the callback function that is called whenever the buffer |
| * attributes on the server side change. Please note that the buffer |
| * attributes can change when moving a stream to a different |
| * sink/source too, hence if you use this callback you should use |
| * pa_stream_set_moved_callback() as well. \since 0.9.15 */ |
| void pa_stream_set_buffer_attr_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata); |
| |
| /** Pause (or resume) playback of this stream temporarily. Available |
| * on both playback and recording streams. If b is 1 the stream is |
| * paused. If b is 0 the stream is resumed. The pause/resume operation |
| * is executed as quickly as possible. If a cork is very quickly |
| * followed by an uncork or the other way round this might not |
| * actually have any effect on the stream that is output. You can use |
| * pa_stream_is_corked() to find out whether the stream is currently |
| * paused or not. Normally a stream will be created in uncorked |
| * state. If you pass PA_STREAM_START_CORKED as flag during connection |
| * of the stream it will be created in corked state. */ |
| pa_operation* pa_stream_cork(pa_stream *s, int b, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Flush the playback buffer of this stream. This discards any audio |
| * in the buffer. Most of the time you're better off using the parameter |
| * delta of pa_stream_write() instead of this function. Available on both |
| * playback and recording streams. */ |
| pa_operation* pa_stream_flush(pa_stream *s, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Reenable prebuffering as specified in the pa_buffer_attr |
| * structure. Available for playback streams only. */ |
| pa_operation* pa_stream_prebuf(pa_stream *s, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Request immediate start of playback on this stream. This disables |
| * prebuffering as specified in the pa_buffer_attr structure, |
| * temporarily. Available for playback streams only. */ |
| pa_operation* pa_stream_trigger(pa_stream *s, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Rename the stream. */ |
| pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Return the current playback/recording time. This is based on the |
| * data in the timing info structure returned by |
| * pa_stream_get_timing_info(). |
| * |
| * This function will usually only return new data if a timing info |
| * update has been received. Only if timing interpolation has been |
| * requested (PA_STREAM_INTERPOLATE_TIMING) the data from the last |
| * timing update is used for an estimation of the current |
| * playback/recording time based on the local time that passed since |
| * the timing info structure has been acquired. |
| * |
| * The time value returned by this function is guaranteed to increase |
| * monotonically. (that means: the returned value is always greater |
| * or equal to the value returned on the last call). This behaviour |
| * can be disabled by using PA_STREAM_NOT_MONOTONIC. This may be |
| * desirable to deal better with bad estimations of transport |
| * latencies, but may have strange effects if the application is not |
| * able to deal with time going 'backwards'. |
| * |
| * The time interpolator activated by PA_STREAM_INTERPOLATE_TIMING |
| * favours 'smooth' time graphs over accurate ones to improve the |
| * smoothness of UI operations that are tied to the audio clock. If |
| * accuracy is more important to you you might need to estimate your |
| * timing based on the data from pa_stream_get_timing_info() yourself |
| * or not work with interpolated timing at all and instead always |
| * query on the server side for the most up to date timing with |
| * pa_stream_update_timing_info(). |
| * |
| * If no timing information has been |
| * received yet this call will return PA_ERR_NODATA. For more details |
| * see pa_stream_get_timing_info(). */ |
| int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec); |
| |
| /** Return the total stream latency. This function is based on |
| * pa_stream_get_time(). |
| * |
| * In case the stream is a monitoring stream the result can be |
| * negative, i.e. the captured samples are not yet played. In this |
| * case *negative is set to 1. |
| * |
| * If no timing information has been received yet this call will |
| * return PA_ERR_NODATA. For more details see |
| * pa_stream_get_timing_info() and pa_stream_get_time(). */ |
| int pa_stream_get_latency(pa_stream *s, pa_usec_t *r_usec, int *negative); |
| |
| /** Return the latest raw timing data structure. The returned pointer |
| * points to an internal read-only instance of the timing |
| * structure. The user should make a copy of this structure if he |
| * wants to modify it. An in-place update to this data structure may |
| * be requested using pa_stream_update_timing_info(). |
| * |
| * If no timing information has been received before (i.e. by |
| * requesting pa_stream_update_timing_info() or by using |
| * PA_STREAM_AUTO_TIMING_UPDATE), this function will fail with |
| * PA_ERR_NODATA. |
| * |
| * Please note that the write_index member field (and only this field) |
| * is updated on each pa_stream_write() call, not just when a timing |
| * update has been received. */ |
| const pa_timing_info* pa_stream_get_timing_info(pa_stream *s); |
| |
| /** Return a pointer to the stream's sample specification. */ |
| const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s); |
| |
| /** Return a pointer to the stream's channel map. */ |
| const pa_channel_map* pa_stream_get_channel_map(pa_stream *s); |
| |
| /** Return a pointer to the stream's format \since 1.0 */ |
| const pa_format_info* pa_stream_get_format_info(pa_stream *s); |
| |
| /** Return the per-stream server-side buffer metrics of the |
| * stream. Only valid after the stream has been connected successfully |
| * and if the server is at least PulseAudio 0.9. This will return the |
| * actual configured buffering metrics, which may differ from what was |
| * requested during pa_stream_connect_record() or |
| * pa_stream_connect_playback(). This call will always return the |
| * actually per-stream server-side buffer metrics, regardless whether |
| * PA_STREAM_ADJUST_LATENCY is set or not. \since 0.9.0 */ |
| const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s); |
| |
| /** Change the buffer metrics of the stream during playback. The |
| * server might have chosen different buffer metrics then |
| * requested. The selected metrics may be queried with |
| * pa_stream_get_buffer_attr() as soon as the callback is called. Only |
| * valid after the stream has been connected successfully and if the |
| * server is at least PulseAudio 0.9.8. Please be aware of the |
| * slightly different semantics of the call depending whether |
| * PA_STREAM_ADJUST_LATENCY is set or not. \since 0.9.8 */ |
| pa_operation *pa_stream_set_buffer_attr(pa_stream *s, const pa_buffer_attr *attr, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Change the stream sampling rate during playback. You need to pass |
| * PA_STREAM_VARIABLE_RATE in the flags parameter of |
| * pa_stream_connect_...() if you plan to use this function. Only valid |
| * after the stream has been connected successfully and if the server |
| * is at least PulseAudio 0.9.8. \since 0.9.8 */ |
| pa_operation *pa_stream_update_sample_rate(pa_stream *s, uint32_t rate, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Update the property list of the sink input/source output of this |
| * stream, adding new entries. Please note that it is highly |
| * recommended to set as much properties initially via |
| * pa_stream_new_with_proplist() as possible instead a posteriori with |
| * this function, since that information may then be used to route |
| * this stream to the right device. \since 0.9.11 */ |
| pa_operation *pa_stream_proplist_update(pa_stream *s, pa_update_mode_t mode, pa_proplist *p, pa_stream_success_cb_t cb, void *userdata); |
| |
| /** Update the property list of the sink input/source output of this |
| * stream, remove entries. \since 0.9.11 */ |
| pa_operation *pa_stream_proplist_remove(pa_stream *s, const char *const keys[], pa_stream_success_cb_t cb, void *userdata); |
| |
| /** For record streams connected to a monitor source: monitor only a |
| * very specific sink input of the sink. Thus function needs to be |
| * called before pa_stream_connect_record() is called. \since |
| * 0.9.11 */ |
| int pa_stream_set_monitor_stream(pa_stream *s, uint32_t sink_input_idx); |
| |
| /** Return the sink input index previously set with |
| * pa_stream_set_monitor_stream(). |
| * \since 0.9.11 */ |
| uint32_t pa_stream_get_monitor_stream(pa_stream *s); |
| |
| PA_C_DECL_END |
| |
| #endif |