Table of Contents
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.
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.
RPN sont les initiales de Reverse Polish Notation (Notation Polonaise Inversée)
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
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
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
Nom | Argument | 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.
Cette macro est remplacée par le contenu du fichier param1. Si le fichier contient des macros VLC, elles seront exécutées.
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.
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.
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".
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.
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...