diff options
author | Tanu Kaskinen <tanuk@iki.fi> | 2020-06-17 08:14:18 +0300 |
---|---|---|
committer | Tanu Kaskinen <tanuk@iki.fi> | 2020-08-10 20:54:21 +0300 |
commit | 0ce3008605e5f644fac4bb5edbb1443110201ec1 (patch) | |
tree | e6a2c6570e659ba0a7f6abc9057423b31d7327e0 /src/pulse | |
parent | 2c790e193730f17b70734a26a417f46189fbc6c0 (diff) | |
download | pulseaudio-0ce3008605e5f644fac4bb5edbb1443110201ec1.tar.gz |
Improve the port available_group and type documentation
Diffstat (limited to 'src/pulse')
-rw-r--r-- | src/pulse/def.h | 4 | ||||
-rw-r--r-- | src/pulse/introspect.h | 76 |
2 files changed, 73 insertions, 7 deletions
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 |