10 Method Definitions (Methodendefinitionen)

10 Method Definitions (Methodendefinitionen)

Das method token (Methoden-Token) gibt die auf der durch den Request-URI identifizierten Ressource auszuführende Methode an. Die Methode unterscheidet Groß- und Kleinschreibung. Zukünftig können neue Methoden definiert werden. Methodennamen DÜRFEN NICHT mit dem Zeichen $ (dezimal 24) beginnen und MÜSSEN ein Token sein. Die Methoden sind in Tabelle 2 zusammengefasst.

method	direction	object	requirement
DESCRIBE	C->S	P,S	recommended
ANNOUNCE	C->S, S->C	P,S	optional
GET_PARAMETER	C->S, S->C	P,S	optional
OPTIONS	C->S, S->C	P,S	required (S->C: optional)
PAUSE	C->S	P,S	recommended
PLAY	C->S	P,S	required
RECORD	C->S	P,S	optional
REDIRECT	S->C	P,S	optional
SETUP	C->S	S	required
SET_PARAMETER	C->S, S->C	P,S	optional
TEARDOWN	C->S	P,S	required

Tabelle 2: Überblick über RTSP-Methoden, ihre Richtung und die Objekte (P: presentation (Präsentation), S: stream (Stream)), auf die sie wirken

Anmerkungen zu Tabelle 2: PAUSE ist empfohlen, aber nicht erforderlich, da ein voll funktionsfähiger Server ohne diese Methode gebaut werden kann, z. B. für Live-Feeds. Unterstützt ein Server eine bestimmte Methode nicht, MUSS er „501 Not Implemented“ zurückgeben, und ein Client SOLLTE diese Methode für diesen Server nicht erneut versuchen.

10.1 OPTIONS

Das Verhalten entspricht dem in [H9.2] beschriebenen. Eine OPTIONS-Anfrage kann jederzeit gestellt werden, z. B. wenn der Client eine nicht standardisierte Anfrage versuchen will. Sie beeinflusst den Serverzustand nicht.

Beispiel:

C->S: OPTIONS * RTSP/1.0 CSeq: 1 Require: implicit-play Proxy-Require: gzipped-messages

S->C: RTSP/1.0 200 OK CSeq: 1 Public: DESCRIBE, SETUP, TEARDOWN, PLAY, PAUSE

Beachten Sie, dass dies notwendigerweise fiktive Features sind (man hofft, kein wirklich nützliches Feature absichtlich zu übersehen, nur um ein starkes Beispiel in diesem Abschnitt zu haben).

10.2 DESCRIBE

Die Methode DESCRIBE ruft die Beschreibung einer presentation oder eines media object (Medienobjekts), identifiziert durch die Anfrage-URL, von einem Server ab. Sie kann den Accept-Header nutzen, um die vom Client verstandenen Beschreibungsformate anzugeben. Der Server antwortet mit einer Beschreibung der angeforderten Ressource. Das DESCRIBE-Anfrage-Antwort-Paar bildet die media initialization phase (Medieninitialisierungsphase) von RTSP.

Beispiel:

C->S: DESCRIBE rtsp://server.example.com/fizzle/foo RTSP/1.0 CSeq: 312 Accept: application/sdp, application/rtsl, application/mheg

S->C: RTSP/1.0 200 OK CSeq: 312 Date: 23 Jan 1997 15:35:06 GMT Content-Type: application/sdp Content-Length: 376

v=0 o=mhandley 2890844526 2890842807 IN IP4 126.16.64.4 s=SDP Seminar i=A Seminar on the session description protocol u=http://www.cs.ucl.ac.uk/staff/M.Handley/sdp.03.ps e=[email protected] (Mark Handley) c=IN IP4 224.2.17.12/127 t=2873397496 2873404696 a=recvonly m=audio 3456 RTP/AVP 0 m=video 2232 RTP/AVP 31 m=whiteboard 32416 UDP WB a=orient:portrait

Die DESCRIBE-Antwort MUSS alle Medieninitialisierungsinformationen für die beschriebenen Ressourcen enthalten. Erhält ein Medienclient eine presentation description (Präsentationsbeschreibung) aus einer anderen Quelle als DESCRIBE und enthält diese einen vollständigen Satz von Medieninitialisierungsparametern, SOLLTE der Client diese Parameter verwenden und nicht anschließend über RTSP eine Beschreibung für dasselbe Medium anfordern.

Außerdem SOLLEN Server die DESCRIBE-Antwort nicht als Mittel der media indirection (Medienumleitung) nutzen.

Klare Regeln sind nötig, damit Clients eindeutig wissen, wann Medieninitialisierung über DESCRIBE anzufordern ist und wann nicht. Indem die DESCRIBE-Antwort die gesamte Medieninitialisierung für die beschriebenen Streams erzwingen und die Nutzung von DESCRIBE zur Medienumleitung abraten, vermeiden wir Schleifenprobleme, die aus anderen Ansätzen resultieren könnten.

Medieninitialisierung ist für jedes RTSP-basierte System erforderlich, die RTSP-Spezifikation schreibt jedoch nicht vor, dass dies über DESCRIBE erfolgen muss. Ein RTSP-Client kann Initialisierungsinformationen auf drei Wegen erhalten:

• über die DESCRIBE-Methode von RTSP; * über ein anderes Protokoll (HTTP, E-Mail-Anhang usw.); * über die Befehlszeile oder die Standardeingabe (als Browser-Hilfsanwendung mit SDP-Datei oder anderem Medieninitialisierungsformat).

Im Interesse praktischer Interoperabilität wird dringend empfohlen, dass minimal servers (MinimalsServer) DESCRIBE unterstützen, und dringend empfohlen, dass minimal clients (MinimalsClients) die Fähigkeit unterstützen, als „helper application“ zu fungieren, die eine Medieninitialisierungsdatei von der Standardeingabe, der Befehlszeile und/oder anderen zum Client-Betriebssystem passenden Mitteln akzeptiert.

10.3 ANNOUNCE

Die Methode ANNOUNCE hat zwei Zwecke:

Vom Client zum Server sendet ANNOUNCE die Beschreibung einer Präsentation oder eines Medienobjekts, identifiziert durch die Anfrage-URL, an den Server. Vom Server zum Client sendet ANNOUNCE aktualisiert die session description (Sitzungsbeschreibung) in Echtzeit.

Wird einer Präsentation ein neuer Medienstrom hinzugefügt (z. B. während einer Live-Präsentation), sollte die gesamte Präsentationsbeschreibung erneut gesendet werden, nicht nur die zusätzlichen Teile, damit Komponenten gelöscht werden können.

Beispiel:

C->S: ANNOUNCE rtsp://server.example.com/fizzle/foo RTSP/1.0 CSeq: 312 Date: 23 Jan 1997 15:35:06 GMT Session: 47112344 Content-Type: application/sdp Content-Length: 332

v=0 o=mhandley 2890844526 2890845468 IN IP4 126.16.64.4

s=SDP Seminar i=A Seminar on the session description protocol u=http://www.cs.ucl.ac.uk/staff/M.Handley/sdp.03.ps e=[email protected] (Mark Handley) c=IN IP4 224.2.17.12/127 t=2873397496 2873404696 a=recvonly m=audio 3456 RTP/AVP 0 m=video 2232 RTP/AVP 31

S->C: RTSP/1.0 200 OK CSeq: 312

10.4 SETUP

Die SETUP-Anfrage für einen URI legt den transport mechanism (Transportmechanismus) für den gestreamten Medieninhalt fest. Ein Client kann SETUP für einen bereits abspielenden Stream ausgeben, um Transportparameter zu ändern, was ein Server DARF erlauben. Erlaubt er es nicht, MUSS er mit dem Fehler „455 Method Not Valid In This State“ antworten. Zugunsten zwischengeschalteter Firewalls muss ein Client die Transportparameter angeben, auch wenn er keinen Einfluss darauf hat, z. B. wenn der Server eine feste Multicast-Adresse bewirbt.

Da SETUP alle Transportinitialisierungsinformationen enthält, werden Firewalls und andere Zwischennetzwerkgeräte (die diese Information brauchen) von der mühsameren Aufgabe verschont, die DESCRIBE-Antwort zu parsen, die der Medieninitialisierung vorbehalten ist.

Der Transport-Header gibt die für die Datenübertragung vom Client akzeptablen Transportparameter an; die Antwort enthält die vom Server gewählten Parameter.

C->S: SETUP rtsp://example.com/foo/bar/baz.rm RTSP/1.0 CSeq: 302 Transport: RTP/AVP;unicast;client_port=4588-4589

S->C: RTSP/1.0 200 OK CSeq: 302 Date: 23 Jan 1997 15:35:06 GMT Session: 47112344 Transport: RTP/AVP;unicast; client_port=4588-4589;server_port=6256-6257

Der Server erzeugt session identifiers (Sitzungskennungen) als Antwort auf SETUP-Anfragen. Enthält eine SETUP-Anfrage eine Sitzungskennung, MUSS der Server diese Setup-Anfrage in die bestehende Sitzung einbinden oder den Fehler „459 Aggregate Operation Not Allowed“ zurückgeben (siehe Abschnitt 11.3.10).

10.5 PLAY

Die Methode PLAY weist den Server an, Daten über den in SETUP angegebenen Mechanismus zu senden. Ein Client DARF KEINE PLAY-Anfrage stellen, bevor ausstehende SETUP-Anfragen als erfolgreich bestätigt wurden.

PLAY positioniert die normal play time (normale Abspielzeit) auf den Anfang des angegebenen Bereichs und liefert Streamdaten bis zum Ende des Bereichs. PLAY-Anfragen können gepipelinet (in die Warteschlange gestellt) werden; ein Server MUSS PLAY-Anfragen in Reihenfolge ausführen. Eine PLAY-Anfrage, die eintrifft, während eine frühere PLAY noch aktiv ist, wird verzögert, bis die erste abgeschlossen ist.

Das ermöglicht präzises Schneiden.

Unabhängig davon, wie eng die beiden PLAY-Anfragen im folgenden Beispiel aufeinander folgen, wird der Server zuerst die Sekunden 10 bis 15, dann unmittelbar danach 20 bis 25 und schließlich 30 bis zum Ende abspielen.

C->S: PLAY rtsp://audio.example.com/audio RTSP/1.0 CSeq: 835 Session: 12345678 Range: npt=10-15

C->S: PLAY rtsp://audio.example.com/audio RTSP/1.0 CSeq: 836 Session: 12345678 Range: npt=20-25

C->S: PLAY rtsp://audio.example.com/audio RTSP/1.0 CSeq: 837 Session: 12345678 Range: npt=30-

Weitere Beispiele siehe PAUSE.

Eine PLAY-Anfrage ohne Range-Header ist zulässig. Sie startet die Wiedergabe vom Anfang, sofern der Stream nicht pausiert wurde. War der Stream per PAUSE pausiert, setzt die Lieferung am Pausenpunkt fort. Läuft der Stream bereits, bewirkt ein solches PLAY keine weitere Aktion und kann zur Prüfung der Serverlebendigkeit dienen.

Der Range-Header kann auch einen time-Parameter enthalten. Er gibt eine UTC-Zeit an, zu der die Wiedergabe starten soll. Wird die Nachricht nach der angegebenen Zeit empfangen, startet die Wiedergabe sofort. Der time-Parameter kann die Synchronisation von Streams aus verschiedenen Quellen unterstützen.

Bei einem on-demand stream antwortet der Server mit dem tatsächlich wiedergegebenen Bereich. Dieser kann vom angeforderten abweichen, wenn eine Ausrichtung auf gültige Rahmengrenzen für die Medienquelle nötig ist. Ist im Request kein Bereich angegeben, wird die aktuelle Position in der Antwort zurückgegeben. Die Einheit des Bereichs in der Antwort ist dieselbe wie im Request.

Nach Abspielen des gewünschten Bereichs wird die Präsentation automatisch pausiert, als wäre PAUSE gesendet worden.

Das folgende Beispiel spielt die gesamte Präsentation ab dem SMPTE time code 0:10:20 bis zum Ende des Clips. Die Wiedergabe soll am 23. Jan. 1997 um 15:36 beginnen.

C->S: PLAY rtsp://audio.example.com/twister.en RTSP/1.0 CSeq: 833 Session: 12345678 Range: smpte=0:10:20-;time=19970123T153600Z

S->C: RTSP/1.0 200 OK CSeq: 833 Date: 23 Jan 1997 15:35:06 GMT Range: smpte=0:10:22-;time=19970123T153600Z

Zur Wiedergabe einer Aufzeichnung einer Live-Präsentation kann die Verwendung von clock-Einheiten sinnvoll sein:

C->S: PLAY rtsp://audio.example.com/meeting.en RTSP/1.0 CSeq: 835 Session: 12345678 Range: clock=19961108T142300Z-19961108T143520Z

S->C: RTSP/1.0 200 OK CSeq: 835 Date: 23 Jan 1997 15:35:06 GMT

Ein Medienserver, der nur Wiedergabe unterstützt, MUSS das npt-Format unterstützen und DARF die Formate clock und smpte unterstützen.

10.6 PAUSE

Die PAUSE-Anfrage unterbricht die Streamlieferung vorübergehend. Benennt die Anfrage-URL einen Stream, werden nur Wiedergabe und Aufzeichnung dieses Streams angehalten. Bei Audio entspricht dies z. B. dem Stummschalten. Benennt die URL eine Präsentation oder eine Gruppe von Streams, wird die Lieferung aller derzeit aktiven Streams in der Präsentation oder Gruppe angehalten. Nach Fortsetzung MUSS die Synchronisation der Spuren erhalten bleiben. Serverressourcen bleiben erhalten, doch ein Server DARF die Sitzung schließen und Ressourcen freigeben, nachdem die Pause die im Session-Header der SETUP-Nachricht mit dem timeout-Parameter angegebene Dauer überschritten hat.

Beispiel:

C->S: PAUSE rtsp://example.com/fizzle/foo RTSP/1.0 CSeq: 834 Session: 12345678

S->C: RTSP/1.0 200 OK CSeq: 834 Date: 23 Jan 1997 15:35:06 GMT

PAUSE kann einen Range-Header enthalten, der angibt, wann Stream oder Präsentation angehalten werden soll. Diesen Punkt nennen wir „pause point“. Der Header muss genau einen Wert enthalten, keinen Zeitbereich. Die normal play time des Streams wird auf den Pausenpunkt gesetzt. Die Pause-Anfrage wird wirksam, sobald der Server erstmals den in einer der ausstehenden PLAY-Anfragen angegebenen Zeitpunkt erreicht. Liegt der Range außerhalb aller ausstehenden PLAY-Anfragen, wird „457 Invalid Range“ zurückgegeben. Beginnt eine media unit (Medieneinheit) (z. B. ein Audio- oder Videorahmen) genau am Pausenpunkt, wird sie weder abgespielt noch aufgezeichnet. Fehlt Range, wird die Lieferung bei Empfang sofort unterbrochen und der Pausenpunkt auf die aktuelle normal play time gesetzt.

PAUSE verwirft alle eingereihten PLAY-Anfragen. Der Pausenpunkt im Medienstrom MUSS jedoch erhalten bleiben. Ein nachfolgendes PLAY ohne Range setzt am Pausenpunkt fort.

Hat der Server z. B. ausstehende PLAY für 10–15 und 20–29 und erhält eine Pause für NPT 21, beginnt er den zweiten Bereich und stoppt bei NPT 21. Ist die Pause für NPT 12 und der Server spielt bei NPT 13 im ersten PLAY, stoppt er sofort. Ist die Pause für NPT 16, stoppt er nach dem ersten PLAY und verwirft den zweiten PLAY.

Ein weiteres Beispiel: Bei überlappenden Bereichen 10–15 und dann 13–20 wirkt PAUSE für NPT=14 während des ersten Bereichs; der zweite PLAY wird faktisch ignoriert, sofern PAUSE eintrifft, bevor der zweite überlappende Bereich beginnt. Unabhängig vom PAUSE-Zeitpunkt wird NPT auf 14 gesetzt.

Hat der Server bereits Daten über den im Range angegebenen Zeitpunkt hinaus gesendet, würde PLAY dennoch zu diesem Zeitpunkt fortsetzen, unter der Annahme, der Client habe spätere Daten verworfen. So bleiben Pause/Play-Zyklen lückenlos.

10.7 TEARDOWN

TEARDOWN beendet die Streamlieferung für den angegebenen URI und gibt zugehörige Ressourcen frei. Ist der URI der presentation URI dieser Präsentation, ist jede zugehörige RTSP-Sitzungskennung ungültig. Sofern nicht alle Transportparameter durch die Sitzungsbeschreibung festgelegt sind, muss vor erneuter Wiedergabe SETUP ausgegeben werden.

Beispiel: C->S: TEARDOWN rtsp://example.com/fizzle/foo RTSP/1.0 CSeq: 892 Session: 12345678 S->C: RTSP/1.0 200 OK CSeq: 892

10.8 GET_PARAMETER

GET_PARAMETER ruft den Wert eines parameter (Parameters) einer Präsentation oder eines Streams ab, angegeben durch den URI. Inhalt von Antwort und Response ist implementierungsabhängig. GET_PARAMETER ohne Entity-Body kann die Lebendigkeit von Client oder Server prüfen („ping“).

Beispiel:

S->C: GET_PARAMETER rtsp://example.com/fizzle/foo RTSP/1.0 CSeq: 431 Content-Type: text/parameters Session: 12345678 Content-Length: 15

packets_received jitter

C->S: RTSP/1.0 200 OK CSeq: 431 Content-Length: 46 Content-Type: text/parameters

packets_received: 10 jitter: 0.3838

„text/parameters“ ist nur ein Beispieltyp. Die Methode ist bewusst locker definiert; Antwortinhalte sollen nach weiteren Experimenten festgelegt werden.

10.9 SET_PARAMETER

Diese Methode fordert an, den Wert eines Parameters für eine Präsentation oder einen Stream am URI zu setzen.

Eine Anfrage SOLLTE nur einen Parameter enthalten, damit der Client den Grund eines Fehlschlags erkennen kann. Enthält sie mehrere, DARF der Server nur handeln, wenn alle erfolgreich gesetzt werden können. Ein Server MUSS wiederholtes Setzen auf denselben Wert erlauben, DARF aber Wertänderungen verbieten.

Hinweis: Transportparameter des Medienstreams DÜRFEN nur mit SETUP gesetzt werden.

Die Beschränkung auf SETUP dient den Firewalls.

Parameter sind fein aufgeteilt für aussagekräftigere Fehlerhinweise. Mehrere gleichzeitig zu setzen kann sinnvoll sein, wenn atomar gewünscht. Stellen Sie sich Gerätesteuerung vor, bei der der Client die Kamera nicht schwenken will, ohne gleichzeitig die richtige Neigung zu erreichen.

Beispiel:

C->S: SET_PARAMETER rtsp://example.com/fizzle/foo RTSP/1.0 CSeq: 421 Content-length: 20 Content-type: text/parameters

barparam: barstuff

S->C: RTSP/1.0 451 Invalid Parameter

CSeq: 421 Content-length: 10 Content-type: text/parameters

barparam

„text/parameters“ ist nur ein Beispiel. Die Methode ist bewusst locker definiert.

10.10 REDIRECT

Eine Redirect-Anfrage teilt dem Client mit, er müsse sich mit einem anderen Serverstandort verbinden. Sie enthält den Pflicht-Header Location; der Client soll Anfragen an diese URL richten. Optional Range, wann die Umleitung wirkt. Will der Client für diesen URI weiter Medien senden oder empfangen, MUSS er TEARDOWN für die aktuelle Sitzung und SETUP für die neue Sitzung am angegebenen Host ausgeben.

Dieses Beispiel leitet den Verkehr für diesen URI zur angegebenen Abspielzeit zum neuen Server um:

S->C: REDIRECT rtsp://example.com/fizzle/foo RTSP/1.0 CSeq: 732 Location: rtsp://bigserver.com:8001 Range: clock=19960213T143205Z-

10.11 RECORD

Diese Methode startet die Aufzeichnung eines Medienbereichs gemäß der Präsentationsbeschreibung. Der Zeitstempel gibt Start- und Endzeit (UTC) an. Ohne Zeitbereich werden die in der Präsentationsbeschreibung angegebenen Start- oder Endzeiten verwendet. Hat die Sitzung bereits begonnen, beginnt die Aufzeichnung sofort.

Der Server entscheidet, ob unter dem request-URI oder einem anderen URI gespeichert wird. Verwendet er nicht den request-URI, SOLLTE die Antwort 201 (Created) sein mit einer Entität, die den Status beschreibt und auf die neue Ressource verweist, sowie Location-Header.

Ein Medienserver, der Aufzeichnung von Live-Präsentationen unterstützt, MUSS das clock-Bereichsformat unterstützen; smpte ist hier nicht sinnvoll.

In diesem Beispiel war der Medienserver zuvor zur angegebenen Konferenz eingeladen worden.

C->S: RECORD rtsp://example.com/meeting/audio.en RTSP/1.0 CSeq: 954 Session: 12345678 Conference: 128.16.64.19/32492374

10.12 Embedded (Interleaved) Binary Data (Eingebettete (verschachtelte) Binärdaten)

Bestimmte Firewall-Designs und Umstände können einen Server zwingen, RTSP-Methoden und Streamdaten zu verschachteln. Das sollte vermieden werden, sofern nicht nötig, da es Client und Server erschwert und Overhead erzeugt. Verschachtelte Binärdaten SOLLEN nur verwendet werden, wenn RTSP über TCP getragen wird.

Streamdaten wie RTP-Pakete werden durch ein ASCII-Dollarzeichen (hex 24), gefolgt von einem ein Byte langen channel identifier (Kanalbezeichner), gefolgt von der Länge der gekapselten Binärdaten als binäre Zwei-Byte-Ganzzahl in Netzwerkbyte-Reihenfolge gekapselt. Die Streamdaten folgen unmittelbar ohne CRLF, jedoch mit den Headern höherer Schicht. Jeder $-Block enthält genau eine upper-layer protocol data unit (PDU höherer Schicht), z. B. ein RTP-Paket.

Der Kanalbezeichner ist im Transport-Header im Parameter interleaved definiert (Abschnitt 12.39).

Ist die Transportwahl RTP, verschachtelt der Server auch RTCP-Nachrichten über die TCP-Verbindung. Standardmäßig gehen RTCP-Pakete auf dem ersten verfügbaren Kanal oberhalb des RTP-Kanals. Der Client DARF RTCP explizit auf einem anderen Kanal anfordern, indem er im interleaved-Parameter des Transport-Headers zwei Kanäle angibt (Abschnitt 12.39).

RTCP ist für die Synchronisation nötig, wenn mehrere Streams so verschachtelt sind. Außerdem bietet es einen praktischen Weg, RTP/RTCP durch die TCP-Steuerverbindung zu tunneln und bei Bedarf auf UDP zu übertragen.

C->S: SETUP rtsp://foo.com/bar.file RTSP/1.0 CSeq: 2 Transport: RTP/AVP/TCP;interleaved=0-1

S->C: RTSP/1.0 200 OK CSeq: 2 Date: 05 Jun 1997 18:57:18 GMT Transport: RTP/AVP/TCP;interleaved=0-1

Session: 12345678

C->S: PLAY rtsp://foo.com/bar.file RTSP/1.0 CSeq: 3 Session: 12345678

S->C: RTSP/1.0 200 OK CSeq: 3 Session: 12345678 Date: 05 Jun 1997 18:59:15 GMT RTP-Info: url=rtsp://foo.com/bar.file; seq=232433;rtptime=972948234

S->C: $\000{2 byte length}{"length" bytes data, w/RTP header} S->C: $\000{2 byte length}{"length" bytes data, w/RTP header} S->C: $\001{2 byte length}{"length" bytes RTCP packet}