10 Method Definitions (Définitions des méthodes)

Le method token (jeton de méthode) indique la méthode à exécuter sur la ressource identifiée par le Request-URI. La méthode est sensible à la casse. De nouvelles méthodes peuvent être définies ultérieurement. Les noms de méthode NE DOIVENT PAS commencer par le caractère $ (décimal 24) et DOIVENT être un token. Les méthodes sont résumées dans le tableau 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

Tableau 2 : Aperçu des méthodes RTSP, de leur direction et des objets sur lesquels elles agissent (P : presentation (présentation), S : stream (flux))

Notes sur le tableau 2 : PAUSE est recommandée mais pas requise, car un serveur pleinement fonctionnel peut être construit sans la prendre en charge, par exemple pour des flux en direct. Si un serveur ne prend pas en charge une méthode particulière, il DOIT renvoyer « 501 Not Implemented » et un client NE DEVRAIT PAS réessayer cette méthode pour ce serveur.

10.1 OPTIONS

Le comportement est équivalent à celui décrit dans [H9.2]. Une requête OPTIONS peut être émise à tout moment, par ex. si le client s'apprête à tenter une requête non standard. Elle n'influence pas l'état du serveur.

Exemple :

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

Notez qu'il s'agit nécessairement de fonctionnalités fictives (on espère ne pas négliger délibérément une fonctionnalité réellement utile pour avoir un exemple fort dans cette section).

10.2 DESCRIBE

La méthode DESCRIBE récupère la description d'une presentation ou d'un media object (objet média) identifié par l'URL de requête auprès d'un serveur. Elle peut utiliser l'en-tête Accept pour préciser les formats de description que le client comprend. Le serveur répond par une description de la ressource demandée. La paire requête-réponse DESCRIBE constitue la phase de media initialization (initialisation média) de RTSP.

Exemple :

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 réponse DESCRIBE DOIT contenir toutes les informations d'initialisation média pour la ou les ressources qu'elle décrit. Si un client média obtient une presentation description (description de présentation) d'une autre source que DESCRIBE et que cette description contient un jeu complet de paramètres d'initialisation média, le client DEVRAIT utiliser ces paramètres et ne pas demander ensuite une description pour le même média via RTSP.

De plus, les serveurs NE DEVRAIENT PAS utiliser la réponse DESCRIBE comme moyen d'indirection média.

Des règles claires doivent être établies pour que les clients sachent sans ambiguïté quand demander l'initialisation média via DESCRIBE et quand ne pas le faire. En imposant que la réponse DESCRIBE contienne toute l'initialisation média pour l'ensemble des flux qu'elle décrit, et en décourageant l'usage de DESCRIBE pour l'indirection média, on évite des problèmes de boucle pouvant résulter d'autres approches.

L'initialisation média est requise pour tout système basé sur RTSP, mais la spécification RTSP n'impose pas qu'elle se fasse via DESCRIBE. Un client RTSP peut recevoir les informations d'initialisation de trois façons :

via la méthode DESCRIBE de RTSP ; * via un autre protocole (HTTP, pièce jointe e-mail, etc.) ; * via la ligne de commande ou l'entrée standard (agissant comme application d'aide de navigateur lancée avec un fichier SDP ou un autre format d'initialisation média).

Pour l'interopérabilité pratique, il est fortement recommandé que les minimal servers (serveurs minimaux) prennent en charge DESCRIBE, et fortement recommandé que les minimal clients (clients minimaux) prennent en charge le fait d'agir comme « helper application » acceptant un fichier d'initialisation média depuis l'entrée standard, la ligne de commande et/ou d'autres moyens adaptés à l'environnement du client.

10.3 ANNOUNCE

La méthode ANNOUNCE a deux rôles :

Lorsqu'elle est envoyée du client au serveur, ANNOUNCE publie la description d'une présentation ou d'un objet média identifié par l'URL de requête sur le serveur. Lorsqu'elle est envoyée du serveur au client, ANNOUNCE met à jour la session description (description de session) en temps réel.

Si un nouveau flux média est ajouté à une présentation (par ex. pendant une présentation en direct), l'intégralité de la description de présentation doit être renvoyée, et non seulement les composants supplémentaires, afin de pouvoir supprimer des composants.

Exemple :

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 requête SETUP pour un URI spécifie le transport mechanism (mécanisme de transport) à utiliser pour le média en flux. Un client peut émettre un SETUP pour un flux déjà en lecture pour modifier les paramètres de transport, ce qu'un serveur PEUT autoriser. S'il ne l'autorise pas, il DOIT répondre par l'erreur « 455 Method Not Valid In This State ». Pour tout pare-feu intermédiaire, un client doit indiquer les paramètres de transport même s'il n'a pas d'influence sur ceux-ci, par ex. lorsque le serveur annonce une adresse de multidiffusion fixe.

Comme SETUP inclut toute l'information d'initialisation du transport, les pare-feu et autres dispositifs réseau intermédiaires (qui en ont besoin) sont épargnés de la tâche plus ardue d'analyser la réponse DESCRIBE, réservée à l'initialisation média.

L'en-tête Transport précise les paramètres de transport acceptables pour le client pour la transmission des données ; la réponse contiendra les paramètres choisis par le serveur.

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

Le serveur génère des session identifiers (identifiants de session) en réponse aux requêtes SETUP. Si une requête SETUP inclut un identifiant de session, le serveur DOIT regrouper cette requête setup dans la session existante ou renvoyer l'erreur « 459 Aggregate Operation Not Allowed » (voir la section 11.3.10).

10.5 PLAY

La méthode PLAY indique au serveur de commencer à envoyer des données via le mécanisme spécifié dans SETUP. Un client NE DOIT PAS émettre PLAY tant que les requêtes SETUP en attente n'ont pas été acquittées comme réussies.

PLAY positionne le normal play time (temps de lecture normal) au début de la plage indiquée et livre les données du flux jusqu'à la fin de la plage. Les requêtes PLAY peuvent être mises en pipeline (file d'attente) ; un serveur DOIT mettre en file les PLAY pour les exécuter dans l'ordre. Ainsi, un PLAY arrivant pendant qu'un PLAY précédent est encore actif est retardé jusqu'à la fin du premier.

Cela permet un montage précis.

Par exemple, quelle que soit la proximité des deux PLAY ci-dessous, le serveur jouera d'abord les secondes 10 à 15, puis immédiatement après 20 à 25, enfin 30 jusqu'à la fin.

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-

Voir la description de PAUSE pour d'autres exemples.

Un PLAY sans en-tête Range est légal. Il démarre la lecture depuis le début sauf si le flux a été mis en pause. Si un flux a été mis en pause via PAUSE, la livraison reprend au point de pause. Si un flux est en lecture, un tel PLAY n'entraîne pas d'action supplémentaire et peut servir à tester la vivacité du serveur.

L'en-tête Range peut aussi contenir un paramètre time. Il indique une heure UTC à laquelle la lecture doit commencer. Si le message est reçu après l'heure indiquée, la lecture démarre immédiatement. Le paramètre time peut aider à synchroniser des flux provenant de sources différentes.

Pour un flux à la demande, le serveur répond avec la plage réellement lue. Elle peut différer de la plage demandée si l'alignement sur des frontières de trames valides est requis par la source. Si aucune plage n'est indiquée dans la requête, la position courante est renvoyée dans la réponse. L'unité de plage dans la réponse est la même que dans la requête.

Après lecture de la plage souhaitée, la présentation est automatiquement mise en pause, comme si une requête PAUSE avait été émise.

L'exemple suivant lit toute la présentation à partir du SMPTE time code 0:10:20 jusqu'à la fin du clip. La lecture doit commencer le 23 janv. 1997 à 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

Pour rejouer l'enregistrement d'une présentation en direct, il peut être souhaitable d'utiliser des unités 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 serveur média ne prenant en charge que la lecture DOIT prendre en charge le format npt et PEUT prendre en charge les formats clock et smpte.

10.6 PAUSE

La requête PAUSE interrompt temporairement la livraison du flux. Si l'URL de requête nomme un flux, seuls la lecture et l'enregistrement de ce flux sont arrêtés. Pour l'audio, cela équivaut à une mise en sourdine. Si l'URL nomme une présentation ou un groupe de flux, la livraison de tous les flux actifs de la présentation ou du groupe est arrêtée. Après reprise, la synchronisation des pistes DOIT être maintenue. Les ressources serveur sont conservées, mais un serveur PEUT fermer la session et libérer les ressources après une pause d'une durée indiquée par le paramètre timeout de l'en-tête Session dans le message SETUP.

Exemple :

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 peut contenir un Range indiquant quand le flux ou la présentation doit s'arrêter. Nous appelons ce point le « pause point ». L'en-tête doit contenir exactement une valeur, pas une plage temporelle. Le normal play time du flux est fixé au point de pause. La requête de pause devient effective la première fois que le serveur atteint l'instant indiqué dans l'un des PLAY en attente. Si Range indique un instant hors de tout PLAY en attente, l'erreur « 457 Invalid Range » est renvoyée. Si une unité média (trame audio ou vidéo) commence exactement au point de pause, elle n'est ni lue ni enregistrée. Sans Range, la livraison est interrompue dès réception et le point de pause est le normal play time courant.

PAUSE annule tous les PLAY en file. Toutefois, le point de pause dans le flux média DOIT être conservé. Un PLAY ultérieur sans Range reprend au point de pause.

Par exemple, si le serveur a des PLAY pour 10–15 et 20–29 en attente puis reçoit une pause pour NPT 21, il commencera la deuxième plage et s'arrêtera à NPT 21. Si la pause est pour NPT 12 et que le serveur lit à NPT 13 pour le premier PLAY, il s'arrête immédiatement. Si la pause est pour NPT 16, il s'arrête après le premier PLAY et annule le second.

Autre exemple : avec des plages 10–15 puis 13–20 (chevauchement), une PAUSE pour NPT=14 prend effet pendant la première plage, le second PLAY étant en pratique ignoré si PAUSE arrive avant le début de la seconde plage chevauchante. Quel que soit l'arrivée de PAUSE, le NPT est fixé à 14.

Si le serveur a déjà envoyé des données au-delà de l'instant du Range, un PLAY reprendrait quand même à cet instant, en supposant que le client a rejeté les données ultérieures. Cela assure des cycles pause/lecture continus sans trou.

10.7 TEARDOWN

TEARDOWN arrête la livraison du flux pour l'URI donné et libère les ressources associées. Si l'URI est l'URI de présentation de cette présentation, tout identifiant de session RTSP associé n'est plus valide. Sauf si tous les paramètres de transport sont définis par la description de session, une requête SETUP doit être émise avant de pouvoir rejouer la session.

Exemple : 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 récupère la valeur d'un parameter (paramètre) d'une présentation ou d'un flux indiqué par l'URI. Le contenu de la réponse est laissé à l'implémentation. GET_PARAMETER sans corps d'entité peut servir de test de vivacité (« ping »).

Exemple :

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 section « text/parameters » n'est qu'un type d'exemple. La méthode est volontairement peu contraignante ; le contenu des réponses sera précisé après expérimentation.

10.9 SET_PARAMETER

Cette méthode demande de fixer la valeur d'un paramètre pour une présentation ou un flux identifié par l'URI.

Une requête NE DEVRAIT contenir qu'un seul paramètre pour que le client sache pourquoi une requête a échoué. Si plusieurs paramètres sont présents, le serveur NE DOIT agir que si tous peuvent être fixés avec succès. Un serveur DOIT permettre de répéter la même valeur, mais PEUT interdire de changer les valeurs.

Note : les paramètres de transport du flux média NE DOIVENT être fixés qu'avec la commande SETUP.

Limiter les paramètres de transport à SETUP profite aux pare-feu.

Les paramètres sont découpés finement pour des indications d'erreur plus utiles. Il peut toutefois être pertinent d'en fixer plusieurs pour un réglage atomique. Imaginez le contrôle d'appareil où le client ne veut pas faire pivoter la caméra sans pouvoir incliner au bon angle simultanément.

Exemple :

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 » n'est qu'un exemple. La méthode est volontairement peu contraignante pour préciser le contenu après expérimentation.

10.10 REDIRECT

Une requête redirect informe le client qu'il doit se connecter à un autre emplacement serveur. Elle contient l'en-tête obligatoire Location indiquant que le client doit émettre des requêtes vers cette URL. Elle peut contenir Range indiquant quand la redirection prend effet. Si le client veut continuer à envoyer ou recevoir du média pour cet URI, il DOIT émettre TEARDOWN pour la session courante et SETUP pour la nouvelle session sur l'hôte désigné.

Cet exemple redirige le trafic pour cet URI vers le nouveau serveur à l'instant de lecture indiqué :

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

10.11 RECORD

Cette méthode démarre l'enregistrement d'une plage de données média selon la description de présentation. L'horodatage reflète début et fin (UTC). Sans plage temporelle, utiliser les heures de début ou de fin de la description. Si la session a déjà commencé, commencer l'enregistrement immédiatement.

Le serveur décide de stocker sous le request-URI ou un autre URI. S'il n'utilise pas le request-URI, la réponse DEVRAIT être 201 (Created) avec une entité décrivant l'état et référençant la nouvelle ressource, et un en-tête Location.

Un serveur média prenant en charge l'enregistrement de présentations en direct DOIT prendre en charge le format de plage clock ; le format smpte n'a pas de sens.

Dans cet exemple, le serveur média avait déjà été invité à la conférence indiquée.

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 (Données binaires embarquées (entrelacées))

Certains pare-feu ou circonstances peuvent forcer un serveur à entrelacer les méthodes RTSP et les données de flux. Cet entrelacement doit en général être évité sauf nécessité, car il complique client et serveur et ajoute des coûts. Les données binaires entrelacées NE DEVRAIENT être utilisées que si RTSP est transporté sur TCP.

Les données de flux telles que les paquets RTP sont encapsulées par un dollar ASCII (24 hex), suivi d'un identifiant de canal sur un octet, suivi de la longueur des données binaires encapsulées comme entier binaire de deux octets en ordre réseau. Les données de flux suivent immédiatement, sans CRLF, mais avec les en-têtes de protocole de couche supérieure. Chaque bloc $ contient exactement une unité de données de protocole de couche supérieure, par ex. un paquet RTP.

L'identifiant de canal est défini dans l'en-tête Transport avec le paramètre interleaved (section 12.39).

Lorsque le transport est RTP, le serveur entrelace aussi les messages RTCP sur la connexion TCP. Par défaut, les paquets RTCP sont envoyés sur le premier canal disponible supérieur au canal RTP. Le client PEUT demander explicitement un autre canal, en spécifiant deux canaux dans interleaved (section 12.39).

RTCP est nécessaire pour la synchronisation lorsque plusieurs flux sont ainsi entrelacés. Cela fournit aussi un moyen pratique de tunneliser RTP/RTCP sur la connexion de contrôle TCP lorsque la configuration l'exige, puis de les transférer sur UDP si possible.

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}