mirrors/pulseaudio
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pulseaudio/pulseaudio.git synced 2025-11-06 13:29:56 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve the port available_group and type documentation

Browse source
This commit is contained in:
Tanu Kaskinen 2020-06-17 08:14:18 +03:00
parent 2c790e1937
commit 0ce3008605
4 changed files with 80 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

76
src/pulse/introspect.h
View file

@ -229,8 +229,31 @@ typedef struct pa_sink_port_info {
const char *description; /**< Description of this port */
uint32_t priority; /**< The higher this value is, the more useful this port is as a default. */
int available; /**< A flags (see #pa_port_available), indicating availability status of this port. \since 2.0 */
const char *available_group; /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
uint32_t type; /**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
const char *available_group; /**< An indentifier for the group of ports that share their availability status with
* each other. This is meant especially for handling cases where one 3.5 mm connector
* is used for headphones, headsets and microphones, and the hardware can only tell
* that something was plugged in but not what exactly. In this situation the ports for
* all those devices share their availability status, and PulseAudio can't tell which
* one is actually plugged in, and some application may ask the user what was plugged
* in. Such applications should get a list of all card ports and compare their
* `available_group` fields. Ports that have the same group are those that need
* input from the user to determine which device was plugged in. The application should
* then activate the user-chosen port.
*
* May be NULL, in which case the port is not part of any availability group (which is
* the same as having a group with only one member).
*
* The group identifier must be treated as an opaque identifier. The string may look
* like an ALSA control name, but applications must not assume any such relationship.
* The group naming scheme can change without a warning.
*
* Since one group can include both input and output ports, the grouping should be done
* using pa_card_port_info instead of pa_sink_port_info, but this field is duplicated
* also in pa_sink_port_info (and pa_source_port_info) in case someone finds that
* convenient.
*
* \since 14.0 */
uint32_t type; /**< Port type, see #pa_device_port_type. \since 14.0 */
} pa_sink_port_info;
/** Stores information about sinks. Please note that this structure
@ -311,8 +334,31 @@ typedef struct pa_source_port_info {
const char *description; /**< Description of this port */
uint32_t priority; /**< The higher this value is, the more useful this port is as a default. */
int available; /**< A flags (see #pa_port_available), indicating availability status of this port. \since 2.0 */
const char *available_group; /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
uint32_t type; /**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
const char *available_group; /**< An indentifier for the group of ports that share their availability status with
* each other. This is meant especially for handling cases where one 3.5 mm connector
* is used for headphones, headsets and microphones, and the hardware can only tell
* that something was plugged in but not what exactly. In this situation the ports for
* all those devices share their availability status, and PulseAudio can't tell which
* one is actually plugged in, and some application may ask the user what was plugged
* in. Such applications should get a list of all card ports and compare their
* `available_group` fields. Ports that have the same group are those that need
* input from the user to determine which device was plugged in. The application should
* then activate the user-chosen port.
*
* May be NULL, in which case the port is not part of any availability group (which is
* the same as having a group with only one member).
*
* The group identifier must be treated as an opaque identifier. The string may look
* like an ALSA control name, but applications must not assume any such relationship.
* The group naming scheme can change without a warning.
*
* Since one group can include both input and output ports, the grouping should be done
* using pa_card_port_info instead of pa_source_port_info, but this field is duplicated
* also in pa_source_port_info (and pa_sink_port_info) in case someone finds that
* convenient.
*
* \since 14.0 */
uint32_t type; /**< Port type, see #pa_device_port_type. \since 14.0 */
} pa_source_port_info;
/** Stores information about sources. Please note that this structure
@ -513,8 +559,26 @@ typedef struct pa_card_port_info {
pa_proplist *proplist; /**< Property list */
int64_t latency_offset; /**< Latency offset of the port that gets added to the sink/source latency when the port is active. \since 3.0 */
pa_card_profile_info2** profiles2; /**< Array of pointers to available profiles, or NULL. Array is terminated by an entry set to NULL. \since 5.0 */
const char *available_group; /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
uint32_t type; /**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
const char *available_group; /**< An indentifier for the group of ports that share their availability status with
* each other. This is meant especially for handling cases where one 3.5 mm connector
* is used for headphones, headsets and microphones, and the hardware can only tell
* that something was plugged in but not what exactly. In this situation the ports for
* all those devices share their availability status, and PulseAudio can't tell which
* one is actually plugged in, and some application may ask the user what was plugged
* in. Such applications should get a list of all card ports and compare their
* `available_group` fields. Ports that have the same group are those that need
* input from the user to determine which device was plugged in. The application should
* then activate the user-chosen port.
*
* May be NULL, in which case the port is not part of any availability group (which is
* the same as having a group with only one member).
*
* The group identifier must be treated as an opaque identifier. The string may look
* like an ALSA control name, but applications must not assume any such relationship.
* The group naming scheme can change without a warning.
*
* \since 14.0 */
uint32_t type; /**< Port type, see #pa_device_port_type. \since 14.0 */
} pa_card_port_info;
/** Stores information about cards. Please note that this structure