RoarAudio/Programmieren/VIO

RoarAudio Verwendet so genannte Virtuellen Ein-/Ausgabe (VIO) Objekte für (nahezu) alle IO Belange. Dieses Dokument stellt kurz die Verwendung solcher VIO Objekte vor.

VIO Objekt öffnen

Zu Beginn muss ein VIO Objekt deklariert werden. Danach kann es mittels einer Funktion zum öffnen geöffnet werden. Für jeden VIO Objekt Type gibt es im Prinzip mindestens eine Open-Funktion. Ein Teil davon soll hier vorgestellt werden. Ein anderer Teil sollte am besten mittels VIO DSTR API verwendet werden.

Deklaration eins VIO Objektes:

struct roar_vio_calls vio;

Beispiel: Öffnen der Standard Eingabe:

if ( roar_vio_open_fh(&vio, ROAR_STDIN) == -1 ) {
 return -1;
}

Öffnen von Standard-Ein-/Ausgabe

Wie im oben Beispiel schon gezeigt kann die Standard Eingabe ganz einfach geöffnet werden. Zum Öffnen der Standard Ausgabe und der Standard Fehler Ausgabe muss der Parameter ROAR_STDIN nur auf ROAR_STDOUT beziehungsweise ROAR_STDERR geändert werden:

ret = roar_vio_open_fh(&vio, ROAR_STDIN );
ret = roar_vio_open_fh(&vio, ROAR_STDOUT);
ret = roar_vio_open_fh(&vio, ROAR_STDERR);

Öffnen von Dateien

Zum Öffnen von Dateien wird roar_vio_open_file() verwendet. Diese Funktion ist nahezu äquivalent zu open(2).

Beispiel:

if ( roar_vio_open_file(&vio, "/etc/motd", O_RDONLY, 0644) == -1 ) {
 return -1;
}

Da die Verwendung von open(2) und seine Parameter nur bedingt Portabel sind kann hier auf VIO DSTR API zurückgegriffen werden. libroar wird dennoch alles tun um eine möglichst einheitliche Schnittstelle zu erzeugen. So sind Beispielsweise Patches für win32 vorhanden um POSIX/UNIX typische Parameter zu unterstützen.

Die von der Verwendung von O_BINARY wird, aus Kompatibilitätsgründen, deutlich abgeraten. Dies wird von der Bibliothek automatisch gesetzt sofern nötig.

Sockets

Da Sockets eine hochgradig Unportable Schnittstelle haben ist dies eines der klassischen Einsatzgebiete der VIOs.

Zur Verwendung von Sockets wird aufs dringlichste empfohlen die VIO DSTR API zu verwenden.

Bereits offene Sockets verwenden

Sind bereits offene Sockets vorhanden so können diese in ein VIO Objekt umgewandelt werden. Dies gescheit mittels roar_vio_open_fh_socket().

Beispiel:

ret = roar_vio_open_fh_socket(&vio, socketfd);

Die Verwendung dieser Funktion, anstatt roar_vio_open_fh() (s.o.) ist unter einigen Systemen dringend erforderlich. Aus diesem Grunde sollte diese Unterscheidung immer durchgeführt werden damit eine maximal Portable Applikation entsteht. Abgesehen davon dass diese Funktion mit Sockets operiert ist sie absolut äquivalent zu roar_vio_open_fh().

Auf VIO Objekt operieren

Auf VIO Objekten kann prinzipiell alles getan werden was auf normalen Dateien (Flache Dateien, Sockets, ...) auch getan werden kann. Im folgenden werden die dazugehörigen Funktionen vorgestellt.

roar_vio_close()

Prototyp:

int     roar_vio_close   (struct roar_vio_calls * vio);

Diese Funktion schließt ein offenes VIO Objekt.

Beispiel:

riar_vio_close(&vio);

roar_vio_read()

Prototyp:

ssize_t roar_vio_read    (struct roar_vio_calls * vio, void *buf, size_t count);

Diese Funktion versucht count Bytes in den Puffer buf von vio ein zu lesen.

Es wird die Anzahl wirklich gelesener Byte zurück gegeben.

Beispiel:

ret = roar_vio_read(&vio, datablock, 512);

Siehe auch: read(2)

roar_vio_write()

Prototyp:

ssize_t roar_vio_write   (struct roar_vio_calls * vio, void *buf, size_t count);

Diese Funktion versucht count Bytes aus dem Puffer buf nach vio zu schreiben.

Es wird die Anzahl wirklich geschriebenen Byte zurück gegeben.

Beispiel:

ret = roar_vio_write(&vio, datablock, 512);

Siehe auch: write(2)

roar_vio_lseek()

Prototyp:

off_t   roar_vio_lseek   (struct roar_vio_calls * vio, off_t offset, int whence);

Diese Funktion versucht an eine andere Position im Datenstrom zu springen. Die Position wird druch offset und whence festgelegt.

Es wird die neue Position vom Anfang des Datenstroms in Byte zurück gegen.

Beispiel:

if ( roar_vio_lseek(&vio, 0, SEEK_SET) != 0 ) {
  return -1;
}

Siehe auch: lseek(2)

roar_vio_nonblock()

Prototyp:

int     roar_vio_nonblock (struct roar_vio_calls * vio, int state);

Diese Funktion setzt den Non-Blocking-Mode des Datenstroms.

Sie gibt entweder 0 für keinen Fehler oder -1 für Fehler zurück.

Beispiele:

ret = roar_vio_nonblock(&vio, ROAR_SOCKET_NONBLOCK);
ret = roar_vio_nonblock(&vio, ROAR_SOCKET_BLOCK);

roar_vio_sync()

Prototyp:

int     roar_vio_sync    (struct roar_vio_calls * vio);

Diese Funktion synchronisiert die Daten aus dem Datenstrom mit den darunter liegenden Ebenen. Sie kann dazu benutzt werden um zu erzwingen das Daten auf die Festplatte geschrieben werden (z.B. kritische Log Dateien).

Sie gibt entweder 0 für keinen Fehler oder -1 für Fehler zurück.

Weder ein erfolgreicher noch ein nicht erfolgreicher Aufruf garantieren das die Daten tatsächlich alle Tieferen Ebenen durschritten haben. Als Beispiel können sie noch im Cache der Festplatte selbst sich befinden.

roar_vio_ctl()

Prototyp:

int     roar_vio_ctl     (struct roar_vio_calls * vio, int cmd, void * data);

Diese Funktion ermöglicht spezielle Zugriffe auf das VIO Objekt welche nicht durch die obigen Funktionen abgedeckt sind.

Der Aufruf dieser Funktion gibt in der Regel 0 für keinen Fehler oder -1 für einen Fehler Zustand zurück.

Bedeutung von data ist abhängig von cmd. cmd kann je nach VIO Type verschiedene werte annehmen. Die Bedeutung des Rückgabewerts hängt ebenfalls von cmd ab.

Siehe Auch

• RoarAudio

Weblinks

Offizielle Webpräsenz „RoarAudio/Programmieren/VIO”

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/VIO” weißt.