Construire des pages pour l'interface HTTP

Table of Contents

Introduction
Les macros VLC
L'évaluateur RPN
Les macros

Introduction

Cette annexe décrit le language utilisé pour écrire des pages web dynamiques pour l'interface HTTP.

Les pages doivent être placées dans le répertoire share/http soit dans le répertoire de VLC (Windows, Mac), soit dans /usr/share/vlc/share/http, soit dans /usr/local/share/http (soit encore dans n'importe quel endroit contenant des fichiers partagés de vlc).

Certains fichiers sont traités à part :

  • Les fichiers commencant par '.' ne sont pas exportés.

  • Un fichier '.access' sera ouvert et l'interface http s'attendra à trouver à la première ligne un login et un mot de passe (sous la forme login:mot de passe). Ce login et mot de passe seront utilisés pour restreindre l'accès aux fichiers dans le répertoire. Attention : seuls les fichiers situés dans le répertoire seront protégés (les sous-répertoires ne sont pas protégés).

  • Un fichier '.host' sera ouvert et l'interface http s'attendra à trouver une list de paires réseau/maque séparés par des retours à la ligne, par exemple 192.168.0.0./255.255.255.0. Si ce fichier est présent, le comportement par défaut est de refuser l'accès aux clients dont l'adresse ne fait pas parti de l'une des pares réseau/masque pour tous les fichiers du répertoire. Si le fichier n'est pas présent, tous les clients auront accès aux fichiers du répertoire. Attention : seuls les fichiers situés dans le répertoire seront protégés (les sous-répertoires ne sont pas protégés).

  • Le fichier <dir>/index.html sera exporté comme <dir> et <dir>/ mais pas comme index.html.

Le type MIME est défini par l'extension du fichier et ne peut pas être spécifié ou modifié pour un fichier donné. Les extensions inconnues auront un type MIME "application/octet-stream".

Vous devriez éviter d'exporter de gros fichiers. En effet chaque fichier est d'abord chargé en mémoire avant d'être envoyé au client. Soyez donc prudents.

Les macros VLC

Chaque fois qu'une page .html/.htm est demandée, elle est analysée par VLC avant d'être envoyée. L'analyseur cherche des macros VLC et les exécute ou les substitue. Les arguments URL reçus par la méthode GET peuvent également être interprétés .

Une macro VLC ressemble à : <vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />.

"id" est le seul champ nécessaire, param1 et param2 sont facultatifs, et dépendent de la valeur de "id".

Vous devez faire attention à cette syntaxe, VLC n'apprécie pas pas les synataxes invalides (elles peuvent souvent être à la base de plantages).

Exemples :

Correct : < vlc id="value" param1="version" /gt;

Incorrect : <vlc id="value" param1="version" > (il manque le dernier paramètre), <vlc id=value param1="version" /> (il manque ici "" )

Les macros valides sont :

  • control (1 paramètre optionnel)

  • include (1 paramètre)

  • get (2 paramètres)

  • set (2 paramètres>

  • rpn (1 paramètre)

  • if (1 paramètre optionnel)

  • else (sans paramètre)

  • end (sans paramètre)

  • value (1 paramètre optionnel)

  • foreach (2 paramètres)

Pour des macros puissantes, vous pouvez utiliser ces outils :

  • L'évaluateur RPN (voir partie II)

  • Les piles : Une pile est un endroit où il est possible d'empiler des nombres et des chaînes des caractères, puis de les récupérer. Elles sont souvent utilisées avec l'évaluateur RPN.

  • Les variables locales : Il est possible de créer dynamiquement de nouvelles variables et de changer leurs valeurs. Quelques variables locales sont prédéfinies :

    • url_value : paramètre de l'URL

    • url_param : 1 si url_value n'est pas vide, 0 sinon

    • version : version de VLC

    • copyright : le copyright de VLC

    • vlc_compile_time, vlc_compile_by, vlc_compile_host, vlc_compile_domain, vlc_compiler, vlc_changeset: information sur le binaire VLC

    • stream_position, stream_time, stream_length, stream_state: information sur le flux en cours de lecture

    • volume : réglage de volume actuel

Remarque: Les piles et les variables locales sont réinitialisées avant l'exécution de la page.

L'évaluateur RPN

RPN sont les initiales de Reverse Polish Notation (Notation Polonaise Inversée)

Introduction

La notation RPN peut paraître étrange, mais c'est un moyen simple et rapide d'écrire des expressions. Cela évite également l'usage des parenthèses ( et ).

Au lieu d'écrire ( 1 + 2 ) * 5 , il suffit d'écrire 1 2 + 5 * .

L'idée sous-jacente est: S'il s'agit d'un nombre ou une chaîne de caractères (utilisant ''), il est placé sur la pile. Si c'est un opérateur (+ par exemple), les arguments sont récupérés sur la pile, l'opération est exécutée, et le résultat est placé sur la pile. Le résultat final de la séquence RPN est la valeur au sommet de la pile.

  pile:       Expression analysée
 vide       1                     1 est placé sur la pile
 1          2                     2 est placé sur la pile
 1 | 2      +                     +: remplace 1 et 2 par 3 au sommet de la pile
 3          5                     5 est placé au sommet de la pile
 3 | 5      *                     *: remplace 3 et 5 par 15 au sommet de la pile
15                                <- résutat

Opérateurs

Notation: ST(1) désigne l'élément situé au sommet de la pile, ST(2) le deuxième,... op est un opérateur.

Sont utilisables :

  • Les opérateurs mathématiques standards: +, -, *, /, %: ils placent le résultat de ST(1) op ST(2) au sommet de la pile

  • Les opérateurs binaires: ! (renvoie !ST(1)); ^, &, |: renvoient le résultat de ST(1) op ST(2)

  • Les tests: =, <, <=, >=: exécute ST(1) op ST(2) et renvoie -1 si vrai, 0 sinon

  • fonctions pour les chaînes de caractères:

    • strcat: renvoie la concaténation ST(1)ST(2)

    • strcmp: compare ST(1) et ST(2). Renvoie 0 s'ils sont égaux

    • strncmp: compare les ST(1) premiers caractères de ST(2) et ST(3). Renvoie 0 s'ils sont identiques

    • strsub: extrait les caractères ST(1) à ST(2) de la chaîne ST(3)

    • strlen : renvoie la longueur de ST(1)

    • str_replace: remplace la chaîne ST(2) avec ST(1) dans ST(3)

    • url_encode: encode les charactères non alphanumériques de ST(1) en %XX pour qu'ils puissent être passés en variables GET ou POST.

    • url_extract : fait l'opération inverse d'url_encode

    • addslashes: protège les guillemets simples (') et les guillemets doubles (") de ST(1) avec un backslash (\) pour qu'ils puissent êtres passés aux fonctions playlist de VLC

    • stripslashes : fait l'opération inverse de addslashes.

    • htmlspecialchars: encode les caractères &, ", ', < et > de ST(1) en &truc; pour qu'ils n'interagissent pas avec les balises HTML.

    • realpath: parse ST(1) comme le chemin d'accès à un fichier et renvoir le chemin absolu vers ce fichier, en enlevant ~ et ../

  • manipulation de la pile:

    • dup: enlève ST(1) de la pile et empile cette même chaîne deux fois

    • drop: enlève ST(1) de la pile

    • swap: échange ST(1) et ST(2)

    • flush : vide la pile

  • manipulation des variables:

    • store: stocke ST(2) dans une variable locale appelée ST(1)

    • value: renvoie la valeur de la variable locale appelée ST(1)

  • controle du lecteur:

    • vlc_play: lit l'élement de la playlist d'ID ST(1) et renvoie 0 en cas de success; voir les fonctions playlist plus bas

    • vlc_stop : arrête la playlist

    • vlc_pause : met la playlist en pause

    • vlc_next : joue l'item suivant dans la playlist

    • vlc_previous : joue l'item précédent dans la playlist

    • vlc_seek : seeks the current input to a location defined in ST(1), for instance +3m (minutes), -20s, 45%, 1:12, 1h12m25s

    • vlc_var_type: renvoie le type de la variable ST(2) de l'objet ST(1); le type est l'une de ces chaînes VLC_VAR_BOOL, VLC_VAR_INTEGER, VLC_VAR_HOTKEY, VLC_VAR_STRING, VLC_VAR_MODULE, VLC_VAR_FILE, VLC_VAR_DIRECTORY, VLC_VAR_VARIABLE, VLC_VAR_FLOAT, UNDEFINED (pas de variable de ce type) or INVALID (pas de flux en entrée); l'objet est VLC_OBJECT_ROOT, VLC_OBJECT_VLC, VLC_OBJECT_INTF, VLC_OBJECT_PLAYLIST, VLC_OBJECT_INPUT, VLC_OBJECT_VOUT, VLC_OBJECT_AOUT ou VLC_OBJECT_SOUT

    • vlc_var_set: change la valeur de la variable ST(2) de l'objet ST(1) à ST(3)

    • vlc_var_get: renvoie la valeur de la variable ST(2) de l'objet ST(1)

    • vlc_object_exists : vérifie si l'objet ST(1) existe

    • vlc_config_type: renvoie le type de la variable de configuration ST(1); voir vlc_var_type pour une liste de types

    • vlc_config_set : change la valeur de la variable de configuration ST(1) à ST(2)

    • vlc_config_get: renvoie la valeur de la variable de configuration ST(1)

    • vlc_config_save: sauve les modifications apportées aux variables de configuration du module ST(1) (ST(1) peut être vide, au quel cas toute la configuration est sauvegardée) et renvoir l'état de sortie (0 en cas de succès)

    • vlc_config_reset: réinitialise le fichier de configuration aux valeurs par défaut

  • fonctions pour la playlist:

    • playlist_add: ajoute MRL ST(1) à la liste de lecture, avec le nom ST(1) et renvoie l'ID associé à l'élément ainsi créé; les caractères spéciaux doivent être echapés avec addslashes; il est pratique d'appeler 'toto.mpg' playlist_add vlc_play

    • playlist_empty: vide la playlist

    • playlist_move: bouge l'élément de la playlist en position ST(2) à la position ST(1)

    • playlist_delete : efface l'élément d'ID ST(1) de la playlist

Les macros

La macro control

The use of the control macro is now deprecated in favour of the RPN functions above. The documentation is provided here for the maintainance of HTML pages still using this old API. The main problem with this API is that there is no way to retrieve the playlist ID of the last added item.

Lorsqu'une page est appelée, des arguments peuvent lui être passés à travers l'URL. (par ex: en utilisant <form>). Ex: http://host:port/page.html?var=value&var2=value2&.. La macro "control" demande à la page de vérifier ces arguments et d'exécuter ceux qui sont autorisés. Le paramètre param1 de cette macro spécifie les commandes autorisées, s'il est vide, toutes les commandes seront permises.

Certaines commandes requièrent un argument qui doit également être spécifié dans l'URL.

Table B.1.  Les commandes dans l'URL

NomArgument Description
play item (entier) Lit l'élément spécifié de la playlist
stop  stop
pause Pause
next  Avance jusqu'au prochain élément de la playlist
previous  Recule à l'élément précédent de la playlist
add mrl (chaine de caractères) Ajoute un MRL (Ressource de Localistion de Média) à la playlist
delete item (entier) Supprime l'élément de playlist spécifié, ou la liste d'éléments de la playlist
empty  En utilisant la playlist (liste de lecture)
close id (hexa) Ferme une connection spécifique
shutdown  Quitter VLC

Par exemple, vous pouvez restreindre l'exécution de la commande shutdown à une page protégée (par un fichier .acces), tout en utilisant la macro control dans toutes les pages non protégées.

La macro include

Cette macro est remplacée par le contenu du fichier param1. Si le fichier contient des macros VLC, elles seront exécutées.

La macro get

Cette macro sera remplacée par la valeur de la variable de configuration dont le nom est stocké dans param1 et dont le type est donné par param2.

param1 doit être le nom d'une variable de configuration existante. param2 doit être le type de la variable. Il devra être choisi parmi int, float, ou string.

Exemple: <vlc id="get" param1="sout" param2="string" /> sera remplacé par la valeur de sout dans la page.

La macro set

Cette macro permet de définir la valeur d'une variable de configuration. Le nom est donné par param1 et le type par param2 (comme pour get). La valeur est définie à partir de l'URL en utilisant le nom donné dans param1.

Par exemple, si player.html contient <vlc id="set" param1="sout" param2="string" />, et si vous demandez la page http://host:ip/player.html?sout=sout_value, la variable sout sera égale à "sout_value". Si l'URL ne contient pas sout, rien ne sera fait.

La macro rpn

Cette macro vous permet d'interpréter les commandes RPN. (Voir II).

La macro if, else, end

Cette macro vous permet de controler la validité de la page HTML.

Si param1 n'est pas vide, il est tout d'abbord exectuté avec l'évaluateur RPN. Si le premier élément de la liste n'est pas 0, le résultat du test est vrai, faux sinon...

  <vlc id="if" param1="1 2 =" />
    <!-- Jamais atteint -->
 <vlc id="else" />
    <p> Test vrai: 1 n'est pas égal à 2</p>
 <vlc id="end" />

Vous pouvez aussi n'utiliser que "if" et "end".

La macro value

Si param1 n'est pas vide, il est tout d'abord exécuté avec l'évaluateur RPN. La macro est remplacée par la valeur du premier élément de la pile.

Remarque: Si l'élément est le nom d'une variable locale, sa valeur sera affichée à la place de son nom.

La macro foreach,end

param1 est le nom de la variable utilisée pour la boucle. param2 est le nom de l'ensemble construit :

  • integer: prenedre le premier élément de la pile pour construire une suite d'entiers. L'élément pile devra être une chaîne de caractères de caractères de la forme: premier:dernier[:pas][,premier2:dernier2[:pas2][,...] (Ex: 1:5:2,6:8:1 sera interprété comme 1,3,5,6,7,8)

  • directory: prendre le premier élément de la pile comme répertoire de base et construire un ensemble intrinsèque de noms de fichiers. Chaque élément possède les champs suivants:

    • name: fichier/nom de répertoire

    • type: "directory" ou "file" ou "unknown"

    • size: taille du fichier

    • date

  • playlist: ensemble basé sur la playlist avec les champs suivants: current est égal à 1 si l'élément est actuellement sélectionné, 0 sinon. index est la valeur d'indexation, qui peut être utilisée par les commandes lecture ou supprimer. name est le nom de l'élément.

  • "information": Crée des informations concernant le flux diffusé. name est le nom de la catégorie, value est sa valeur, info est un nouvel ensemble qui peut être rempli à chaque fois (les champs secondaires de info sont name et value).

  • les variables d'entrée telles que "program", "title", "chapter", "audio-es", "video-es" et "spu-es": Créer une liste pour l'élément en cours de lecture. Chaque liste a les champs suivants:

    • nome: nom de l'élément (langue des flux élémentaires, pistes, etc.) à afficher aux endroits où un format lisible est préféré

    • id: ID de l'élément à passer en argument de la fonction vlc_var_set et renvoyé par la fonction vlc_var_get

    • selected: 1 si l'élément est sélectionné, 0 sinon

  • le nom d'une variable foreach si c'est un ensemble d'ensembles de valeurs.

    <vlc id="foreach" param1="cat" param2="informations" />
                    <p> <vlc id="value" param1="cat.name" />
                    <ul>
                    <vlc id="foreach" param1="info" param2="cat.info" />
                        <li>
                        <vlc id="value" param1="info.name" /> :
                                <vlc id="value" param1="info.value" />
                        </li>
                    <vlc id="end" />
                    </ul>
                <vlc id="end" />
    

Pour plus de détails, regardez le répertoire share/http situé à la racine de l'arboresence de VLC...