Querying available modes and devices

Querying available modes and devices
	Using playback and capture modes and devices

Various playback and capture modes are available: DirectSound on all Windows platforms, Windows Audio Session API for Windows Vista and Windows 7; Alsa and PulseAudio on Linux; CoreAudio on Mac OS X.

Available device names may differ depending on the current mode.

The default playback and capture modes can be queried with:

unsigned int ts3client_getDefaultPlayBackMode( result);

char** result;

unsigned int ts3client_getDefaultCaptureMode( result);

char** result;

result
Address of a variable that receives the default playback or capture mode. The value can be used as parameter for the functions querying and opening devices. Unless the function returns an error, the string must be released using ts3client_freeMemory.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

All available playback and capture modes can be queried with:

unsigned int ts3client_getPlaybackModeList( result);

char*** result;

unsigned int ts3client_getCaptureModeList( result);

char*** result;

result
Address of a variable that receives a NULL-terminated array of C-strings listing available playback or capture modes.
Unless the function returns an error, the caller must release each element of the array (the C-string) and finally the complete array with ts3client_freeMemory.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. In case of an error, the result array is uninitialized and must not be accessed or released.

Example to query all available playback modes:

char** array;

if(ts3client_getPlaybackModeList(&array) == ERROR_ok) {
    for(int i=0; array[i] != NULL; ++i) {
        printf("Mode: %s\n", array[i]);
        ts3client_freeMemory(array[i]);  // Free C-string
    }
    ts3client_freeMemory(array);  // Free the array
}

Playback and capture devices available for the given mode can be listed, as well as the current operating systems default. The returned device values can be used to initialize the devices.

To query the default playback and capture device, call

`unsigned int ts3client_getDefaultPlaybackDevice(`	`modeID`,
	`result)`;

const char* modeID;
char*** result;

`unsigned int ts3client_getDefaultCaptureDevice(`	`modeID`,
	`result)`;

const char* modeID;
char*** result;

mode
Defines the playback/capture mode to use. For different modes there might be different default devices. Valid modes are returned by ts3client_getDefaultPlayBackMode / ts3client_getDefaultCaptureMode and ts3client_getPlaybackModeList / ts3client_getCaptureModeList.
result
Address of a variable that receives an array of two C-strings. The first element contains the device name, the second the device ID.
Unless the function returns an error, the caller must free the two array elements and the complete array with ts3client_freeMemory.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. In case of an error, the result array is uninitialized and must not be released.

Example to query the default playback device:

char* defaultMode;

/* Get default playback mode */
if(ts3client_getDefaultPlayBackMode(&defaultMode) == ERROR_ok) {
    char** defaultPlaybackDevice;

    /* Get default playback device */
    if(ts3client_getDefaultPlaybackDevice(defaultMode, &defaultPlaybackDevice) == ERROR_ok) {
        printf("Default playback device name: %s\n", defaultPlaybackDevice[0]);  /* First element: Device name */
        printf("Default playback device ID: %s\n",   defaultPlaybackDevice[1]);  /* Second element: Device ID */

        /* Release the two array elements and the array */
        ts3client_freeMemory(defaultPlaybackDevice[0]);
        ts3client_freeMemory(defaultPlaybackDevice[1]);
        ts3client_freeMemory(defaultPlaybackDevice);
    } else {
        printf("Failed to get default playback device\n");
    }
} else {
    printf("Failed to get default playback mode\n");
}

To get a list of all available playback and capture devices for the specified mode, call

`unsigned int ts3client_getPlaybackDeviceList(`	`modeID`,
	`result)`;

const char* modeID;
char**** result;

`unsigned int ts3client_getCaptureDeviceList(`	`modeID`,
	`result)`;

const char* modeID;
char**** result;

modeID
Defines the playback/capture mode to use. For different modes there might be different device lists. Valid modes are returned by ts3client_getDefaultPlayBackMode / ts3client_getDefaultCaptureMode and ts3client_getPlaybackModeList / ts3client_getCaptureModeList.
result
Address of a variable that receives a NULL-terminated array { { char* deviceName, char* deviceID }, { char* deviceName, char* deviceID }, ... , NULL }.
Unless the function returns an error, the elements of the array and the array itself need to be freed using ts3client_freeMemory.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. In case of an error, the result array is uninitialized and must not be released.

Example to query all available playback devices:

char* defaultMode;

if(ts3client_getDefaultPlayBackMode(&defaultMode) == ERROR_ok) {
    char*** array;

    if(ts3client_getPlaybackDeviceList(defaultMode, &array) == ERROR_ok) {
        for(int i=0; array[i] != NULL; ++i) {
            printf("Playback device name: %s\n", array[i][0]);  /* First element: Device name */
            printf("Playback device ID: %s\n",   array[i][1]);  /* Second element: Device ID */

            /* Free element */
            ts3client_freeMemory(array[i][0]);
            ts3client_freeMemory(array[i][1]);
            ts3client_freeMemory(array[i]);
        }
        ts3client_freeMemory(array);  /* Free complete array */
    } else {
        printf("Error getting playback device list\n");
    }
} else {
    printf("Error getting default playback mode\n");
}


Using playback and capture modes and devices		Checking current modes and devices