RoarAudio/Programmieren/VS

Die Very Simple API oder auch VS ist eine API die sich an die Simple APIs verschiedener anderer Sound Systeme anlehnt und einen leichten Umstieg ermöglichen soll. Im Sie ist recht stark limitiert. Ihr größtes Limit liegt darin das sie im Normalfall nur einen Stream pro Klient verwalten kann.

Die VS ist vollständig Objekt-Orientiert und kann auch einige der Funktionen die RoarAudio herausstellen bedienen. Sie hat weiterhin Schnittstellen-Funktionen um an die Internen Objekte heran zu kommen und ermöglicht somit mit der normalen API gemischt verwendet zu werden.

Grundsätzlicher Ablauf

Zu Beginn wird ein VS Objekt erzeugt. Dieses ist Bereits mit dem Server verbunden. Nun werden Stream Parameter gesetzt und ein Stream auf dem Server erzeugt. Dies Kann auch in Kombination mit dem erzeugen des Objektes geschehen. Nun können Operationen auf das Objekt angewendet werden. Zum Beispiel können Audio Daten geschrieben werden. Nach dem man fertig ist wird das Objekt wieder Freigegeben und die Verbindung zum Server voll automatisch getrennt.

Fehlerbehandlung

Alle Funktionen verwenden -1 oder NULL zur Fehlerrückgabe. Sie haben einen Parameter namens error welcher dazu genutzt werden kann um einen Fehler Code zu bekommen.

Die Funktion roar_vs_strerr() kann dazu verwendet werden um Lesbare Fehlermeldungen zu erzeugen.

Beispiel

int err;
int ret;

ret = roar_vs_mute(vss, ROAR_VS_TRUE, &err);

if ( ret == -1 ) {
 fprintf(stderr, "Fehler: %s\n", roar_vs_strerr(err));
}

Öffnen einer Verbindung zum Server und eines Streams

...

Schließen der Verbindung

Zum Schließen der Verbindung wird kommt die Funktion roar_vs_close() zum Einsatz. Dieser wird das Verbindungs-Objekt, der Pointer zur Fehlercode Variable sowie der Parameter killit übergeben.

Der Parameter killit kann entweder ROAR_VS_TRUE oder ROAR_VS_FALSE sein. Ist er auf ROAR_VS_TRUE gesetzt wird die Wiedergabe sofort beendet. Ist er auf ROAR_VS_FALSE so wird der verbliebene Puffer (im Klient, Netzwerk und Server) erst zu ende abgespielt. Dies kann im besonderen dann einen Unterschied im Sekunden Bereich machen, sollte die Übertragung einen stark komprimierten Codec einsetzen.

Beispiel

int ret;

ret = roar_vs_close(vss, ROAR_VS_FALSE, &err);

Schreiben und Lesen von Audio Daten

Zum Schreiben und Lesen von Audio Daten stehen die Funktionen roar_vs_write() und roar_vs_read() zur Verfügung. Diese erhalten folgende Parameter:

• Das Verbindungs-Objekt,
• Den Puffer zu den Daten,
• Die Länge der Daten in Byte,
• Den Pointer auf die Fehlercode Variable.

Der Rückgabewert ist die Anzahl der wirklich geschriebenen oder gelesenen Bytes oder -1 im Fehlerfalle. Die Anzahl kann kleiner sein als die vorgegebene Länge. Hierbei handelt es sich nicht um einen Fehler sondern nur darum das zum aktuellen Zeitpunkt nicht mehr Daten geschrieben oder gelesen werden können. Ein Programm muss es dann erneut versuchen.

Beispiele

Hier sei ein Programm gezeigt welches zwischen zwei Verbindungen kopiert. Dieses Programm Liest die Fehlercodes nicht aus. Ein reelles Programm sollte dies tun.

ssize_t ret;
char buf[1024];

while ((ret = roar_vs_read(vss0, buf, sizeof(buf), NULL)) != -1) {
 if ( roar_vs_write(vss1, buf, ret, NULL) != ret ) {
  // Short-Write handling.
 }
}

Andere Operationen

...

Interaktion mit der Haupt API

...

Siehe Auch

• RoarAudio

UUGRN-Wiki verbessern („Stub”)

Dieser Artikel ist leider sehr kurz. Also: Sei mutig und mache aus ihm bitte einen guten Artikel, wenn du mehr zum Thema „RoarAudio/Programmieren/VS” weißt.