Commit 0dea3ebd authored by Laurent Aimar's avatar Laurent Aimar

* intf-http.txt: small doc about how to write .html page for the http

 interface (up to date, but a bit technical...).

 Btw, the first who ask me to write another documentation will just go
 to hell ;)
parent 49603672
HTTP interface
--------------
I. Presentation
###############
1. VLC has a little HTTP server
-------------------------------
You can launch the HTTP interface with :
vlc -I http --http-src /directory/ --http-host host:port
The HTTP interface will listen at host:port and will reproduce the
structure of /directory at http://host:ip/
While exporting /director, some files are a bit special :
* files beginning with '.' : they won't be exported.
* file '.access' : It will be opened and http interface expect to find
at the first line a login/password (written as login:password). This
login/password will be used to protect all files in this directory.
Be careful that only files in this directory will be protected,
particularly sub-directory won't be protected.
* file <dir>/index.html will be exported as <dir> and <dir>/ and not as
index.html.
Examples:
Sources URL
directory/index.html -> http://host:port/
directory/help.html -> http://host:port/help.html
directory/help.gif -> http://host:port/help.gif
directory/.access -> "Not exported"
directory/dir2/essai.html -> http://host:port/dir2/essai.html
The mime type is set looking at file extension and it cannot be
specified/modified for specific file. Unknown extensions will have
"application/octet-stream" as the mime type.
You should avoid exported big files. Actually, each file is first
loaded in memory before being sent to a client, so be careful ...
2. VLC macro in .html/.htm pages
--------------------------------
a. Presentation
---------------
Each type, a .html/.htm page is requested, it is parsed by the vlc
before sent. This parser search for special vlc macro, and then execute
them or substitute them.
Moreover, when receiving URL arguments (by a GET method), they could be
interpreted.
b. Syntax
---------
A vlc macro have to respect :
<vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />
"id" is the only mandatory field, param1 and param2 may or may not be
present and depends on the value of "id".
You should take care that you _have to_ respect this syntax, VLC won't
like invalid syntax. (It could easily leads to segfaults)
For examples :
Correct:
<vlc id="value" param1="version" /> is correct
Invalid:
<vlc id="value" param1="version" > <- invalid tag ending
<vlc id=value param1="version" /> <- missing "" around value
c. Valid macro list
-------------------
For now the following macro are valid :
Macro | Parameter 1 | Parameter 2
----------------------------------------------
control | Optional |
get | Yes | Yes
set | Yes | Yes
rpn | Yes |
if | Optional |
else | |
end | |
value | Optional |
foreach | Yes | Yes
3. RPN, Stacks and locale variables
------------------------------
To provide powerful macro, you have access to
a. RPN evaluator
----------------
See II.
b. Stacks
---------
The stacks is a place where you can push numbers and strings, and then
pop them backs. It's used with the little RPN evaluator.
c. Locales variables
--------------------
You can dynamically create new variables and changes their values.
Some locales variables are predefined
- url_value : parameter of the url
- url_param : 1 if url_value isn't empty else 0
- version : the VLC version
- copyright : the VLC copyright
Variables could have fields, just use . to access them.
Ex: var.field, var.field.subfield, ...
A field could in fact be a set, so use [] to access a particular element.
Ex: var.field[2], var.field[3].subfield[12]
Remarks: you cannot create (yet) such variables with fields.
4. Remarks:
-----------
The stacks, and locales variables context is reseted before a page is
executed.
II. RPN evaluator
#################
RPN means Reverse Polish Notation.
1.introduction
--------------
RPN could be strange but it's a fast and easy way to write expressions.
It also avoid the use of ( and ).
Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *
The idea beyond it is :
- if it is a number or a string (using '') push it on the stack
- if it is an operator (like +), pop the arguments from the stack,
execute the operators and then push the result onto the stack.
The result of the RPN sequence is the value at the top of the stack.
Ex: instead of writing (1+2)*5 you enter 1 2 + 5 *
stack: Word processed
<empty> 1 1 is pushed on the stack
1 2 2 same things
1 | 2 + + : remove 1 and 2 and write 3 on the stack
3 5 5 is pushed on the stack
3 | 5 * * : remove 3 and 5 and write 15
15 <- result
2. Operators.
-------------
Notation : ST(1) means the first stack element, ST(2) the second one ...
and op the operator.
You have access to :
* standard arithmetics operators:
+, -, *, /, % : push the result of ST(1) op ST(2)
* standard binary operators:
! : push !ST(1)
^, &, | : push the result of ST(1) op ST(2)
* test:
=, <, <=, >, >= : do ST(1) op ST(2) and push -1 if true else 0
* string:
strcat : push the result of 'ST(1)ST(2)'
strcmp : compare ST(1) and ST(2), push -1, 0, or 1
strlen : push the length of ST(1)
* stack manipulation
dup : duplicate ST(1) on the stack
drop : remove ST(1)
swap : swap ST(1) and ST(2)
flush : empty the stack
* variables manipulation:
store : store ST(2) in a locale variable named ST(1)
value : push the value of the local variable named ST(1)
url_extract : push the value of the ST(1) part of the url parameters.
III. Macros
###########
1. Macro "control"
------------------
When asking for a page, you can pass arguments to it through the url.
(eg using a <form>)
Ex: http://host:port/page.html?var=value&var2=value2&...
The "control" macro warm a page to parse such arguments and give control
on which one will be authorized.
param1 of this macro say which command are allowed, if empty then all
commands will work.
Url commands are :
| Name | argument |
-----------------------------------------------------------------
| play | item(integer)| Play the specified item
| stop | | Stop
| pause | | Pause
| next | | Go to the next playlist element
| previous | | Got to the previous playlist element
| add | mrl(string) | Add a mrl to the playlist
| del | item(integer)| Del an element of the playlist
| empty | | Empty the playlist
| close | id(hexa) | Close a specific connection
| shutdown | | Quit vlc
For example, you can restrict the execution of the shutdown command to
protected pages (through a .access) using the control macro in all pages
unprotected.
2. Macro "get"
--------------
This macro will be replaced by the value of the configuration variable
which name is stored in param1 and the type is given by param2.
- param1 should be a existing name of a configuration variable
- param2 should be the correct type of this variable. You have
- int
- float
- string
Example:
<vlc id="get" param1="sout" param2="string" />
will be replaced in the output page by the value of sout.
3. Macro "set"
--------------
This macro allow to set the value of a configuration variable.
The name is given by param1 and the type by param2 (like for get).
The value is retrieve from the url using the name in param1.
So if player.html contain <vlc id="set" param1="sout" param2="string" />
and then you can call http://host:ip/player.html?sout=sout_value to
set sout to the value "sout_value"
If the url doesn't contain sout, then nothing is done.
4. Macro "rpn"
-------------
This macro allows you to interpret RPN commands.
See II.
5. Macro "if" "else" "end"
--------------------------
It allows to control the parsing of the html page.
-> if param1 isn't empty, it is first executed with the RPN evaluator.
-> if the first element from the stack isn't 0 the test value is true
else false.
ex:
<vlc id="if" param1="1 2 =" />
<!-- Never reached -->
<vlc id="else" />
<p> Test succeed 1 isn't equal to 2 <p>
<vlc id="end" />
You can also just use "if" and "end".
6. Macro "value"
----------------
->if param1 isn't empty, it is first executed with the RPN evaluator.
->the macro is replaced with the value of the first element of the stack.
Remarks: if it's in fact a locale variable name, the value of this
variable will be displayed (instead of it name).
7. Macro "foreach" "end"
------------------------
param1 : name of the variable used for the loop
param2 : name of the set to be build:
- "integer" : take the first element from the stack to construct
a set of integer. The stack element should be a string like:
first:last[:step][,first2:last2[:step2][,...]
Ex: 1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8
- "directory" : take the first element of the stack as the base
directory and construct a set of filename and directly in it.
Each element has the following fields:
- name : file/directory name
- type : "directory" or "file" or "unknown"
- size : size of the file
- date
- "playlist" :
Fields:
- current : 1 if currently selected else 0
- index : the index value (to be used for example for the
"del" control command.
- name
- "informations" : Create informations for the current playing
stream.
Fields:
- name : Category name
- value : Category value
- info : a new set so you can parse it with another foreach.
Sub fields :
- name : Info name
- value Info value
- "hosts" : Create the list of host we are listening.
Fields:
- id : opaque id
- host:
- ip :
- port:
- "urls" : Create the list of urls currently available
Fields:
- id :
- stream: 1 if it's a stream else 0.
- url :
- mime :
- protected: 1 if protected else 0.
- used :
- "connections" : Create the list of current connections.
Fields:
- id : opaque id, used by "control" macro (with close command)
- ip :
- url:
- status: HTTP error code.
- the name of a foreach variable if it's a set of set of value.
Ex :
<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" />
IV. Conclusion
##############
Have a look at share/http directory of the VLC sources...
Any remarks, suggestions, ... -> fenrir@via.ecp.fr
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment