--- /dev/null
+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
+
projects / vlc / commitdiff