diff options
-rw-r--r-- | PROTOCOL | 6 | ||||
-rw-r--r-- | src/modules/alsa/mixer/paths/analog-output.conf.common | 2 | ||||
-rw-r--r-- | src/pulse/def.h | 4 | ||||
-rw-r--r-- | src/pulse/introspect.h | 76 |
4 files changed, 80 insertions, 8 deletions
@@ -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 diff --git a/src/modules/alsa/mixer/paths/analog-output.conf.common b/src/modules/alsa/mixer/paths/analog-output.conf.common index 7bf346346..31d4b447b 100644 --- a/src/modules/alsa/mixer/paths/analog-output.conf.common +++ b/src/modules/alsa/mixer/paths/analog-output.conf.common @@ -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 diff --git a/src/pulse/def.h b/src/pulse/def.h index 2e5a5ec37..4097bd89c 100644 --- a/src/pulse/def.h +++ b/src/pulse/def.h @@ -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, diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h index 89685b501..657510747 100644 --- a/src/pulse/introspect.h +++ b/src/pulse/introspect.h @@ -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 |