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

### Querying available modes and devices

Various playback and capture modes are available, for example DirectSound on all Windows platforms or “Windows Audio Session API” for Windows Vista. It is important to note that the available devices depend on the current mode; not all devices are available for all modes.

The default playback and capture modes can be queried with:

`unsigned int ts3client_getDefaultPlayBackMode(` | result`)`; |

`int* result`;

`unsigned int ts3client_getDefaultCaptureMode(` | result`)`; |

`int* result`;

Parameters

- `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.

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`;

Parameters

- `result`

  Address of a variable that receives a NULL-terminated array { { char* modeID, char* name }, { char* modeID, char* name }, ... , NULL } listing available playback or capture modes.

  Unless the function returns an error, the caller must release modeID, name and the array itself 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 ***array;

    if(ts3client_getPlaybackModeList(&array) == ERROR_ok) {
        for(int i=0; array[i] != NULL; ++i) {
            char *modeID = array[i][0];
    	char *name = array[i][1];
    	// ...
    	ts3client_freeMemory(array[i][0]);
    	ts3client_freeMemory(array[i][1]);
    	ts3client_freeMemory(array[i]);
        }
        ts3client_freeMemory(array);
    }

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

To query the default playback and capture devices, call

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

`int modeID`;
`char*** result`;

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

`int modeID`;
`char*** result`;

Parameters

- `modeID`

  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 { char* name, char* device } (not NULL-terminated, always returns a tuple).

  Unless the function returns an error, the caller must free name, device and the array itself 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 the default playback device:

    int modeID;
    char** defaultPlaybackDevice;

    if(ts3client_getDefaultPlayBackMode(&modeID) != ERROR_ok) {
        printf("Error getting default playback mode\n");
        return;
    }

    if(ts3client_getDefaultPlaybackDevice(modeID, &defaultPlaybackDevice) != ERROR_ok) {
        printf("Error getting default playback device\n");
        return;
    }

    if(defaultPlaybackDevice != NULL) {
        char *name = defaultPlaybackDevice[0];
        char *device = defaultPlaybackDevice[1];
        // ...
        ts3client_freeMemory(defaultPlaybackDevice[0]);
        ts3client_freeMemory(defaultPlaybackDevice[1]);
        ts3client_freeMemory(defaultPlaybackDevice);
    }

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

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

`int modeID`;
`char**** result`;

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

`int modeID`;
`char**** result`;

Parameters

- `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* name, char* device }, { char* name, char* device }, ... , NULL }.

  Unless the function returns an error, the array needs 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:

    int modeID;
    char*** array;

    if(ts3client_getDefaultPlayBackMode(& modeID) != ERROR_ok) {
        printf("Error getting default playback mode\n");
        return;
    }

    if(ts3client_getPlaybackDeviceList(modeID, &array) != ERROR_ok) {
        printf("Error getting playback device list\n");
        return;
    }

    for(int i=0; array[i] != NULL; ++i) {
        char *name = array[i][0];
        char *device = array[i][1];
        // ...
        ts3client_freeMemory(array[i][0]);
        ts3client_freeMemory(array[i][1]);
        ts3client_freeMemory(array[i]);
    }
    ts3client_freeMemory(array);

The string `device` string can be used as parameter for `ts3client_openPlaybackDevice` / `ts3client_openCaptureDevice`.

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