10 Method Definitions (Definizioni dei metodi)

10 Method Definitions (Definizioni dei metodi)

Il method token (token di metodo) indica il metodo da eseguire sulla risorsa identificata dal Request-URI. Il metodo distingue maiuscole e minuscole. In futuro si possono definire nuovi metodi. I nomi di metodo NON DEVONO iniziare con il carattere $ (decimale 24) e DEVONO essere un token. I metodi sono riassunti nella tabella 2.

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

Tabella 2: Panoramica dei metodi RTSP, della loro direzione e degli oggetti su cui agiscono (P: presentation (presentazione), S: stream (flusso))

Note sulla tabella 2: PAUSE è raccomandato ma non richiesto, perché si può costruire un server pienamente funzionale senza supportarlo, ad es. per feed live. Se un server non supporta un metodo particolare, DEVE restituire «501 Not Implemented» e un client NON DOVREBBE riprovare tale metodo per quel server.

10.1 OPTIONS

Il comportamento è equivalente a quello descritto in [H9.2]. Una richiesta OPTIONS può essere emessa in qualsiasi momento, ad es. se il client sta per tentare una richiesta non standard. Non influenza lo stato del server.

Esempio:

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

Si noti che queste sono necessariamente funzionalità fittizie (si spera di non trascurare deliberatamente una funzione veramente utile solo per avere un esempio forte in questa sezione).

10.2 DESCRIBE

Il metodo DESCRIBE recupera dal server la descrizione di una presentation o di un media object (oggetto multimediale) identificato dall'URL della richiesta. Può usare l'header Accept per specificare i formati di descrizione che il client comprende. Il server risponde con una descrizione della risorsa richiesta. La coppia richiesta-risposta DESCRIBE costituisce la fase di media initialization (inizializzazione dei media) di RTSP.

Esempio:

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

La risposta DESCRIBE DEVE contenere tutte le informazioni di inizializzazione dei media per le risorse che descrive. Se un client multimediale ottiene una presentation description (descrizione della presentazione) da una fonte diversa da DESCRIBE e tale descrizione contiene un insieme completo di parametri di inizializzazione, il client DOVREBBE usare tali parametri e non richiedere poi una descrizione per lo stesso media via RTSP.

Inoltre, i server NON DOVREBBERO usare la risposta DESCRIBE come mezzo di media indirection (indirezione dei media).

Servono regole chiare affinché i client sappiano senza ambiguità quando richiedere l'inizializzazione via DESCRIBE e quando no. Forzando la risposta DESCRIBE a contenere tutta l'inizializzazione per l'insieme di flussi descritti e scoraggiando l'uso di DESCRIBE per indirezione, si evitano problemi di ciclo che potrebbero derivare da altri approcci.

L'inizializzazione dei media è richiesta per ogni sistema basato su RTSP, ma la specifica RTSP non impone che avvenga tramite DESCRIBE. Un client RTSP può ricevere le informazioni di inizializzazione in tre modi:

• tramite il metodo DESCRIBE di RTSP; * tramite un altro protocollo (HTTP, allegato e-mail, ecc.); * tramite riga di comando o standard input (come applicazione helper del browser avviata con file SDP o altro formato di inizializzazione).

Per l'interoperabilità pratica, si raccomanda fortemente che i minimal servers (server minimi) supportino DESCRIBE, e che i minimal clients (client minimi) supportino l'essere «helper application» che accetta un file di inizializzazione da standard input, riga di comando e/o altri mezzi appropriati all'ambiente del client.

10.3 ANNOUNCE

Il metodo ANNOUNCE ha due scopi:

Dal client al server, ANNOUNCE pubblica sul server la descrizione di una presentazione o di un oggetto multimediale identificato dall'URL della richiesta. Dal server al client, ANNOUNCE aggiorna la session description (descrizione di sessione) in tempo reale.

Se viene aggiunto un nuovo flusso multimediale a una presentazione (ad es. durante una presentazione live), va inviata di nuovo l'intera descrizione della presentazione, non solo i componenti aggiuntivi, così da poter eliminare componenti.

Esempio:

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

La richiesta SETUP per un URI specifica il transport mechanism (meccanismo di trasporto) per i media in streaming. Un client può emettere SETUP per un flusso già in riproduzione per cambiare i parametri di trasporto, cosa che un server PUÒ consentire. Se non lo consente, DEVE rispondere con l'errore «455 Method Not Valid In This State». A beneficio di eventuali firewall intermedi, un client deve indicare i parametri di trasporto anche se non può influenzarli, ad es. quando il server annuncia un indirizzo multicast fisso.

Poiché SETUP include tutte le informazioni di inizializzazione del trasporto, firewall e altri dispositivi di rete intermedi (che ne hanno bisogno) sono risparmiati dal compito più oneroso di analizzare la risposta DESCRIBE, riservata all'inizializzazione dei media.

L'header Transport specifica i parametri di trasporto accettabili al client per la trasmissione dati; la risposta conterrà i parametri scelti dal server.

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

Il server genera session identifiers (identificatori di sessione) in risposta alle richieste SETUP. Se una richiesta SETUP include un identificatore di sessione, il server DEVE aggregare tale setup nella sessione esistente oppure restituire l'errore «459 Aggregate Operation Not Allowed» (vedere la sezione 11.3.10).

10.5 PLAY

Il metodo PLAY dice al server di iniziare a inviare dati tramite il meccanismo specificato in SETUP. Un client NON DEVE emettere PLAY finché le richieste SETUP pendenti non sono state confermate come riuscite.

PLAY posiziona la normal play time (tempo di riproduzione normale) all'inizio dell'intervallo indicato e consegna i dati del flusso fino alla fine dell'intervallo. Le richieste PLAY possono essere messe in pipeline (in coda); un server DEVE mettere in coda le PLAY da eseguire in ordine. Una PLAY che arriva mentre una PLAY precedente è ancora attiva è ritardata fino al completamento della prima.

Ciò consente un montaggio preciso.

Ad esempio, per quanto ravvicinate arrivino le due PLAY sotto, il server riprodurrà prima i secondi 10–15, poi subito dopo 20–25, infine 30 fino alla fine.

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-

Vedere PAUSE per ulteriori esempi.

Una PLAY senza header Range è lecita. Avvia la riproduzione dall'inizio salvo che il flusso sia stato messo in pausa. Se un flusso è stato messo in pausa con PAUSE, la consegna riprende dal punto di pausa. Se un flusso è in riproduzione, tale PLAY non causa ulteriori azioni e può servire a verificare che il server sia vivo.

L'header Range può anche contenere un parametro time, che specifica un istante UTC in cui iniziare la riproduzione. Se il messaggio arriva dopo l'ora indicata, la riproduzione inizia subito. Il parametro time può aiutare a sincronizzare flussi da fonti diverse.

Per un flusso on-demand, il server risponde con l'intervallo effettivamente riprodotto. Può differire da quello richiesto se è necessario allineare l'intervallo ai confini di frame validi per la sorgente. Se nella richiesta non c'è intervallo, nella risposta si restituisce la posizione corrente. L'unità dell'intervallo nella risposta è la stessa della richiesta.

Dopo aver riprodotto l'intervallo desiderato, la presentazione si mette in pausa automaticamente, come se fosse stata emessa PAUSE.

L'esempio seguente riproduce l'intera presentazione a partire dal SMPTE time code 0:10:20 fino alla fine della clip. La riproduzione deve iniziare il 23 gen 1997 alle 15:36.

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

Per riprodurre la registrazione di una presentazione live può essere utile usare unità clock:

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

Un server multimediale che supporta solo la riproduzione DEVE supportare il formato npt e PUÒ supportare i formati clock e smpte.

10.6 PAUSE

La richiesta PAUSE interrompe temporaneamente la consegna del flusso. Se l'URL della richiesta nomina un flusso, si fermano solo riproduzione e registrazione di quel flusso. Per l'audio equivale ad es. al muto. Se l'URL nomina una presentazione o un gruppo di flussi, si ferma la consegna di tutti i flussi attualmente attivi nella presentazione o nel gruppo. Dopo la ripresa, la sincronizzazione delle tracce DEVE essere mantenuta. Le risorse del server restano, ma un server PUÒ chiudere la sessione e liberare risorse dopo una pausa della durata indicata dal parametro timeout dell'header Session nel messaggio SETUP.

Esempio:

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 può contenere un Range che specifica quando fermare flusso o presentazione. Chiamiamo questo punto «pause point». L'header deve contenere esattamente un valore, non un intervallo temporale. La normal play time del flusso è impostata al punto di pausa. La richiesta di pausa diventa efficace la prima volta che il server incontra l'istante specificato in una delle PLAY in sospeso. Se Range indica un tempo fuori da ogni PLAY in sospeso, si restituisce «457 Invalid Range». Se una media unit (unità multimediale) (ad es. un frame audio o video) inizia la presentazione esattamente al punto di pausa, non viene riprodotta né registrata. Se manca Range, la consegna si interrompe immediatamente alla ricezione e il punto di pausa è la normal play time corrente.

PAUSE scarta tutte le PLAY in coda. Tuttavia il punto di pausa nel flusso multimediale DEVE essere mantenuto. Una PLAY successiva senza Range riprende dal punto di pausa.

Ad esempio, se il server ha PLAY in sospeso per 10–15 e 20–29 e riceve una pausa per NPT 21, inizierà il secondo intervallo e si fermerà a NPT 21. Se la pausa è per NPT 12 e il server sta riproducendo a NPT 13 per la prima PLAY, si ferma subito. Se la pausa è per NPT 16, si ferma dopo la prima PLAY e scarta la seconda.

Altro esempio: con intervalli sovrapposti 10–15 e poi 13–20, una PAUSE per NPT=14 ha effetto mentre il server riproduce il primo intervallo, con la seconda PLAY di fatto ignorata, assumendo che PAUSE arrivi prima che inizi il secondo intervallo sovrapposto. Indipendentemente dall'arrivo di PAUSE, l'NPT è impostato a 14.

Se il server ha già inviato dati oltre l'istante indicato in Range, una PLAY riprenderebbe comunque da quell'istante, assumendo che il client abbia scartato i dati successivi. Ciò garantisce cicli continui pausa/riproduzione senza lacune.

10.7 TEARDOWN

TEARDOWN ferma la consegna del flusso per l'URI dato e libera le risorse associate. Se l'URI è il presentation URI di questa presentazione, qualsiasi identificatore di sessione RTSP associato non è più valido. A meno che tutti i parametri di trasporto siano definiti dalla descrizione di sessione, occorre emettere SETUP prima di poter riprodurre di nuovo la sessione.

Esempio: 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 recupera il valore di un parameter (parametro) di una presentazione o di un flusso indicato nell'URI. Il contenuto della risposta è lasciato all'implementazione. GET_PARAMETER senza entity body può servire a verificare la vitalità di client o server («ping»).

Esempio:

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

La sezione «text/parameters» è solo un tipo di esempio. Il metodo è volutamente definito in modo lasco; i contenuti di risposta saranno definiti dopo ulteriore sperimentazione.

10.9 SET_PARAMETER

Questo metodo richiede di impostare il valore di un parametro per una presentazione o un flusso indicato dall'URI.

Una richiesta DOVREBBE contenere un solo parametro, così il client può capire perché una richiesta è fallita. Se ne contiene diversi, il server DEVE agire solo se tutti possono essere impostati con successo. Un server DEVE consentire di ripetere l'impostazione allo stesso valore, ma PUÒ vietare di cambiare i valori.

Nota: i parametri di trasporto del flusso multimediale DEVONO essere impostati solo con il comando SETUP.

Limitare i parametri di trasporto a SETUP è a beneficio dei firewall.

I parametri sono suddivisi in modo fine per indicazioni di errore più significative. Può però aver senso consentire l'impostazione di più parametri se si desidera un'impostazione atomica. Immaginate il controllo dispositivi in cui il client non vuole far panning alla telecamera a meno che non possa inclinare contemporaneamente all'angolo giusto.

Esempio:

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» è solo un esempio. Il metodo è volutamente lasco.

10.10 REDIRECT

Una richiesta redirect informa il client che deve connettersi a un'altra posizione del server. Contiene l'header obbligatorio Location, che indica che il client dovrebbe inviare richieste a quell'URL. Può contenere Range, che indica quando la redirezione ha effetto. Se il client vuole continuare a inviare o ricevere media per questo URI, DEVE emettere TEARDOWN per la sessione corrente e SETUP per la nuova sessione sull'host indicato.

Questo esempio reindirizza il traffico per questo URI al nuovo server all'istante di riproduzione indicato:

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

10.11 RECORD

Questo metodo avvia la registrazione di un intervallo di dati multimediali secondo la descrizione della presentazione. Il timestamp riflette orario di inizio e fine (UTC). Se non è dato un intervallo temporale, usare l'orario di inizio o fine fornito nella descrizione. Se la sessione è già iniziata, iniziare subito la registrazione.

Il server decide se memorizzare sotto il request-URI o un altro URI. Se non usa il request-URI, la risposta DOVREBBE essere 201 (Created) e contenere un'entità che descrive lo stato della richiesta e riferisce la nuova risorsa, e un header Location.

Un server multimediale che supporta la registrazione di presentazioni live DEVE supportare il formato di intervallo clock; il formato smpte non ha senso qui.

In questo esempio il server multimedia era stato precedentemente invitato alla conferenza indicata.

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 (Dati binari incorporati (interlacciati))

Certi progetti di firewall e altre circostanze possono costringere un server a interlacciare metodi RTSP e dati di flusso. L'interlacciamento va in genere evitato salvo necessità, perché complica client e server e impone overhead. I dati binari interlacciati DOVREBBERO essere usati solo se RTSP è trasportato su TCP.

Dati di flusso come pacchetti RTP sono incapsulati da un segno dollaro ASCII (24 esadecimale), seguito da un channel identifier (identificatore di canale) di un byte, seguito dalla lunghezza dei dati binari incapsulati come intero binario di due byte in ordine di byte di rete. I dati di flusso seguono subito dopo, senza CRLF, ma con gli header del protocollo di livello superiore. Ogni blocco $ contiene esattamente una upper-layer protocol data unit (unità dati di protocollo di livello superiore), ad es. un pacchetto RTP.

L'identificatore di canale è definito nell'header Transport con il parametro interleaved (sezione 12.39).

Quando la scelta di trasporto è RTP, anche i messaggi RTCP sono interlacciati dal server sulla connessione TCP. Per impostazione predefinita, i pacchetti RTCP sono inviati sul primo canale disponibile superiore al canale RTP. Il client PUÒ richiedere esplicitamente RTCP su un altro canale, specificando due canali nel parametro interleaved dell'header Transport (sezione 12.39).

RTCP è necessario per la sincronizzazione quando due o più flussi sono interlacciati in questo modo. Fornisce anche un modo comodo per tunnelare pacchetti RTP/RTCP sulla connessione di controllo TCP quando richiesto dalla configurazione di rete e trasferirli su UDP quando possibile.

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}