# Unofficial ALSA API documentation
ALSA has to be the **worst** documented API in the whole FOSS world, so since I
had to go trough the pain of reverse-engineering other programs I thought to save
you form the same pain. So I present to you the most half-hassed description of
the ALSA API on the interweb.

## Functions

### Interfaces
TODO

### Hints
Hints are names, descriptions and other information about sound cards, interfaces
and others. To get access to those hints there is a family of functions.

#### `snd_device_name_hint`
Get hints from a specified card of specified interface

```c
int snd_device_name_hint (int card, const char *iface, void ***hints);
```

ARGS:

* `(int)card`: specifies the card index number, -1 means all cards
* `(char *)iface`: interface identification (like "pcm", "rawmidi", "timer", "seq")

RESULT:

* `(void ***)hints`: hints will receive a NULL-terminated array of device name
hints, which can be passed to `snd_device_name_get_hint()` to extract usable values.
When no longer needed, hints should be passed to `snd_device_name_free_hint()` to
release resources.

RETURN: `(int)` 0 on success or negative error code

#### `snd_device_name_get_hint`
Extract selected hint form hints array

```c
char* snd_device_name_get_hint (const void *hint, const char *id);
```

ARGS:

* `(const void *)hint`: a pointer to a hint which can be gotten by referencing
`hints[i]` from `snd_device_name_hint()`, where `i` is the card index
* `(const char *)id`: hint value to extract, valid IDs are
	- NAME: name of device
	- DESC: description of device
	- IOID: input / output identification ("Input" or "Output"), NULL means both

RESULT: RETURN: `(char *)` gives a pointer to a string containing the requested
hint or NULL on error, the result should be freed when done.

#### `snd_device_name_free_hint`
Free hints array

```c
int snd_device_name_free_hint (void **hints);
```

ARGS:

* `(void **)hints`: hints array gotten from `snd_device_name_hint`

RETURN: `(int)` 0 on success or negative code on error

#### Example
Get hints from all pcms of all cards and print them out

```c
#define _POSIX_C_SOURCE 200809L
#include <stdio.h>
#include <stdlib.h>

#include <alsa/asoundlib.h>

int main (int argc, char *argv[])
{
	void **hints, **n;
	char *name, *descr, *descr1, *io;

	if (snd_device_name_hint(-1, "pcm", &hints) < 0)
		return -1;
	n = hints;
	while (*n != NULL) {
		name = snd_device_name_get_hint(*n, "NAME");
		descr = snd_device_name_get_hint(*n, "DESC");
		io = snd_device_name_get_hint(*n, "IOID");
		printf("%s\n", name);
		if ((descr1 = descr) != NULL) {
			printf("    ");
			while (*descr1) {
				if (*descr1 == '\n')
					printf("\n    ");
				else
					putchar(*descr1);
				descr1++;
			}
			putchar('\n');
		}
	      	if (name != NULL)
	      		free(name);
		if (descr != NULL)
			free(descr);
		if (io != NULL)
			free(io);
		n++;
	}
	snd_device_name_free_hint(hints);
	return 0;
}
```