mirrors/pulseaudio
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pulseaudio/pulseaudio.git synced 2025-10-28 05:40:21 -04: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

6
PROTOCOL
View file

@ -429,7 +429,11 @@ Added two values to the pa_encoding_t enum:
## v34, implemented by >= 14.0
Added available_group and type fields to the device port info.
New fields in the port introspection data (duplicated for all port types:
sink, source and card ports):
string available_group
uint32 type
#### If you just changed the protocol, read this
## module-tunnel depends on the sink/source/sink-input/source-input protocol

2
src/modules/alsa/mixer/paths/analog-output.conf.common
View file

@ -53,6 +53,8 @@
; [General]
; type = ... # The device type. It's highly recommended to set a type for every path.
; # See parse_type() in alsa-mixer.c for supported values.
; priority = ... # Priority for this path
; description-key = ... # The path description is looked up from a table in path_verify() in
; # src/modules/alsa/alsa-mixer.c. By default the path name (i.e. the file name

4
src/pulse/def.h
View file

@ -1070,7 +1070,9 @@ typedef enum pa_port_available {
/** \endcond */
#endif
/** Port type. \since 14.0 */
/** Port type. New types can be added in the future, so applications should
* gracefully handle situations where a type identifier doesn't match any item
* in this enumeration. \since 14.0 */
typedef enum pa_device_port_type {
PA_DEVICE_PORT_TYPE_UNKNOWN = 0,
PA_DEVICE_PORT_TYPE_AUX = 1,

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