order.png

Radiostream™ XML Interface

Zur Steuerung aus eigenen Anwendungen

Diese Anleitung beschreibt die Verwendung der Radiostream™ XML Schnittstelle zur Steuerung Ihres Stream-Servers aus eigenen Anwendungen heraus anhand eines konkreten Beispiels für PHP.

XML Schnittstelle

URL der Schnittstelle

Die Schnittstelle ist erreichbar unter der Adresse https://www.radiostream.de/api (SSL)

Aufbau der XML Requests

Die XML Requests, die an Radiostream™ gesendet werden, sind immer wie folgt aufgebaut:

<?xml version="1.0" encoding="UTF-8"?>
<radiostream>
   <request class="server" method="start" />
         <username>xxx</username>
         <password>....</password>
          .... optionale weitere tags siehe Beschreibung Methoden ....
</radiostream>

Die Angabe class="server" ist vorgegeben, und bedeutet, dass Sie den Server steuern möchten. Andere Klassen können ggf. in der Zukunft ergänzt werden, existieren derzeit aber nicht. Ein anderer Wert als server ist hier aktuell also nicht zulässig.

Die Angabe method ist die Methode, die auf dem Server aufgerufen werden soll. In diesem Beispiel ist die Methode start und bedeutet Starte Server.

Die Werte username und password entsprechen Ihren Zugangsdaten von Radiostream™ (Kundennummer oder Emailadresse, sowie ihr Zugangs-Passwort).

So einfach: Dieses oben gezeigte Beispiel ist also ein vollständiges Beispiel zum Starten des Servers.

Aufbau der XML Responses

Die Antworten sind immer wie folgt aufgebaut:

<radiostream>
   <status>...</status>
   <message>....</message>
</radiostream>

Das Attribut status enthält je nach Erfolg oder Mißerfolg des aufgerufenen Befehls success oder failed als Rückgabewert. Darüber hinaus gibt es noch einen dritten Rückgabewert error der einen fehlerhaft aufgerufenen Request kennzeichnet. Der Unterschied zwischen failed und error besteht also darin, dass ein failed-Request syntaktisch richtig war, aber kein erfolgreiches Ergebnis liefert. Ein error-Request kennzeichnet einen tatsächlichen Fehler.

success
Der Befehl wurde erfolgreich ausgeführt
failed
Der Befehl wurde nicht erfolgreich ausgeführt
error
Fehler z.B. Syntax Error

Im Feld message ist darüber hinaus eine verbale Meldung enthalten.

Methoden

Neben start aus dem o.g. Beispiel stehen weitere Methoden zur Verfügung. Dies ist die Liste der aktuell aufrufbaren Methoden und ggf. deren Parameter.

In allen Requests ist die Angabe von username und password Pflicht.

start
Startet den Server
stop
Stoppt den Server
serverstatus
Zeigt den Status des Servers an
sourcestatus
Zeigt den Status der Live-Quelle (Source) an
streamstatus
Zeigt den Status des Streams an, inkl. Server Name, aktuelle Anzahl Listener, Song Titel, durchschnittliche Hörerzeit etc.
kicksource
Trennt die Live-Quelle vom Server** z.B. für Moderatorenwechsel o.ä.
links
Zeigt alle Stream-Links an, z.B. URLs zu Status-Grafiken oder Player-Links zur Einbindung in Ihre Homepage

Beispiel 1: Server einschalten

Request

<?xml version="1.0" encoding="UTF-8"?>
<radiostream>
   <username>2345</username>
   <password>geheim</password>
   <request class="server" method="start" />
</radiostream>

Response

<?xml version="1.0"?>
<radiostream>
   <status>success</status>
   <message>starting server: without errors</message>
</radiostream>

Beispiel 2: Stream Status abfragen

Request

<?xml version="1.0" encoding="UTF-8"?>
<radiostream>
   <username>2345</username>
   <password>geheim</password>
   <request class="server" method="streamstatus" />
</radiostream>

Response

<?xml version="1.0"?>
<radiostream>
   <status>success</status>
   <ServerTitle>[radiostream.de] Mein Radioservername</ServerTitle>
   <CurrentSongTitle>3-11 Porter - Surround Me With Your love(Mental Overdrive Edit)</CurrentSongTitle>
   <BitRatekbps>128</BitRatekbps>
   <CurrentListenersCount>147</CurrentListenersCount>
   <AverageListenTimeMin>84</AverageListenTimeMin>
   <StreamHitsCount>12213</StreamHitsCount>
   <LastStatus>2009-03-13 23:30:00</LastStatus>
</radiostream>

PHP Beispiel

Dieses PHP-Beispiel ist in PHP4 und PHP5 nutzbar.

Installation PEAR Package "XML_Serializer"

Führen Sie auf Ihrem System folgenden Befehl aus:

pear install XML_Parser
pear install XML_Util
pear install XML_Serializer

Sollte das Paket bereits auf Ihrem Server installiert sein, erhalten Sie folgende Meldung:

Ignoring installed package pear/XML_Serializer
Nothing to install

Fahren Sie dann wie folgt fort.

Radiostream™ PHP-Klasse

Laden Sie die folgende Datei auf Ihren Server und extrahieren Sie die PHP-Klasse class.xml-radiostream.php in das Webserver-Verzeichnis.

http://www.radiostream.de/radiostream-xml.zip

Programm Code einbinden

Das folgende Beispiel zeigt die eigenliche Integration des Programm-Codes in eigene Scripts:


<?php
// Einbinden der  Radiostream™Interface Klasse
include("class.xml-radiostream.php");

// Konfiguration: Radio-Kennung und Passwort
$user   = array(
        "username"      => "2345",
        "password"      => "geheim"
);

// initialisieren:
$rs = new RSInterface($user);

// Request senden und XML-Ergebnis ausgeben:
$res = $rs->GetResponse($rs->SendRequest("streamstatus"));

print_r($res);
?>

Ergibt folgende Ausgabe:

stdClass Object
(
    [status] => success
    [winamp] => http://www.radiostream.de/stream/12345.pls
    [windowsmedia] => http://www.radiostream.de/stream/12345.asx
    [realplayer] => http://www.radiostream.de/stream/12345.ram
    [quicktime] => http://www.radiostream.de/stream/12345.qtl
    [mpegurl] => http://www.radiostream.de/stream/12345.m3u
)

Für Erweiterungswünsche schreiben Sie an admin@radiostream.de.