Bearbeiten von „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 [[RoarAudio/Programmieren/VIO DSTR|VIO DSTR API]] verwendet werden.

Deklaration eins VIO Objektes:
 struct roar_vio_calls vio;

Beispiel: Öffnen der [[stdin|Standard Eingabe]]:
 if ( roar_vio_open_fh(&vio, ROAR_STDIN) == -1 ) {
  return -1;
 }

== 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_read(&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 ==
{{Homepage|roaraudio.keep-cool.org}}

[[Kategorie:RoarAudio]]
[[Kategorie:Software]]
[[Kategorie:Sound]]
[[Kategorie:Programmierung]]
{{Stub}}
@@ Zeile 11: / Zeile 11: @@
    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 [[RoarAudio/Programmieren/VIO DSTR|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 [[RoarAudio/Programmieren/VIO DSTR|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 ==
@@ Zeile 78: / Zeile 46: @@
 Beispiel:
-  ret = roar_vio_write(&vio, datablock, 512);
+  ret = roar_vio_read(&vio, datablock, 512);
 Siehe auch: write(2)