cubeb-api: Give cubeb_init a third param, backend name

This allows forcing of a particular backend by name,
*if* it was compiled in, otherwise default list is tried
in default order as before.

Tests updated to reflect new api.  (Gecko change required)

Using JACK backend:
100% tests passed, 0 tests failed out of 13
Total Test time (real) = 183.75 sec

Signed-off-by: Damien Zammit <damien@zamaudio.com>

include/cubeb/cubeb.h

@@ -414,10 +414,16 @@ typedef void (* cubeb_log_callback)(char const * fmt, ...);
                    context will be returned.
     @param context_name A name for the context. Depending on the platform this
                         can appear in different locations.
+    @param backend_name The name of the cubeb backend user desires to select.
+                        Accepted values self-documented in cubeb.c: init_oneshot
+                        If NULL, a default ordering is used for backend choice.
+                        A valid choice overrides all other possible backends,
+                        so long as the backend was included at compile time.
     @retval CUBEB_OK in case of success.
     @retval CUBEB_ERROR in case of error, for example because the host
                         has no audio hardware. */
-CUBEB_EXPORT int cubeb_init(cubeb ** context, char const * context_name);
+CUBEB_EXPORT int cubeb_init(cubeb ** context, char const * context_name,
+                                              char const * backend_name);
 
 /** Get a read-only string identifying this context's current backend.
     @param context A pointer to the cubeb context.

src/cubeb.c

@@ -8,6 +8,7 @@
 #include <assert.h>
 #include <stddef.h>
 #include <stdlib.h>
+#include <string.h>
 #include "cubeb/cubeb.h"
 #include "cubeb-internal.h"
 
@@ -105,9 +106,62 @@ validate_latency(int latency)
 }
 
 int
-cubeb_init(cubeb ** context, char const * context_name)
+cubeb_init(cubeb ** context, char const * context_name, char const * backend_name)
 {
-  int (* init[])(cubeb **, char const *) = {
+  int (* init_oneshot)(cubeb **, char const *) = NULL;
+
+  if (backend_name != NULL) {
+    if (!strcmp(backend_name, "pulse")) {
+#if defined(USE_PULSE)
+      init_oneshot = pulse_init;
+#endif
+    } else if (!strcmp(backend_name, "jack")) {
+#if defined(USE_JACK)
+      init_oneshot = jack_init;
+#endif
+    } else if (!strcmp(backend_name, "alsa")) {
+#if defined(USE_ALSA)
+      init_oneshot = alsa_init;
+#endif
+    } else if (!strcmp(backend_name, "audiounit")) {
+#if defined(USE_AUDIOUNIT)
+      init_oneshot = audiounit_init;
+#endif
+    } else if (!strcmp(backend_name, "wasapi")) {
+#if defined(USE_WASAPI)
+      init_oneshot = wasapi_init;
+#endif
+    } else if (!strcmp(backend_name, "winmm")) {
+#if defined(USE_WINMM)
+      init_oneshot = winmm_init;
+#endif
+    } else if (!strcmp(backend_name, "sndio")) {
+#if defined(USE_SNDIO)
+      init_oneshot = sndio_init;
+#endif
+    } else if (!strcmp(backend_name, "opensl")) {
+#if defined(USE_OPENSL)
+      init_oneshot = opensl_init;
+#endif
+    } else if (!strcmp(backend_name, "audiotrack")) {
+#if defined(USE_AUDIOTRACK)
+      init_oneshot = audiotrack_init;
+#endif
+    } else if (!strcmp(backend_name, "kai")) {
+#if defined(USE_KAI)
+      init_oneshot = kai_init;
+#endif
+    } else {
+      /* Already set */
+    }
+  }
+
+  int (* default_init[])(cubeb **, char const *) = {
+    /*
+     * init_oneshot must be at the top to allow user
+     * to override all other choices
+     */
+    init_oneshot,
 #if defined(USE_PULSE)
     pulse_init,
 #endif
@@ -145,10 +199,10 @@ cubeb_init(cubeb ** context, char const * context_name)
     return CUBEB_ERROR_INVALID_PARAMETER;
   }
 
-  for (i = 0; i < NELEMS(init); ++i) {
-    if (init[i](context, context_name) == CUBEB_OK) {
-      /* Assert that the minimal API is implemented. */
 #define OK(fn) assert((* context)->ops->fn)
+  for (i = 0; i < NELEMS(default_init); ++i) {
+    if (default_init[i] && default_init[i](context, context_name) == CUBEB_OK) {
+      /* Assert that the minimal API is implemented. */
       OK(get_backend_id);
       OK(destroy);
       OK(stream_init);
@@ -159,7 +213,6 @@ cubeb_init(cubeb ** context, char const * context_name)
       return CUBEB_OK;
     }
   }
-
   return CUBEB_ERROR;
 }
 

test/test_audio.cpp

@@ -119,7 +119,7 @@ int run_test(int num_channels, layout_info layout, int sampling_rate, int is_flo
 
   cubeb *ctx = NULL;
 
-  r = cubeb_init(&ctx, "Cubeb audio test: channels");
+  r = cubeb_init(&ctx, "Cubeb audio test: channels", NULL);
   if (r != CUBEB_OK) {
     fprintf(stderr, "Error initializing cubeb library\n");
     return r;
@@ -168,7 +168,7 @@ int run_panning_volume_test(int is_float)
 
   cubeb *ctx = NULL;
 
-  r = cubeb_init(&ctx, "Cubeb audio test");
+  r = cubeb_init(&ctx, "Cubeb audio test", NULL);
   if (r != CUBEB_OK) {
     fprintf(stderr, "Error initializing cubeb library\n");
     return r;

test/test_devices.cpp

@@ -109,7 +109,7 @@ TEST(cubeb, enumerate_devices)
   cubeb * ctx = NULL;
   cubeb_device_collection * collection = NULL;
 
-  r = cubeb_init(&ctx, "Cubeb audio test");
+  r = cubeb_init(&ctx, "Cubeb audio test", NULL);
   if (r != CUBEB_OK) {
     fprintf(stderr, "Error initializing cubeb library\n");
     ASSERT_EQ(r, CUBEB_OK);

test/test_duplex.cpp

@@ -82,7 +82,7 @@ TEST(cubeb, duplex)
   user_state_duplex stream_state = { false };
   uint32_t latency_frames = 0;
 
-  r = cubeb_init(&ctx, "Cubeb duplex example");
+  r = cubeb_init(&ctx, "Cubeb duplex example", NULL);
   if (r != CUBEB_OK) {
     fprintf(stderr, "Error initializing cubeb library\n");
     ASSERT_EQ(r, CUBEB_OK);

test/test_latency.cpp

@@ -11,7 +11,7 @@ TEST(cubeb, latency)
   uint32_t latency_frames;
   cubeb_channel_layout layout;
 
-  r = cubeb_init(&ctx, "Cubeb audio test");
+  r = cubeb_init(&ctx, "Cubeb audio test", NULL);
   ASSERT_EQ(r, CUBEB_OK);
 
   r = cubeb_get_max_channel_count(ctx, &max_channels);

test/test_overload_callback.cpp

@@ -57,7 +57,7 @@ TEST(cubeb, overload_callback)
   int r;
   uint32_t latency_frames = 0;
 
-  r = cubeb_init(&ctx, "Cubeb callback overload");
+  r = cubeb_init(&ctx, "Cubeb callback overload", NULL);
   ASSERT_EQ(r, CUBEB_OK);
 
   output_params.format = STREAM_FORMAT;

test/test_record.cpp

@@ -76,7 +76,7 @@ TEST(cubeb, record)
   int r;
   user_state_record stream_state = { false };
 
-  r = cubeb_init(&ctx, "Cubeb record example");
+  r = cubeb_init(&ctx, "Cubeb record example", NULL);
   if (r != CUBEB_OK) {
     fprintf(stderr, "Error initializing cubeb library\n");
     ASSERT_EQ(r, CUBEB_OK);

test/test_sanity.cpp

@@ -85,7 +85,7 @@ TEST(cubeb, init_destroy_context)
   cubeb * ctx;
   char const* backend_id;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -106,7 +106,7 @@ TEST(cubeb, init_destroy_multiple_contexts)
   ASSERT_EQ(ARRAY_LENGTH(ctx), ARRAY_LENGTH(order));
 
   for (i = 0; i < ARRAY_LENGTH(ctx); ++i) {
-    r = cubeb_init(&ctx[i], NULL);
+    r = cubeb_init(&ctx[i], NULL, NULL);
     ASSERT_EQ(r, CUBEB_OK);
     ASSERT_NE(ctx[i], nullptr);
   }
@@ -124,7 +124,7 @@ TEST(cubeb, context_variables)
   uint32_t value;
   cubeb_stream_params params;
 
-  r = cubeb_init(&ctx, "test_context_variables");
+  r = cubeb_init(&ctx, "test_context_variables", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -157,7 +157,7 @@ TEST(cubeb, init_destroy_stream)
   cubeb_stream * stream;
   cubeb_stream_params params;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -186,7 +186,7 @@ TEST(cubeb, init_destroy_multiple_streams)
   cubeb_stream * stream[8];
   cubeb_stream_params params;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -219,7 +219,7 @@ TEST(cubeb, configure_stream)
   cubeb_stream * stream;
   cubeb_stream_params params;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -255,7 +255,7 @@ test_init_start_stop_destroy_multiple_streams(int early, int delay_ms)
   cubeb_stream * stream[8];
   cubeb_stream_params params;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -355,7 +355,7 @@ TEST(cubeb, init_destroy_multiple_contexts_and_streams)
 #endif
 
   for (i = 0; i < ARRAY_LENGTH(ctx); ++i) {
-    r = cubeb_init(&ctx[i], "test_sanity");
+    r = cubeb_init(&ctx[i], "test_sanity", NULL);
     ASSERT_EQ(r, CUBEB_OK);
     ASSERT_NE(ctx[i], nullptr);
 
@@ -383,7 +383,7 @@ TEST(cubeb, basic_stream_operations)
   cubeb_stream_params params;
   uint64_t position;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -434,7 +434,7 @@ TEST(cubeb, stream_position)
 
   total_frames_written = 0;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 
@@ -574,7 +574,7 @@ TEST(cubeb, drain)
   delay_callback = 0;
   total_frames_written = 0;
 
-  r = cubeb_init(&ctx, "test_sanity");
+  r = cubeb_init(&ctx, "test_sanity", NULL);
   ASSERT_EQ(r, CUBEB_OK);
   ASSERT_NE(ctx, nullptr);
 

test/test_tone.cpp

@@ -101,7 +101,7 @@ TEST(cubeb, tone)
   struct cb_user_data *user_data;
   int r;
 
-  r = cubeb_init(&ctx, "Cubeb tone example");
+  r = cubeb_init(&ctx, "Cubeb tone example", NULL);
   if (r != CUBEB_OK) {
     fprintf(stderr, "Error initializing cubeb library\n");
     ASSERT_EQ(r, CUBEB_OK);