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
A generic notification callback
A generic request callback
A generic callback for operation completion
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. \a *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 \a *nbytes value is invalid. * Accessing the memory returned after the following pa_stream_write() * or pa_stream_cancel_write() is invalid. * * On invocation only \a *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 \a data set to an address * within this memory area and an \a 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 * \a data pointer and \a nbytes values. * * On success, will return zero and a valid (non-NULL) pointer. If the * return value is non-zero, or the pointer is NULL, this indicates an * error. Callers should also pay careful attention to the returned * length, which may not be the same as that passed in, as mentioned above. * * \since 0.9.16
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. * Returns zero on success. \since 0.9.16
< Synchronize this stream with the specified one, or NULL for a standalone stream
< Additional flags, or 0 for default
Pause (or resume) playback of this stream temporarily. Available * on both playback and recording streams. If \a b is 1 the stream is * paused. If \a 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 a flag when connecting * the stream, it will be created in corked state.
Disconnect a stream from a source/sink. Returns zero on success.
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.
Remove the current fragment on record streams. It is invalid to do this without first * calling pa_stream_peek(). Returns zero on success.
Flush the playback or record buffer of this stream. This discards any audio data * in the buffer. Most of the time you're better off using the parameter * \a seek of pa_stream_write() instead of this function.
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 * actual per-stream server-side buffer metrics, regardless whether * PA_STREAM_ADJUST_LATENCY is set or not. \since 0.9.0
Return a pointer to the stream's channel map.
Return the context this stream is attached to.
Return the index of the sink or source this stream is connected to * in the server. This is useful with the introspection * functions such as pa_context_get_sink_info_by_index() or * 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_INVALID_INDEX on failure, * including the being server older than 0.9.8. \since 0.9.8
Return the name of the sink or source this stream is connected to * in the server. This is useful with the introspection * functions such as pa_context_get_sink_info_by_name() * or 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 fail when the server is older than * 0.9.8. \since 0.9.8
Return a pointer to the stream's format. \since 1.0
Return the sink input resp.\ source output index this stream is * identified in the server with. This is useful with the * introspection functions such as pa_context_get_sink_input_info() * or pa_context_get_source_output_info(). This returns PA_INVALID_INDEX * on failure.
Determine the total stream latency. This function is based on * pa_stream_get_time(). The returned time is in the sound card clock * domain, which usually runs at a slightly different rate than the * system clock. * * The latency is stored in \a *r_usec. 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 \a *negative is set to 1. * * If no timing information has been received yet, this call will * return -PA_ERR_NODATA. On success, it will return 0. * * For more details see pa_stream_get_timing_info() and * pa_stream_get_time().
Return the sink input index previously set with * pa_stream_set_monitor_stream(). Returns PA_INVALID_INDEX * on failure. \since 0.9.11
Return a pointer to the stream's sample specification.
Return the current state of the stream.
Return the current playback/recording time. This is based on the * data in the timing info structure returned by * pa_stream_get_timing_info(). The returned time is in the sound card * clock domain, which usually runs at a slightly different rate than * the system clock. * * 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 (the returned value is always greater * or equal to the value returned by the last call). This behaviour * can be disabled by using PA_STREAM_NOT_MONOTONIC. This may be * desirable to better deal 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 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(). * * Returns zero on success, negative on error.
Return the latest raw timing data structure. The returned pointer * refers to an internal read-only instance of the timing * structure. The user should make a copy of this structure if * wanting 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 return NULL. * * 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.
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
Return 1 if the this stream has been corked. This will return 0 if * not, and a negative value on error. \since 0.9.11
Return 1 if the sink or source this stream is connected to has * been suspended. This will return 0 if not, and a negative value on * error. This function will return with -PA_ERR_NOTSUPPORTED when the * server is older than 0.9.8. \since 0.9.8
< The desired channel map, or NULL for default
< The initial property list
< The initial property list
< The length of the data read in bytes
Reenable prebuffering if specified in the pa_buffer_attr * structure. Available for playback streams only.
Update the property list of the sink input/source output of this * stream, remove entries. \since 0.9.11
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 many properties initially via * pa_stream_new_with_proplist() as possible instead a posteriori with * this function, since that information may be used to route * this stream to the right device. \since 0.9.11
Return the number of bytes that may be read using pa_stream_peek(). * * (size_t) -1 is returned on error.
Increase the reference counter by one.
Change the buffer metrics of the stream during playback. The * server might have chosen different buffer metrics than * 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
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
Set the callback function that is called whenever a meta/policy * control event is received. \since 0.9.15
Set the callback function that is called whenever a latency * information update happens. Useful on PA_STREAM_AUTO_TIMING_UPDATE * streams only.
For record streams connected to a monitor source: monitor only a * very specific sink input of the sink. This function needs to be * called before pa_stream_connect_record() is called. * Returns zero on success, negative on error. \since 0.9.11
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
Rename the stream.
Set the callback function that is called when a buffer overflow happens. (Only for playback streams)
Set the callback function that is called when new data is available from the stream.
Set the callback function that is called when 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
Set the callback function that is called whenever the state of the stream changes.
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
Set the callback function that is called when a buffer underflow happens. (Only for playback streams)
Set the callback function that is called when new data may be * written to the stream.
Request immediate start of playback on this stream. This disables * prebuffering temporarily if specified in the pa_buffer_attr structure. * Available for playback streams only.
Decrease the reference counter by one.
Change the stream sampling rate during playback. You need to pass * PA_STREAM_VARIABLE_RATE in the flags parameter of * pa_stream_connect_playback() 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
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.
Return the number of bytes requested by the server that have not yet been written.
< Seek mode, must be PA_SEEK_RELATIVE for upload streams
< Seek mode, must be PA_SEEK_RELATIVE for upload streams
An opaque stream for playback or recording