Vorlage:Tuxbox nhttpd

Der Neutrino http daemon bietet die Möglichkeit, diverse Funktionen über das HTTP-Protokoll abzufragen oder zu steuern. Auch sehr hilfreich für externe Tools, die auf diese Schnittstelle zugreifen und damit Neutrino steuern oder Informationen abrufen können. Ein bekanntes Beispiel wäre Jack the Grabber oder andere Streaming-Programme. Die Abfrage oder Steuerung kann über einen ganz normalen Browser (Internet Explorer, Opera, Mozilla, Firefox) oder aber auch über Kommandozeilen-Tools (wget, lynx) erfolgen.

Normalerweise wird die Steuerung von Neutrino über das Webinterface (nhttpd) nicht durch eine Benutzer/Kennwortabfrage geschützt. Wie man dies trotzdem erreichen kann wird hier beschrieben.

nhttpd /control api doku

Diese Dokumentation ist auch im CVS hier zu finden. Bei Aufrufen vom Browser ist im Handler "dbox" durch die IP Adresse der Dbox zu ersetzen.

Die Kanalliste

Handler: http://dbox/control/channellist
Parameter: keine
Rückgabe: Es wird die gesamte Kanalliste von Neutrino zurückgegeben. Jede Zeile wird von einem Enter (\n) von der Nächsten getrennt. Eine Zeile enthält ein Programm.

Rückgabeformat: channel_id Programmname

Die channel_id dient als Handle für andere Operationen wie Zappen oder EPG. Die channel_id ist eine 64 bit Hexadezimalzahl.

Beispiel:

>>>http://dbox/control/channellist
16dca Das Erste
16e29 EinsExtra
16e2a EinsFestival
16e2b EinsMuXx
16d66 ZDF

EPG-Abfrage

Handler: http://dbox/control/epg

Parameter: keine
Rückgabe: Es werden alle verfügbaren EPGs aller Programme zur aktuellen Zeit zurückgegeben. Jede Zeile wird von einem Enter (\n) von der Nächsten getrennt. Eine Zeile enthält die Information über die aktuell laufende Sendung.

Rückgabeformat: channel_id EVENTID Titel der Sendung

Die EVENTID dient als Handle um genauere Informationen abzufragen.

Beispiel:

>>>http://dbox/control/epg
8716804 571264467523 Wasserloch Nr. 3
8716304 571231699926 Ein Käfig voller Helden
8716311 571232198133 Cop Rock

Parameter: channel_id (64 bit, hexadezimal)
Rückgabe: Als Rückgabe wird die Eventliste des durch die channel_id identifizierten Senders gesendet, d.h. eine Liste, welche Filme auf diesem Sender kommen. Jede Zeile wird von einem Enter (\n) von der Nächsten getrennt.

Rückgabeformat: EVENTID Startzeit Dauer Titel der Sendung

Die EVENTID dient als Handle um genauere EPG-Informationen abzufragen.

Beispiel:

>>>http://dbox/control/epg?8716304
571231699925 1021322700 1500 Shooting Stars
571231699926 1021324200 1500 Ein Kaefig voller Helden
571231699927 1021325700 1500 The Hitchhiker
571231699928 1021327200 1500 The Hitchhiker

Parameter: id=channel_id
Rückgabe: Als Rückgabe wird die Eventliste des durch die channel_id identifizierten Senders gesendet, das heißt eine Liste, was für Filme auf einem Sender kommen. Jeder Datensatz wird von einem EnterEnter (\n\n) vom Nächsten getrennt.

Rückgabeformat: EVENTID Startzeit DURATION TITLE INFO1 INFO2

Die EVENTID dient als Handle um genauere EPG-Informationen abzufragen.

Beispiel:

>>>http://dbox/control/epg?id=16dcb
6143198520 1067754600 1800
Daten der Woche
Moderation: Andrea Müller
Themen:Š* Kandidatenkür: Maas wird SpitzenkandidatŠ* ......

6143198521 1067756400 1800
Abendschau
Themen:Š* Protestmarsch "Es reicht"Š* ..........

Parameter: eventid=EVENTID
Rückgabe: Es wird die ausführliche Beschreibung eines Films zurückgegeben. Diese besteht aus einem Titel, einer allgemeinen Info und der Beschreibung. Titel Info und Beschreibung werden mit einem Enter (\n) voneinander getrennt. Es muss beachtet werden, dass in der Beschreibung weitere Enter vorkommen können.

Rückgabeformat:
Titel
Info
Beschreibung

Beispiel:

>>>http://dbox/control/epg?eventid=571231699926
Ein Käfig voller Helden
Operation 'Tiger' 
blablabla

Parameter: ext
Rückgabe: Es werden alle verfügbaren EPGs aller Programme zur aktuellen Zeit zurückgegeben. Jede Zeile wird von einem Enter (\n) von der Nächsten getrennt. Eine Zeile enthält die Information über die aktuell laufende Sendung.

Rückgabeformat: channel_id Startzeit Dauer EVENTID Titel der Sendung

Die EVENTID dient als Handle um genauere Informationen abzufragen.

Beispiel:

>>>http://dbox/control/epg?ext
8716330 1025382300 6900 571233417784 Rocky 2

Die DBox herunterfahren

Handler: http://dbox/control/shutdown

Parameter: keine
Rückgabe: Es wird der Text "ok" bei Erfolg oder "error" im Fehlerfall zurückgegeben. Die Dbox schaltet sich bei "ok" sofort ab.

Rückgabeformat: ok / error

Beispiel:

>>>http://dbox/control/shutdown
ok

Standby Mode

Handler: http://dbox/control/standby

Parameter: on
Rückgabe: Schaltet in den Standby Mode

Rückgabeformat: ok /error

Beispiel:

>>>http://dbox/control/standby?on
ok

Parameter: off
Rückgabe: Schaltet den Standby Mode aus

Rückgabeformat: ok /error

Beispiel:

>>>http://dbox/control/standby?off
ok

Lautstärke-Steuerung

Handler: http://dbox/control/volume

Parameter: keine
Rückgabe: Es wird die aktuell eingestellte Lautstärke zurückgegeben - die Werte bewegen sich zwischen 0 (leise) und 100 (laut).

Rückgabeformat: Lautstärke

Beispiel:

>>>http://dbox/control/volume
80

Parameter: <Lautstärke als ganze Zahl in 5er Schritten>
Rückgabe: Es kann die Lautstärke eingestellt werden - die Werte müssen sich zwischen 0 (leise) und 100 (laut) bewegen. Es sollten nur Werte in 5er-Schritten gesetzt werden (5,10,...).

Rückgabeformat: ok / error

Beispiel:

>>>http://dbox/control/volume?40
ok

Parameter: mute
Rückgabe: Die Audio-Ausgabe wird abgeschaltet. Es kommt als Bestätigung der String "mute" zurück.

Rückgabeformat: ok

Beispiel:

>>>http://dbox/control/volume?mute
mute

Parameter: unmute
Rückgabe: Die Audio-Ausgabe wird wieder eingeschaltet. Es kommt als Bestätigung der String "unmute" zurück.

Rückgabeformat: ok

Beispiel:

>>>http://dbox/control/volume?mute
unmute

Parameter: status
Rückgabe: Es wird der Status (ob gerade mute aktiv ist) zurückgegeben. (0 - unmuted, 1 - mute)

Rückgabeformat: 0 oder 1

Beispiel:

>>>http://dbox/control/volume?status
1

Programm umschalten / Playback

Handler: http://dbox/control/zapto

Parameter: keine
Rückgabe: Es wird die channel_id (hex-value, 64 bit, kein 0x-prefix) des aktuell laufenden Senders zurückgegeben.

Beispiel:

>>>http://dbox/control/zapto
16dcb

Parameter: getpids
Rückgabe: Es werden die VPID und die APID des laufenden Senders angezeigt. Die beiden Werte sind durch ein Enter voneinander getrennt.

Rückgabeformat: VPID, APID

Beispiel:

>>>http://dbox/control/zapto?getpids
305
306

Parameter: getallpids
Rückgabe: Es werden die VTXT PID, VPID und alle APIDs des laufenden Senders angezeigt. Die Werte sind durch ein Enter voneinander getrennt. Hinter jeder APID wird eine kurze Beschreibung angegeben, bei AC3 Streams zusätzlich (AC3).

Rückgabeformat:
VPID
APID <description> [(AC3)]
[APID...]
[VTXT PID]

Beispiel:

>>>http://dbox/control/zapto?getallpids

00511
00512 deutsch
00513 englisch
00515 Dolby Digital 2.0
00032 vtxt
00101 pmt

oder

00101
00102 German  
00104 vtxt
00100 pmt

Parameter: stopplayback
Rückgabe: Stoppt die Decodierung, um grabben zu können. Zusätzlich wird der Sectionsd gestoppt. Rückgabewert sollte ok für Erfolg sein.

Rückgabeformat: ok / error

Beispiel:

>>>http://dbox/control/zapto?stopplayback
ok

Parameter: startplayback
Rückgabe: Startet die Decodierung nach dem Grabben wieder, Sectionsd wird auch wieder gestartet. Rückgabewert sollte ok für Erfolg sein.

Rückgabeformat: ok

Beispiel:

>>>http://dbox/control/zapto?startplayback
ok

Parameter: statusplayback
Rückgabe: '1': Playback aktiv, '0': kein Playback aktiv

Rückgabeformat: 0/1

Beispiel:

>>>http://dbox/control/zapto?statusplayback
0

Parameter: stopsectionsd
Rückgabe: Stoppt den Sectionsd zum Grabben. Rückgabewert sollte ok für Erfolg sein.

Rückgabeformat: ok

Beispiel:

>>>http://dbox/control/zapto?stopsectionsd
ok

Parameter: startsectionsd
Rückgabe: Startet Sectionsd nach dem Grabben wieder. Rückgabewert sollte "ok" für Erfolg sein.

Rückgabeformat: ok

Beispiel:

>>>http://dbox/control/zapto?startsectionsd
ok

Parameter: statussectionsd
Rückgabe: gibt den Status des Sectionsd zurück. (Scanning, bzw, kein Scanning)

Rückgabe-Format: '1': sectionsd scanning an, '0': sectionsd scanning aus

Beispiel:

>>>http://dbox/control/zapto?statussectionsd
1

Parameter: channel_id (64 bit, hexidecimal value)
Rückgabe: Zappt auf den angegebenen Kanal. Als Rückgabe ist im Erfolgsfall "ok" zu erwarten.

Rückgabeformat: ok / error

Beispiel:

>>>http://dbox/control/zapto?16dcb
ok

Radio/TV, Record Mode

Handler: http://dbox/control/setmode

Parameter: status
Rückgabe: Es wird der aktuelle record mode Status zurückgegeben

Rückgabeformat: on / off

Beispiel:

>>>http://dbox/control/setmode?status
on

Parameter: radio
Rückgabe: Schaltet in den radio mode

Rückgabeformat: ok / error

Beispiel:

>>>http://dbox/control/setmode?radio
ok

Parameter: tv
Rückgabe: Schaltet in den TV mode

Rückgabeformat: ok / error

Beispiel:

>>>http://dbox/control/setmode?tv
ok

Parameter: record
Rückgabe: Schaltet in den record mode Dies beinhaltet auch das Stoppen, bzw. das Starten des sectionsd Scanning, das Starten des Playbacks(immer) und Stoppen des Playbacks (nur bei stopplayback=true).

Rückgabeformat: ok / error

Beispiele:

>>>http://dbox/control/setmode?record=start
ok

>>>http://dbox/control/setmode?record=start&stopplayback=true
ok

>>>http://dbox/control/setmode?record=stop
ok

Radio/TV Mode Abfrage

Handler: http://dbox/control/getmode

Parameter:
Rückgabe: "tv", "radio", "unkown"

Es wird der aktuelle mode zurückgegeben tv / radio / unknown (shouldn't happen)

Beispiel:

>>>http://dbox/control/getmode
tv

Datum von der Box abfragen

Handler: http://dbox/control/getdate

Parameter: keine
Rückgabe: Es wird das Datum zurückgegeben.

Rückgabeformat: dd.mm.yyyy

Beispiel:

>>>http://dbox/control/getdate
25.02.2005

Uhrzeit von der Box abfragen

Handler: http://dbox/control/gettime

Parameter: keine
Rückgabe: Es wird die Uhrzeit zurückgegeben.

Rückgabeformat: hh:mm:ss

Beispiel:

>>>http://dbox/control/gettime
20:34:24

Parameter: rawtime
Rückgabe: Es wird die Uhrzeit im time_t Format zurückgegeben.

Rückgabeformat: time_t

Beispiel:

>>>http://dbox/control/gettime?rawtime
1046804654

Allgemeine Informationen abfragen

Handler: http://dbox/control/info

Parameter: streaminfo
Rückgabe: Es werden Streaminfos zurückgegeben. Die Werte sind durch Enter (\n) getrennt

Rückgabeformat: X_res Y_res Bitrate Videoformat Framerate Audioformat

Beispiel:

>>>http://dbox/control/info?streaminfo
480
576
997500
4:3
25
joint stereo

Parameter: version
Rückgabe: Aktuelle cramfs - Version. Es wird der Inhalt der Datei /.version zurückgegeben.

Beispiel:

>>>http://dbox/control/info?version
version: 1.1.27032002-21.8
md5sum: f1d7d47578bb9040a82085182934ce0e
Erstellt von alexW

Parameter: settings
Rückgabe: Aktuelle Settings und DBox Typ

Beispiel:

>>>http://dbox/control/info?settings
Boxtype Nokia
videooutput RGB
videoformat 4:3

Parameter: httpdversion
Rückgabe:
Version des httpd
1 : nhttpd (legacy api)
2 : thttpd
3 : nhttpd

Beispiel:

>>>http://dbox/control/info?httpdversion
3

Aktuellen Kanal abfragen

Handler: http://dbox/control/getonidsid

Parameter:
Rückgabe: Es wird die TSIDONIDSID des aktuellen Kanals zurückgegeben.

Diese Funktion sollte NICHT mehr verwendet werden und ist durch folgenden Aufruf ersetzt:
http://dbox/control/zapto

Rückgabeformat: TSIDONIDSID

Beispiel:

>>>http://dbox/control/getonidsid
44d00016dca

services.xml lesen

Handler: http://dbox/control/getservicesxml

Parameter:
Rückgabe: Es wird der Inhalt der Datei /var/tuxbox/config/zapit/services.xml zurückgegeben.

Beispiel:

>>>http://dbox/control/getservicesxml
<xml version="1.0" encoding="iso-8859-1"?>
<ZAPIT>
<cable>
<transponder transportID="00001" networkID="0">
<cable frequency="04020" symbolRate="06900" fec="0" polarity="0"/>
...

bouquets.xml auslesen

Handler: http://dbox/control/getbouquetsxml

Parameter:
Rückgabe: Es wird der Inhalt der Datei /var/tuxbox/config/zapit/bouquets.xml zurückgegeben.

Beispiel:

>>>http://dbox/control/getbouquetsxml

<?xml version="1.0" encoding="iso-8859-1"?>
<ZAPIT>
        <Bouquet name="beispielbouquet" hidden="0" locked="0">
                <channel serviceID="6d67" name="3sat" onid="0001"/>
...

Bouquetlist abfragen

Handler: http://dbox/control/getbouquets

Parameter:
Rückgabe: Es werden alle Bouquets zurückgeliefert

Beispiel:

>>>http://dbox/control/getbouquets
1 ARD
3 Premiere World
4 VisionProgramme
5 ZDFvision

Bouquet abfragen

Handler: http://dbox/control/getbouquet

Parameter: Bouquet Nr. und TV|RADIO
Rueckgabe: Es werden alle Sender des Bouquets zurückgeliefert

Rückgabeformat: [Nummer_des_Kanals] [channel_id] [Name_des_Senders]

Beispiel:

>>>http://dbox/control/getbouquet?bouquet=2&mode=TV
20 12ee3 RTL Television
21 85002e SAT.1
22 850382 ProSieben
23 12ef4 RTL2
24 12f1c VOX

Fenster in Neutrino

Handler: http://dbox/control/message

Parameter: popup=text oder nmsg=text
Rückgabe: ok

Character encoding: UTF-8, Leerzeichen werden mit %20 dargestellt

Neutrino öffnet ein Popup (popup) oder Message (nmsg) Window, in dem der Textteil des Parameter angezeigt wird. Ein Popup Fenster schließt sich nach einiger Zeit von selbst, während ein Message Window vom Benutzer geschlossen werden muss.

Beispiel:

>>>http://dbox/control/message?popup=Hello%20World
Popup Window auf dem Bildschirm "Hello World"

>>>http://dbox/control/message?nmsg=Hello%20Welt
Message Window auf dem Bildschirm "Hello World"

Timerd Interface

Handler: http://dbox/control/timer

Parameter:
Rückgabe: Zeigt die Liste aller Timer

Rückgabeformat: [eventID] [eventType] [eventRepeat] [repcount] [announceTime] [alarmTime] [stopTime] [data]

eventID ist der Timerplatz.
eventType ist die Art des Timers, die kann sein:

1 = SHUTDOWN
2 = NEXTPROGRAM
3 = ZAPTO
4 = STANDBY
5 = RECORD
6 = REMIND
7 = SLEEPTIMER
8 = EXEC_PLUGIN

siehe dazu auch: Neutrino Timer Doku

eventRepeat ist die Angabe der Timerwiederholung. Die kann sein:

0 = ONCE (Einmal)
1 = DAILY (Täglich)
2 = WEEKLY (Wöchentlich)
3 = BIWEEKLY (Alle 2 Wochen)
4 = FOURWEEKLY (Alle 4 Wochen)
5 = MONTHLY (Monatlich)
6 = BYEVENTDESCRIPTION (noch nicht implementiert)

Es gibt auch noch eine Möglichkeit WEEKDAYS also auch Wochentage festzulegen, an denen die Aufnahme stattfinden soll. Dies wird über einen Bitschlüssel angegeben, der Bit 9-15 als die Wochentage ansieht.
Das heißt:

0000000100000000 = 256    = Montag
0000001000000000 = 512    = Dinstag
0000010000000000 = 1024   = Mittwoch
0000100000000000 = 2048   = Donerstag
0001000000000000 = 4096   = Freitag
0010000000000000 = 8192   = Samstag
0100000000000000 = 16384  = Sontag

Demzufolge ist Montag+ Mittwoch+ Samstag

0000000100000000 =  256
0000010000000000 = 1024
0010000000000000 = 8192
----------------   ----
0010010100000000 = 9472

Siehe dazu auch: timerdtypes.h

repcount bestimmt die Anzahl der Timeraufrufe, nach der der Timer automatisch gelöscht wird. 0 bedeutet, dass es keine Beschränkung gibt. Bei eventRepeat=ONCE hat diese Einstellung keine Auswirkungen.
announceTime ist die Zeit, an der die Warnung vor dem Timer auf dem Bildschirm erscheint.
alarmTime ist die Zeit des Timer-Starts
stopTime ist die Stoppzeit für den Timer
data ist der Name des Senders.

Beispiel:

>>>http://dbox/control/timer
1 1 1 4 1034309516 1034309576 1034284376 555089

d.h. event 1, SHUTDOWN, DAILY, nach 4 Timerausführungen wird der Timer gelöscht, announcezeit, alarm/startzeit, stoppzeit, kanal/daten die zeiten sind time_t (Unix Zeitstempel)

Parameter: action,[id],<alarm|ad,amo,ay,ah,ami>,<stop|sd,smo,sy,sh,smi>,announce,type,rep,repcount,channel_id,msg,rs
Rückgabe: ok / error

announce, type, rep und repcount analog zu oben.

action kann entweder new oder modify sein. Bei modify muss noch ein Parameter id angegeben werden, um festzulegen, welcher Timer modifiziert wird.

Man kann entweder alarm und stop mit einer time_t Zeit verwenden oder die anderen Variablen mit den Daten füttern:

a/sd  = Tag
a/smo = Monat
a/sy  = Jahr
a/sh  = Stunde
a/smi = Minute

channel_id ist die Kennung des Senders (als Hexadezimalzahl ohne '0x'-Prefix).
msg ist die Message die bei REMIND gesendet wird

Ist der Parameter "rs" auf "1" gesetzt, so wird bei Aufnahmetimern, die in Neutrino konfigurierte "Aufnahmestart/stop-Korrektur" berücksichtigt.

siehe dazu auch: webapi.cpp

Rückgabeformat: ok / error

Beispiel:

>>>http://dbox/control/timer?action=new&alarm=1034309576&stop=1034284376&announce=1034309576&type=1&rep=1&channel_id=16dcb
ok

Shellscript ausführen

Handler: http://dbox/cgi-bin/exec oder http://dbox/control/exec

Parameter: <Scriptname> (ohne .sh!)
Rückgabe: Führt das Shellscript aus und liefert die Ausgabe an den Client zurück. 404 Bei Nicht-Auffinden.

Beispiel:

buli.sh gibt einen RSS-Feed zurück, der vom Newsticker angezeigt wird. In newsticker.list muss dann der Aufruf folgendermaßen aussehen:

http://dbox/cgi-bin/exec?buli

HINWEIS: Shellscript muss im richtigen Verzeichnis liegen. Ansonsten 404. (siehe oben unter Custom Plugins)

System-/Treiberfunktionen

Handler: http://dbox/control/system

Parameter: getAViAExtIec
Rückgabe: Status des Iec (optischer Ausgang)

0 = Iec deaktiviert
1 = Iec aktiviert

Beispiel:

http://dbox/control/system?getAViAExtIec
1

Parameter: setAViAExtIec=on
Rückgabe: ok

Aktiviert den Iec

Beispiel:

http://dbox/control/system?setAViAExtIec=on
ok

Parameter: setAViAExtIec=off
Rückgabe: ok

Deaktiviert den Iec

Beispiel:

http://dbox/control/system?setAViAExtIec=off
ok

Parameter: getAViAExtPlayBack
Rückgabe: Gibt zurück, in welchem Dekoder-Modus der Avia läuft

0 = PES
1 = SPTS

Beispiel:

http://dbox/control/system?getAViAExtPlayBack
1

Parameter: getAViAExtPlayBack=pes
Rückgabe: ok

Aktiviert den DualPES-Modus

Beispiel:

http://dbox/control/system?setAViAExtPlayBack=pes
ok

Parameter: getAViAExtPlayBack=spts
Rückgabe: ok

Aktiviert den SPTS-Modus

Beispiel:

http://dbox/control/system?setAViAExtPlayBack=spts
ok

Streaming von der Box zu VLC, MPlayer, etc.

Handler: http://dbox/control/build_live_url

Parameter: audio_no=<audio-track>
Parameter: vlc_link=true| Rückgabe: live-URL oder redirection Link auf vlc.m3u-Datei

Beispiel:

http://dbox/control/build_live_url
http://192.168.0.99:31339/0,0x0064,0x0065,0x0066

Das Beispiel zeigt die PMT-ID, Video-PID und Audio-PID für Das Erste in Hexadezimalzahlen.

mplayer kann mann z.B. so aufrufen:

mplayer http://192.168.0.99:31339/0,0x0064,0x0065,0x0066

Beispiel: Beim Aufruf von http://192.168.0.99/control/build_live_url?vlc_link=true wird ein REDIRECT zu der Datei tmp/vlc.m3u vom Server mit dem gleichen Inhalt wie oben ausgegeben:

 http://192.168.0.99:31339/0,0x0064,0x0065,0x0066 

Die Datei bzw. den Pfad kann man ebenfalls mit dem VLC-Player öffnen. Bei Radio Streams muss neben der Audio-ID auch die PMT-ID übermittelt werden da VLC die Wiedergabe sonst nicht startet.