* 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 ;)

doc/intf-http.txt

+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
+