includes typo fixes, neatening, addition of more return info, and such.
*
* \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
* \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
- * \li pa_channel_map_init_auto() - Create a standard channel map for a specific number of channels
- * \li pa_channel_map_init_extend() - Similar to
- * pa_channel_map_init_auto() but synthesize a channel map if no
- * predefined one is known for the specified number of channels.
+ * \li pa_channel_map_init_auto() - Create a standard channel map for a specific
+ * number of channels.
+ * \li pa_channel_map_init_extend() - Similar to pa_channel_map_init_auto() but
+ * synthesize a channel map if no predefined
+ * one is known for the specified number of
+ * channels.
*
* \section conv_sec Convenience Functions
*
* mixing of streams */
typedef struct pa_channel_map {
uint8_t channels;
- /**< Number of channels */
+ /**< Number of channels mapped */
pa_channel_position_t map[PA_CHANNELS_MAX];
/**< Channel labels */
* it might become part of an ABI. */
#define PA_CHANNEL_MAP_SNPRINT_MAX 336
-/** Make a human readable string from the specified channel map */
+/** Make a human readable string from the specified channel map. Returns \a s. */
char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
/** Parse a channel position list or well-known mapping name into a
* that some implementations may block all other events
* when a deferred event is active.
* \li I/O events - Events that trigger on file descriptor activities.
- * \li Times events - Events that trigger after a fixed amount of time.
+ * \li Timer events - Events that trigger after a fixed amount of time.
*
* The abstraction is represented as a number of function pointers in the
* pa_mainloop_api structure.
pa_context_state_t pa_context_get_state(pa_context *c);
/** Connect the context to the specified server. If server is NULL,
-connect to the default server. This routine may but will not always
-return synchronously on error. Use pa_context_set_state_callback() to
-be notified when the connection is established. If flags doesn't have
-PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or
-accessible a new daemon is spawned. If api is non-NULL, the functions
-specified in the structure are used when forking a new child
-process. */
+ * connect to the default server. This routine may but will not always
+ * return synchronously on error. Use pa_context_set_state_callback() to
+ * be notified when the connection is established. If flags doesn't have
+ * PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or
+ * accessible a new daemon is spawned. If api is non-NULL, the functions
+ * specified in the structure are used when forking a new child
+ * process. Returns negative on certain errors such as invalid state
+ * or parameters. */
int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api);
/** Terminate the context connection immediately */
/** Return the protocol version of the library. */
uint32_t pa_context_get_protocol_version(pa_context *c);
-/** Return the protocol version of the connected server. */
+/** Return the protocol version of the connected server.
+ * Returns PA_INVALID_INDEX on error. */
uint32_t pa_context_get_server_protocol_version(pa_context *c);
/** Update the property list of the client, adding new entries. Please
- * note that it is highly recommended to set as much properties
+ * note that it is highly recommended to set as many properties
* initially via pa_context_new_with_proplist() as possible instead a
* posteriori with this function, since that information may then be
* used to route streams of the client to the right device. \since 0.9.11 */
/** Return the client index this context is
* identified in the server with. This is useful for usage with the
- * introspection functions, such as pa_context_get_client_info(). \since 0.9.11 */
+ * introspection functions, such as pa_context_get_client_info().
+ * Returns PA_INVALID_INDEX on error. \since 0.9.11 */
uint32_t pa_context_get_index(pa_context *s);
/** Create a new timer event source for the specified time (wrapper
* of this size. It is not recommended writing smaller blocks than
* this (unless required due to latency demands) because this
* increases CPU usage. If ss is NULL you will be returned the
- * byte-exact tile size. If you pass a valid ss, then the tile size
+ * byte-exact tile size. if ss is invalid, (size_t) -1 will be
+ * returned. If you pass a valid ss, then the tile size
* will be rounded down to multiple of the frame size. This is
* supposed to be used in a construct such as
* pa_context_get_tile_size(pa_stream_get_context(s),
/**< The operation has completed */
PA_OPERATION_CANCELLED
/**< The operation has been cancelled. Operations may get cancelled by the
- * application, or as a result of the context getting disconneted while the
+ * application, or as a result of the context getting disconnected while the
* operation is pending. */
} pa_operation_state_t;
PA_CONTEXT_NOAUTOSPAWN = 0x0001U,
/**< Disabled autospawning of the PulseAudio daemon if required */
PA_CONTEXT_NOFAIL = 0x0002U
- /**< Don't fail if the daemon is not available when pa_context_connect() is called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon to appear. \since 0.9.15 */
+ /**< Don't fail if the daemon is not available when pa_context_connect() is
+ * called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon
+ * to appear. \since 0.9.15 */
} pa_context_flags_t;
/** \cond fulldocs */
PA_STREAM_FIX_CHANNELS = 0x0100,
/**< 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
+ * sample spec and the passed channel map contain. 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.
*
PA_STREAM_START_MUTED = 0x1000U,
/**< Create in muted state. If neither PA_STREAM_START_UNMUTED nor
- * PA_STREAM_START_MUTED it is left to the server to decide
+ * PA_STREAM_START_MUTED are set, it is left to the server to decide
* whether to create the stream in muted or in unmuted
* state. \since 0.9.11 */
PA_STREAM_START_UNMUTED = 0x10000U,
/**< Create in unmuted state. If neither PA_STREAM_START_UNMUTED
- * nor PA_STREAM_START_MUTED it is left to the server to decide
+ * nor PA_STREAM_START_MUTED are set it is left to the server to decide
* whether to create the stream in muted or in unmuted
* state. \since 0.9.15 */
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
+ * of date at the time you want to use it. Consider using
* PA_SEEK_RELATIVE instead. */
int read_index_corrupt;
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
+ * of date at the time you want to use it. Consider using
* PA_SEEK_RELATIVE_ON_READ instead. */
pa_usec_t configured_sink_usec;
/** Seek type for pa_stream_write(). */
typedef enum pa_seek_mode {
PA_SEEK_RELATIVE = 0,
- /**< Seek relatively to the write index */
+ /**< Seek relative to the write index. */
PA_SEEK_ABSOLUTE = 1,
- /**< Seek relatively to the start of the buffer queue */
+ /**< Seek relative to the start of the buffer queue. */
PA_SEEK_RELATIVE_ON_READ = 2,
- /**< Seek relatively to the read index. */
+ /**< Seek relative to the read index. */
PA_SEEK_RELATIVE_END = 3
- /**< Seek relatively to the current end of the buffer queue. */
+ /**< Seek relative to the current end of the buffer queue. */
} pa_seek_mode_t;
/** \cond fulldocs */
/** Returns a printable string representing the given encoding type. \since 1.0 */
const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST;
-/** Converts a string of the form returned by \a pa_encoding_to_string() back to a \a pa_encoding_t. \since 1.0 */
+/** Converts a string of the form returned by \a pa_encoding_to_string() back to
+ * a \a pa_encoding_t. \since 1.0 */
pa_encoding_t pa_encoding_from_string(const char *encoding);
/** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */
/**< Additional encoding-specific properties such as sample rate, bitrate, etc. */
} pa_format_info;
-/** Allocates a new \a pa_format_info structure. Clients must initialise at least the encoding field themselves. \since 1.0 */
+/** Allocates a new \a pa_format_info structure. Clients must initialise at
+ * least the encoding field themselves. Free with pa_format_info_free. \since 1.0 */
pa_format_info* pa_format_info_new(void);
/** Returns a new \a pa_format_info struct and representing the same format as \a src. \since 1.0 */
/** Returns non-zero when the format info structure is valid. \since 1.0 */
int pa_format_info_valid(const pa_format_info *f);
-/** Returns non-zero when the format info structure represents a PCM (i.e.\ uncompressed data) format. \since 1.0 */
+/** Returns non-zero when the format info structure represents a PCM
+ * (i.e.\ uncompressed data) format. \since 1.0 */
int pa_format_info_is_pcm(const pa_format_info *f);
/** Returns non-zero if the format represented by \a first is a subset of
* it might become part of an ABI. \since 1.0 */
#define PA_FORMAT_INFO_SNPRINT_MAX 256
-/** Return a human-readable string representing the given format. \since 1.0 */
+/** Make a human-readable string representing the given format. Returns \a s. \since 1.0 */
char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f);
/** Parse a human-readable string of the form generated by
* Main loop abstraction layer. Both the PulseAudio core and the
* PulseAudio client library use a main loop abstraction layer. Due to
* this it is possible to embed PulseAudio into other
- * applications easily. Two main loop implementations are
+ * applications easily. Three main loop implementations are
* currently available:
- * \li A minimal implementation based on the C library's poll() function (See \ref mainloop.h)
- * \li A wrapper around the GLIB main loop. Use this to embed PulseAudio into your GLIB/GTK+/GNOME programs (See \ref glib-mainloop.h)
+ * \li A minimal implementation based on the C library's poll() function
+ * (See \ref mainloop.h).
+ * \li A special version of the previous implementation where all of
+ * PulseAudio's internal handling runs in a separate thread
+ * (See \ref thread-mainloop.h).
+ * \li A wrapper around the GLIB main loop. Use this to embed PulseAudio into
+ * your GLIB/GTK+/GNOME programs (See \ref glib-mainloop.h).
*
- * The structure pa_mainloop_api is used as vtable for the main loop abstraction.
+ * The structure pa_mainloop_api is used as a vtable for the main loop abstraction.
*
- * This mainloop abstraction layer has no direct support for UNIX signals. Generic, mainloop implementation agnostic support is available through \ref mainloop-signal.h.
+ * This mainloop abstraction layer has no direct support for UNIX signals.
+ * Generic, mainloop implementation agnostic support is available through
+ * \ref mainloop-signal.h.
* */
PA_C_DECL_BEGIN
/** An opaque main loop object */
typedef struct pa_mainloop pa_mainloop;
-/** Allocate a new main loop object */
+/** Allocate a new main loop object. Free with pa_mainloop_free. */
pa_mainloop *pa_mainloop_new(void);
/** Free a main loop object */
to. On success returns the number of sources dispatched in this iteration. */
int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval);
-/** Run unlimited iterations of the main loop object until the main loop's quit() routine is called. */
+/** Run unlimited iterations of the main loop object until the main loop's
+quit() routine is called. Returns a negative value on error. Optionally return
+the return value as specified with the main loop's quit() routine in the integer
+variable retval points to. */
int pa_mainloop_run(pa_mainloop *m, int *retval);
/** Return the abstract main loop abstraction layer vtable for this
* as keys and arbitrary data as values. \since 0.9.11 */
typedef struct pa_proplist pa_proplist;
-/** Allocate a property list. \since 0.9.11 */
+/** Allocate a property list. Free with pa_proplist_free. \since 0.9.11 */
pa_proplist* pa_proplist_new(void);
/** Free the property list. \since 0.9.11 */
/** Append a new string entry to the property list, possibly
* overwriting an already existing entry with the same key. An
* internal copy of the data passed is made. Will accept only valid
- * UTF-8. \since 0.9.11 */
+ * UTF-8. Returns zero on success. \since 0.9.11 */
int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
/** Append a new string entry to the property list, possibly
* internal copy of the data passed is made. Will accept only valid
* UTF-8. The string passed in must contain a '='. Left hand side of
* the '=' is used as key name, the right hand side as string
- * data. \since 0.9.16 */
+ * data. Returns zero on success. \since 0.9.16 */
int pa_proplist_setp(pa_proplist *p, const char *pair);
/** Append a new string entry to the property list, possibly
* overwriting an already existing entry with the same key. An
* internal copy of the data passed is made. Will accept only valid
* UTF-8. The data can be passed as printf()-style format string with
- * arguments. \since 0.9.11 */
+ * arguments. Returns zero on success. \since 0.9.11 */
int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...) PA_GCC_PRINTF_ATTR(3,4);
/** Append a new arbitrary data entry to the property list, possibly
* overwriting an already existing entry with the same key. An
- * internal copy of the data passed is made. \since 0.9.11 */
+ * internal copy of the data passed is made.
+ * Returns zero on success. \since 0.9.11 */
int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
/** Return a string entry for the specified key. Will return NULL if
/** Store the value for the specified key in \a data. Will store a
* NUL-terminated string for string entries. The \a data pointer returned will
* point to an internally allocated buffer. The caller should make a
- * copy of the data before the property list is accessed again. \since
- * 0.9.11 */
+ * copy of the data before the property list is accessed again.
+ * Returns zero on success, negative on error. \since 0.9.11 */
int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
/** Update mode enum for pa_proplist_update(). \since 0.9.11 */
void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, const pa_proplist *other);
/** Removes a single entry from the property list, identified be the
- * specified key name. \since 0.9.11 */
+ * specified key name. Returns zero on success, negative on error.
+ * \since 0.9.11 */
int pa_proplist_unset(pa_proplist *p, const char *key);
/** Similar to pa_proplist_unset() but takes an array of keys to
pa_proplist *pa_proplist_from_string(const char *str);
/** Returns 1 if an entry for the specified key exists in the
- * property list. \since 0.9.11 */
+ * property list. Returns negative on error. \since 0.9.11 */
int pa_proplist_contains(pa_proplist *p, const char *key);
/** Remove all entries from the property list object. \since 0.9.11 */
* integer value or a NULL pointer. On success, zero or a positive integer
* value or a valid pointer is returned.
*
- * Functions of the \ref simple generally return -1 or NULL on failure and
+ * Functions of the \ref simple API generally return -1 or NULL on failure and
* can optionally store an error code (see ::pa_error_code) using a pointer
* argument.
*
- * Functions of the \ref async return an negative error code or NULL on
+ * Functions of the \ref async API return an negative error code or NULL on
* failure (see ::pa_error_code). In the later case, pa_context_errno()
* can be used to obtain the error code of the last failed operation.
*
/** Type for usec specifications (unsigned). Always 64 bit. */
typedef uint64_t pa_usec_t;
-/** Return the amount of bytes playback of a second of audio with the specified sample type takes */
+/** Return the amount of bytes that constitute playback of one second of
+ * audio, with the specified sample spec. */
size_t pa_bytes_per_second(const pa_sample_spec *spec) PA_GCC_PURE;
/** Return the size of a frame with the specific sample type */
* full sample spec. \since 0.9.15 */
size_t pa_sample_size_of_format(pa_sample_format_t f) PA_GCC_PURE;
-/** Calculate the time the specified bytes take to play with the
- * specified sample type. The return value will always be rounded
- * down for non-integral return values. */
+/** Calculate the time it would take to play a buffer of the specified
+ * size with the specified sample type. The return value will always
+ * be rounded down for non-integral return values. */
pa_usec_t pa_bytes_to_usec(uint64_t length, const pa_sample_spec *spec) PA_GCC_PURE;
-/** Calculates the number of bytes that are required for the specified
- * time. The return value will always be rounded down for non-integral
+/** Calculates the size of a buffer required, for playback duration
+ * of the time specified, with the specified sample type. The
+ * return value will always be rounded down for non-integral
* return values. \since 0.9 */
size_t pa_usec_to_bytes(pa_usec_t t, const pa_sample_spec *spec) PA_GCC_PURE;
* it might become part of an ABI. */
#define PA_SAMPLE_SPEC_SNPRINT_MAX 32
-/** Pretty print a sample type specification to a string */
+/** Pretty print a sample type specification to a string. Returns \a s. */
char* pa_sample_spec_snprint(char *s, size_t l, const pa_sample_spec *spec);
/** Maximum required string length for pa_bytes_snprint(). Please note
* ABI. \since 0.9.16 */
#define PA_BYTES_SNPRINT_MAX 11
-/** Pretty print a byte size value (i.e.\ "2.5 MiB") */
+/** Pretty print a byte size value (i.e.\ "2.5 MiB"). Returns \a s. */
char* pa_bytes_snprint(char *s, size_t l, unsigned v);
-/** Return 1 when the specified format is little endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is little endian, 0 when
+ * big endian. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
int pa_sample_format_is_le(pa_sample_format_t f) PA_GCC_PURE;
-/** Return 1 when the specified format is big endian, return -1 when
- * endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is big endian, 0 when
+ * little endian. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
int pa_sample_format_is_be(pa_sample_format_t f) PA_GCC_PURE;
#ifdef WORDS_BIGENDIAN
#define pa_sample_format_is_ne(f) pa_sample_format_is_be(f)
#define pa_sample_format_is_re(f) pa_sample_format_is_le(f)
#else
-/** Return 1 when the specified format is native endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is native endian, 0 when
+ * not. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
#define pa_sample_format_is_ne(f) pa_sample_format_is_le(f)
-/** Return 1 when the specified format is reverse endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is reverse endian, 0 when
+ * native. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
#define pa_sample_format_is_re(f) pa_sample_format_is_be(f)
#endif
* PA_INVALID_INDEX on failure. \since 0.9.11 */
typedef void (*pa_context_play_sample_cb_t)(pa_context *c, uint32_t idx, void *userdata);
-/** Make this stream a sample upload stream */
+/** Make this stream a sample upload stream. Returns zero on success. */
int pa_stream_connect_upload(pa_stream *s, size_t length);
/** Finish the sample upload, the stream name will become the sample
* name. You cancel a sample upload by issuing
- * pa_stream_disconnect() */
+ * pa_stream_disconnect(). Returns zero on success. */
int pa_stream_finish_upload(pa_stream *s);
-/** Remove a sample from the sample cache. Returns an operation object which may be used to cancel the operation while it is running */
+/** Remove a sample from the sample cache. Returns an operation object which
+ * may be used to cancel the operation while it is running. */
pa_operation* pa_context_remove_sample(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
/** Play a sample from the sample cache to the specified device. If
pa_context *c /**< Context */,
const char *name /**< Name of the sample to play */,
const char *dev /**< Sink to play this sample on */,
- pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side which is a good idea. */ ,
+ pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ ,
pa_context_success_cb_t cb /**< Call this function after successfully starting playback, or NULL */,
void *userdata /**< Userdata to pass to the callback */);
pa_context *c /**< Context */,
const char *name /**< Name of the sample to play */,
const char *dev /**< Sink to play this sample on */,
- pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side which is a good idea. */ ,
+ pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ ,
pa_proplist *proplist /**< Property list for this sound. The property list of the cached entry will be merged into this property list */,
pa_context_play_sample_cb_t cb /**< Call this function after successfully starting playback, or NULL */,
void *userdata /**< Userdata to pass to the callback */);
/** Close and free the connection to the server. The connection object becomes invalid when this is called. */
void pa_simple_free(pa_simple *s);
-/** Write some data to the server. */
+/** Write some data to the server. Returns zero on success, negative on error. */
int pa_simple_write(pa_simple *s, const void *data, size_t bytes, int *error);
-/** Wait until all data already written is played by the daemon. */
+/** Wait until all data already written is played by the daemon.
+ * Returns zero on success, negative on error. */
int pa_simple_drain(pa_simple *s, int *error);
/** Read some data from the server. This function blocks until \a bytes amount
* of data has been received from the server, or until an error occurs.
- * Returns a negative value on failure. */
+ * Returns zero on success, negative on failure. */
int pa_simple_read(
pa_simple *s, /**< The connection object. */
void *data, /**< A pointer to a buffer. */
/** Return the playback or record latency. */
pa_usec_t pa_simple_get_latency(pa_simple *s, int *error);
-/** Flush the playback or record buffer. This discards any audio in the buffer. */
+/** Flush the playback or record buffer. This discards any audio in the buffer.
+ * Returns zero on success, negative on error. */
int pa_simple_flush(pa_simple *s, int *error);
PA_C_DECL_END
* 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
+ * \li Asynchronous - The application registers 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.
* 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 - 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
* 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
+ * To make sure that a particular stream doesn't stop playing 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.
+ * pass a pa_buffer_attr with prebuf set to 0 when connecting.
*
* \section disc_sec Disconnecting
*
/** 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(). */
+ * or pa_context_get_source_output_info(). This returns PA_INVALID_INDEX
+ * on failure. */
uint32_t pa_stream_get_index(pa_stream *s);
/** Return the index of the sink or source this stream is connected to
*
* 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 */
+ * 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 */
uint32_t pa_stream_get_device_index(pa_stream *s);
/** Return the name of the sink or source this stream is connected to
*
* 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 */
+ * about this. This function will fail 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
*
* Since 5.0, it's possible to specify a single-channel volume even if the
* stream has multiple channels. In that case the same volume is applied to all
- * channels. */
+ * channels.
+ *
+ * Returns zero on success. */
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_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. */
+/** Connect the stream to a source. Returns zero on success. */
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. */
+/** Disconnect a stream from a source/sink. Returns zero on success. */
int pa_stream_disconnect(pa_stream *s);
/** Prepare writing data to the server (for playback streams). This
* 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. \since 0.9.16 */
+ * \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 */
int pa_stream_begin_write(
pa_stream *p,
void **data,
* 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 */
+ * explicit freeing of the memory area is not necessary.
+ * Returns zero on success. \since 0.9.16 */
int pa_stream_cancel_write(
pa_stream *p);
*
* The client may freely seek around in the output buffer. For
* most applications it is typical to pass 0 and PA_SEEK_RELATIVE
- * as values for the arguments \a offset and \a seek. After the write
- * call succeeded the write index will be at the position after where
- * this chunk of data has been written to.
+ * as values for the arguments \a offset and \a seek respectively.
+ * After a successful write call 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
* 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
+ * necessary. It is OK to write to 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.*/
+ * area.
+ *
+ * Returns zero on success. */
int pa_stream_write(
pa_stream *p /**< The stream to use */,
const void *data /**< The data to write */,
* 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. */
+ * a hole.
+ *
+ * Returns zero on success, negative on error. */
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(). */
+ * calling pa_stream_peek(). Returns zero on success. */
int pa_stream_drop(pa_stream *p);
/** Return the number of bytes requested by the server that have not yet
* buffer_attr.maxlength bytes. This is usually not desirable, though, as
* it would increase stream latency to be higher than requested
* (buffer_attr.tlength).
+ *
+ * (size_t) -1 is returned on error.
*/
size_t pa_stream_writable_size(pa_stream *p);
-/** Return the number of bytes that may be read using pa_stream_peek(). */
+/** Return the number of bytes that may be read using pa_stream_peek().
+ *
+ * (size_t) -1 is returned on error. */
size_t pa_stream_readable_size(pa_stream *p);
/** Drain a playback stream. Use this for notification when the
/** 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
+/** 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
*
* If no timing information has been
* received yet this call will return -PA_ERR_NODATA. For more details
- * see pa_stream_get_timing_info(). */
+ * see pa_stream_get_timing_info().
+ *
+ * Returns zero on success, negative on error. */
int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
/** Determine the total stream latency. This function is based on
/** 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 he
- * wants to modify it. An in-place update to this data structure may
- * be requested using pa_stream_update_timing_info().
+ * 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 fail with
- * -PA_ERR_NODATA.
+ * 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
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
+ * 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
/** 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. \since
- * 0.9.11 */
+ * called before pa_stream_connect_record() is called.
+ * Returns zero on success, negative on error. \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 */
+ * pa_stream_set_monitor_stream(). Returns PA_INVALID_INDEX
+ * on failure. \since 0.9.11 */
uint32_t pa_stream_get_monitor_stream(pa_stream *s);
PA_C_DECL_END
*
* The added feature in the threaded main loop is that it spawns a new thread
* that runs the real main loop. This allows a synchronous application to use
- * the asynchronous API without risking to stall the PulseAudio library.
+ * the asynchronous API without risking stalling the PulseAudio library.
*
* \section creat_sec Creation
*
/** Allocate a new threaded main loop object. You have to call
* pa_threaded_mainloop_start() before the event loop thread starts
- * running. */
+ * running. Free with pa_threaded_mainloop_free. */
pa_threaded_mainloop *pa_threaded_mainloop_new(void);
/** Free a threaded main loop object. If the event loop thread is
* first. */
void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
-/** Start the event loop thread. */
+/** Start the event loop thread. Returns zero on success, negative on error. */
int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
/** Terminate the event loop thread cleanly. Make sure to unlock the
*
* This library 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
+ * 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
pa_volume_t values[PA_CHANNELS_MAX]; /**< Per-channel volume */
} pa_cvolume;
-/** Return non-zero when *a == *b */
+/** Return non-zero when *a == *b, checking that both a and b
+ * have the same number of channels and that the volumes of
+ * channels in a equal those in b. */
int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE;
/** Initialize the specified volume and return a pointer to
* might become part of an ABI.*/
#define PA_CVOLUME_SNPRINT_MAX 320
-/** Pretty print a volume structure */
+/** Pretty print a volume structure. Returns \a s. */
char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
/** Maximum length of the strings returned by
* might become part of an ABI. \since 0.9.13 */
#define PA_SW_CVOLUME_SNPRINT_DB_MAX 448
-/** Pretty print a volume structure but show dB values. \since 0.9.13 */
+/** Pretty print a volume structure, showing dB values. Returns \a s. \since 0.9.13 */
char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
/** Maximum length of the strings returned by pa_cvolume_snprint_verbose().
/** Pretty print a volume structure in a verbose way. The volume for each
* channel is printed in several formats: the raw pa_volume_t value,
* percentage, and if print_dB is non-zero, also the dB value. If map is not
- * NULL, the channel names will be printed. \since 5.0 */
+ * NULL, the channel names will be printed. Returns \a s. \since 5.0 */
char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB);
/** Maximum length of the strings returned by
* might become part of an ABI. \since 0.9.15 */
#define PA_VOLUME_SNPRINT_MAX 10
-/** Pretty print a volume \since 0.9.15 */
+/** Pretty print a volume. Returns \a s. \since 0.9.15 */
char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
/** Maximum length of the strings returned by
* might become part of an ABI. \since 0.9.15 */
#define PA_SW_VOLUME_SNPRINT_DB_MAX 11
-/** Pretty print a volume but show dB values. \since 0.9.15 */
+/** Pretty print a volume but show dB values. Returns \a s. \since 0.9.15 */
char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
/** Maximum length of the strings returned by pa_volume_snprint_verbose().
/** Pretty print a volume in a verbose way. The volume is printed in several
* formats: the raw pa_volume_t value, percentage, and if print_dB is non-zero,
- * also the dB value. \since 5.0 */
+ * also the dB value. Returns \a s. \since 5.0 */
char *pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB);
/** Return the average volume of all channels */
/** Multiply two per-channel volumes and return the result in
* *dest. This is only valid for software volumes! a, b and dest may
- * point to the same structure. */
+ * point to the same structure. Returns dest, or NULL on error. */
pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
/** Multiply a per-channel volume with a scalar volume and return the
* result in *dest. This is only valid for software volumes! a
- * and dest may point to the same structure. \since
- * 0.9.16 */
+ * and dest may point to the same structure. Returns dest, or NULL on error.
+ * \since 0.9.16 */
pa_cvolume *pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
/** Divide two volume specifications, return the result. This uses
/** Divide two per-channel volumes and return the result in
* *dest. This is only valid for software volumes! a, b
- * and dest may point to the same structure. \since 0.9.13 */
+ * and dest may point to the same structure. Returns dest,
+ * or NULL on error. \since 0.9.13 */
pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
/** Divide a per-channel volume by a scalar volume and return the
* result in *dest. This is only valid for software volumes! a
- * and dest may point to the same structure. \since
- * 0.9.16 */
+ * and dest may point to the same structure. Returns dest,
+ * or NULL on error. \since 0.9.16 */
pa_cvolume *pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
/** Convert a decibel value to a volume (amplitude, not power). This is only valid for software volumes! */
/** Convert a volume to a decibel value (amplitude, not power). This is only valid for software volumes! */
double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST;
-/** Convert a linear factor to a volume. 0.0 and less is muted while
- * 1.0 is PA_VOLUME_NORM. This is only valid for software volumes! */
+/** Convert a linear factor to a volume. 0.0 and less is muted while
+ * 1.0 is PA_VOLUME_NORM. This is only valid for software volumes! */
pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST;
/** Convert a volume to a linear factor. This is only valid for software volumes! */
#define PA_DECIBEL_MININFTY ((double) -200.0)
#endif
-/** Remap a volume from one channel mapping to a different channel mapping. \since 0.9.12 */
+/** Remap a volume from one channel mapping to a different channel mapping.
+ * Returns \a v. \since 0.9.12 */
pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to);
/** Return non-zero if the specified volume is compatible with the
* requested balance value (e.g. when the input volume was zero anyway for
* all channels). If no balance value is applicable to
* this channel map the volume will not be modified. See
- * pa_channel_map_can_balance(). \since 0.9.15 */
+ * pa_channel_map_can_balance(). Will return NULL on error. \since 0.9.15 */
pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
/** Calculate a 'fade' value (i.e.\ 'balance' between front and rear)
* return the requested fade value (e.g. when the input volume was
* zero anyway for all channels). If no fade value is applicable to
* this channel map the volume will not be modified. See
- * pa_channel_map_can_fade(). \since 0.9.15 */
+ * pa_channel_map_can_fade(). Will return NULL on error. \since 0.9.15 */
pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade);
/** Calculate a 'lfe balance' value for the specified volume with
* return the requested value (e.g. when the input volume was
* zero anyway for all channels). If no lfe balance value is applicable to
* this channel map the volume will not be modified. See
- * pa_channel_map_can_lfe_balance(). \since 8.0 */
+ * pa_channel_map_can_lfe_balance(). Will return NULL on error. \since 8.0 */
pa_cvolume* pa_cvolume_set_lfe_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
/** Scale the passed pa_cvolume structure so that the maximum volume
* of all channels equals max. The proportions between the channel
- * volumes are kept. \since 0.9.15 */
+ * volumes are kept. Returns \a v, or NULL on error. \since 0.9.15 */
pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
/** Scale the passed pa_cvolume structure so that the maximum volume
* of all channels selected via cm/mask equals max. This also modifies
* the volume of those channels that are unmasked. The proportions
- * between the channel volumes are kept. \since 0.9.16 */
+ * between the channel volumes are kept. If cm is NULL this call is
+ * identical to pa_cvolume_scale(). Returns \a v, or NULL on error.
+ * \since 0.9.16 */
pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask);
/** Set the passed volume to all channels at the specified channel
* position. Will return the updated volume struct, or NULL if there
* is no channel at the position specified. You can check if a channel
* map includes a specific position by calling
- * pa_channel_map_has_position(). \since 0.9.16 */
+ * pa_channel_map_has_position(). Returns \a cv, or NULL on error.
+ * \since 0.9.16 */
pa_cvolume* pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v);
/** Get the maximum volume of all channels at the specified channel
/** This goes through all channels in a and b and sets the
* corresponding channel in dest to the greater volume of both. a, b
- * and dest may point to the same structure. \since 0.9.16 */
+ * and dest may point to the same structure. Returns \a dest, or NULL
+ * on error. \since 0.9.16 */
pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
/** Increase the volume passed in by 'inc', but not exceeding 'limit'.
- * The proportions between the channels are kept. \since 0.9.19 */
+ * The proportions between the channels are kept.
+ * Returns \a v, or NULL on error. \since 0.9.19 */
pa_cvolume* pa_cvolume_inc_clamp(pa_cvolume *v, pa_volume_t inc, pa_volume_t limit);
/** Increase the volume passed in by 'inc'. The proportions between
- * the channels are kept. \since 0.9.16 */
+ * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */
pa_cvolume* pa_cvolume_inc(pa_cvolume *v, pa_volume_t inc);
/** Decrease the volume passed in by 'dec'. The proportions between
- * the channels are kept. \since 0.9.16 */
+ * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */
pa_cvolume* pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec);
PA_C_DECL_END
projects / platform / upstream / pulseaudio.git / commitdiff