* 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.
+ * -PA_ERR_NODATA set.
*
* Since updating the timing info structure usually requires a full
* network round trip and some applications monitor the timing very
*
* 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
+ * 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);
*
* 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
+ * 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 a negative value on
- * error. This function will return with PA_ERR_NOTSUPPORTED when the
+ * 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);
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).
- * \a data will point to the actual data and \a 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. */
+ * If there is data at the current read index, \a data will point to
+ * the actual data and \a nbytes will contain the size of the data in
+ * bytes (which can be less or more than a complete fragment).
+ *
+ * If there is no data at the current read index, it means that either
+ * the buffer is empty or it contains a hole (that is, the write index
+ * is ahead of the read index but there's no data where the read index
+ * points at). If the buffer is empty, \a data will be NULL and
+ * \a nbytes will be 0. If there is a hole, \a data will be NULL and
+ * \a nbytes will contain the length of the hole.
+ *
+ * Use pa_stream_drop() to actually remove the data from the buffer
+ * and move the read index forward. pa_stream_drop() should not be
+ * called if the buffer is empty, but it should be called if there is
+ * a hole. */
int pa_stream_peek(
pa_stream *p /**< The stream to use */,
const void **data /**< Pointer to pointer that will point to data */,
* pa_stream_update_timing_info().
*
* If no timing information has been
- * received yet this call will return PA_ERR_NODATA. For more details
+ * 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
+/** Determine 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 \a *negative is set to 1.
+ * 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. For more details see
- * pa_stream_get_timing_info() and pa_stream_get_time(). */
+ * return -PA_ERR_NODATA. On success, it will return 0.
+ *
+ * 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
* 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.
+ * -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