pulse: Add verbose volume printing functions

For more informative logging.

src/map-file

@@ -142,6 +142,7 @@ pa_cvolume_set_balance;
 pa_cvolume_set_fade;
 pa_cvolume_set_position;
 pa_cvolume_snprint;
+pa_cvolume_snprint_verbose;
 pa_cvolume_valid;
 pa_encoding_to_string;
 pa_ext_device_manager_delete;
@@ -361,6 +362,7 @@ pa_utf8_filter;
 pa_utf8_to_locale;
 pa_utf8_valid;
 pa_volume_snprint;
+pa_volume_snprint_verbose;
 pa_xfree;
 pa_xmalloc;
 pa_xmalloc0;

src/pulse/volume.c

@@ -361,6 +361,48 @@ char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c) {
     return s;
 }
 
+char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB) {
+    char *current = s;
+    bool first = true;
+
+    pa_assert(s);
+    pa_assert(l > 0);
+    pa_assert(c);
+
+    pa_init_i18n();
+
+    if (!pa_cvolume_valid(c)) {
+        pa_snprintf(s, l, _("(invalid)"));
+        return s;
+    }
+
+    pa_assert(!map || (map->channels == c->channels));
+    pa_assert(!map || pa_channel_map_valid(map));
+
+    current[0] = 0;
+
+    for (unsigned channel = 0; channel < c->channels && l > 1; channel++) {
+        char channel_position[32];
+        size_t bytes_printed;
+        char buf[PA_VOLUME_SNPRINT_VERBOSE_MAX];
+
+        if (map)
+            pa_snprintf(channel_position, sizeof(channel_position), "%s", pa_channel_position_to_string(map->map[channel]));
+        else
+            pa_snprintf(channel_position, sizeof(channel_position), "%u", channel);
+
+        bytes_printed = pa_snprintf(current, l, "%s%s: %s",
+                                    first ? "" : ",   ",
+                                    channel_position,
+                                    pa_volume_snprint_verbose(buf, sizeof(buf), c->values[channel], print_dB));
+        l -= bytes_printed;
+        current += bytes_printed;
+        first = false;
+    }
+
+    return s;
+}
+
 char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v) {
     double f;
 
@@ -380,6 +422,28 @@ char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v) {
     return s;
 }
 
+char *pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB) {
+    char dB[PA_SW_VOLUME_SNPRINT_DB_MAX];
+
+    pa_assert(s);
+    pa_assert(l > 0);
+
+    pa_init_i18n();
+
+    if (!PA_VOLUME_IS_VALID(v)) {
+        pa_snprintf(s, l, _("(invalid)"));
+        return s;
+    }
+
+    pa_snprintf(s, l, "%" PRIu32 " / %3u%%%s%s",
+                v,
+                (v * 100 + PA_VOLUME_NORM / 2) / PA_VOLUME_NORM,
+                print_dB ? " / " : "",
+                print_dB ? pa_sw_volume_snprint_dB(dB, sizeof(dB), v) : "");
+
+    return s;
+}
+
 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) {
     unsigned c;
     pa_assert(a);

src/pulse/volume.h

@@ -174,6 +174,18 @@ char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
 /** Pretty print a volume structure but show dB values. \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().
+ * Please note that this value can change with any release without warning and
+ * without being considered API or ABI breakage. You should not use this
+ * definition anywhere where it might become part of an ABI. \since 5.0 */
+#define PA_CVOLUME_SNPRINT_VERBOSE_MAX 1984
+
+/** 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 */
+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
  * pa_volume_snprint(). Please note that this value can change with
  * any release without warning and without being considered API or ABI
@@ -194,6 +206,17 @@ char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
 /** Pretty print a volume but show dB values. \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().
+ * Please note that this value can change with any release without warning and
+ * withou being considered API or ABI breakage. You should not use this
+ * definition anywhere where it might become part of an ABI. \since 5.0 */
+#define PA_VOLUME_SNPRINT_VERBOSE_MAX 35
+
+/** 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 */
+char *pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB);
+
 /** Return the average volume of all channels */
 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE;