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
    - stream_position : current position of the VLC in the stream (percentage)
    - stream_time : current position of the VLC in the stream (in seconds)
    - stream_length : total length of the current stream (in seconds)
    - volume : current volume level
    - stream_state : current state of the VLC (playing, paused, stop)

 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
    strncmp         : compare the ST(3) first characters of 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       | arguments    |
  -------------------------------------------------------------------------------
  | 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
  | fullscreen |              | toggle fullscreen
  | volume     | value(string)| set volume level (absolute or relative)
  | seek       | seek_value   | c.f. notes
  | add        | mrl(string)  | Add a mrl to the playlist (with its options)
  | delete     | item(integer)| Deletes an (list of) element of the playlist
  | keep       | item(integer)| Deletes all but (list of) element of the playlist
  | sort       | type,order   | c.f. notes
  | 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.

Notes:
 Seek: The seek command is used to seek in current playing stream. the
seek_value argument is a string which represents a relative or absolute
position in the stream: a percentage, or a time.
For examples "+12min 42sec", "01:13:43", "-12%", "42%", or
"1 hour 12 minutes" are valid argument values.
 Sort: sorts the playlist by type (string), and with the order (integer).
If order is "0", it is normal order. Otherwise it is reverse order. The
type can be "title", "group", "author".


 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 
                        "delete" control command.
            - name
            - group   : the group number

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