git.sesse.net Git - vlc/blob - doc/intf-http.txt

   1 HTTP interface
   2 --------------
   3
   4 I. Presentation
   5 ###############
   6
   7  1. VLC has a little HTTP server
   8  -------------------------------
   9
  10  You can launch the HTTP interface with :
  11
  12  vlc -I http --http-src /directory/ --http-host host:port
  13
  14  The  HTTP interface  will listen  at host:port  and will  reproduce the
  15 structure of /directory at http://host:ip/
  16
  17 While exporting /director, some files are a bit special :
  18
  19  * files beginning with '.' : they won't be exported.
  20  * file '.access' : It will be  opened and http interface expect to find
  21   at the  first line a  login/password (written as  login:password). This
  22   login/password will  be used  to protect all  files in  this directory.
  23   Be  careful  that only  files  in  this  directory will  be  protected,
  24   particularly sub-directory won't be protected.
  25  * file <dir>/index.html will be exported as <dir> and <dir>/ and not as
  26   index.html.
  27
  28 Examples:
  29  Sources                            URL
  30  directory/index.html           ->  http://host:port/
  31  directory/help.html            ->  http://host:port/help.html
  32  directory/help.gif             ->  http://host:port/help.gif
  33  directory/.access              ->  "Not exported"
  34  directory/dir2/essai.html      ->  http://host:port/dir2/essai.html
  35
  36  The  mime type  is  set looking  at  file extension  and  it cannot  be
  37 specified/modified for specific  file.  Unknown  extensions  will  have
  38 "application/octet-stream" as the mime type.
  39
  40  You  should avoid  exported big  files.  Actually, each  file is  first
  41 loaded in memory before being sent to a client, so be careful ...
  42
  43
  44  2. VLC macro in .html/.htm pages
  45  --------------------------------
  46
  47  a. Presentation
  48  ---------------
  49
  50  Each type,  a .html/.htm  page is  requested, it is  parsed by  the vlc
  51 before sent. This parser search for  special vlc macro, and then execute
  52 them or substitute them.
  53  Moreover, when receiving URL arguments (by a GET method), they could be
  54 interpreted.
  55
  56  b. Syntax
  57  ---------
  58  A vlc macro have to respect :
  59  <vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />
  60
  61  "id" is the only  mandatory field, param1 and param2 may  or may not be
  62 present and depends on the value of "id".
  63
  64  You should take care that you  _have to_ respect this syntax, VLC won't
  65 like invalid syntax. (It could easily leads to segfaults)
  66
  67  For examples :
  68  Correct:
  69      <vlc id="value" param1="version" /> is correct
  70  Invalid:
  71      <vlc id="value" param1="version" >     <- invalid tag ending
  72      <vlc id=value param1="version" />      <- missing "" around value
  73
  74  c. Valid macro list
  75  -------------------
  76
  77  For now the following macro are valid :
  78
  79    Macro    | Parameter 1 | Parameter 2
  80  ----------------------------------------------
  81    control  |   Optional  |
  82    get      |     Yes     |    Yes
  83    set      |     Yes     |    Yes
  84    rpn      |     Yes     |
  85    if       |   Optional  |
  86    else     |             |
  87    end      |             |
  88    value    |   Optional  |
  89    foreach  |     Yes     |    Yes
  90
  91  3. RPN, Stacks and locale variables
  92  ------------------------------
  93
  94  To provide powerful macro, you have access to
  95
  96  a. RPN evaluator
  97  ----------------
  98  See II.
  99
 100  b. Stacks
 101  ---------
 102  The stacks is a place where you can push numbers and strings, and then
 103 pop them backs. It's used with the little RPN evaluator.
 104
 105  c. Locales variables
 106  --------------------
 107  You can dynamically create new variables and changes their values.
 108  Some locales variables are predefined
 109     - url_value : parameter of the url
 110     - url_param : 1 if url_value isn't empty else 0
 111     - version   : the VLC version
 112     - copyright : the VLC copyright
 113
 114  Variables could have fields, just use . to access them.
 115   Ex: var.field, var.field.subfield, ...
 116  A field could in fact be a set, so use [] to access a particular element.
 117   Ex: var.field[2], var.field[3].subfield[12]
 118
 119  Remarks: you cannot create (yet) such variables with fields.
 120
 121  4. Remarks:
 122  -----------
 123  The stacks, and locales variables context  is reseted before a page is
 124 executed.
 125
 126 II. RPN evaluator
 127 #################
 128
 129  RPN means Reverse Polish Notation.
 130
 131  1.introduction
 132  --------------
 133
 134  RPN could be strange but it's a fast and easy way to write expressions.
 135 It also avoid the use of ( and ).
 136
 137  Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *
 138  The idea beyond it is :
 139   - if it is a number or a string (using '') push it on the stack
 140   - if it is an operator (like +), pop the arguments from the stack,
 141   execute the operators and then push the result onto the stack.
 142  The result of the RPN sequence is the value at the top of the stack.
 143
 144
 145 Ex: instead of writing (1+2)*5 you enter 1 2 + 5 *
 146
 147 stack:      Word processed
 148  <empty>    1                   1 is pushed on the stack
 149  1          2                   2 same things
 150  1 | 2      +                   + : remove 1 and 2 and write 3 on the stack
 151  3          5                   5 is pushed on the stack
 152  3 | 5      *                   * : remove 3 and 5 and write 15
 153  15                             <- result
 154
 155
 156  2. Operators.
 157  -------------
 158
 159  Notation : ST(1) means the first stack element, ST(2) the second one ...
 160  and op the operator.
 161
 162 You have access to :
 163
 164  * standard arithmetics operators:
 165     +, -, *, /, %   : push the result of ST(1) op ST(2)
 166  * standard binary operators:
 167     !               : push !ST(1)
 168     ^, &, |         : push the result of ST(1) op ST(2)
 169  * test:
 170     =, <, <=, >, >= : do ST(1) op ST(2) and push -1 if true else 0
 171  * string:
 172     strcat          : push the result of 'ST(1)ST(2)'
 173     strcmp          : compare ST(1) and ST(2), push -1, 0, or 1
 174     strlen          : push the length of ST(1)
 175  * stack manipulation
 176     dup             : duplicate ST(1) on the stack
 177     drop            : remove ST(1)
 178     swap            : swap ST(1) and ST(2)
 179     flush           : empty the stack
 180  * variables manipulation:
 181     store           : store ST(2) in a locale variable named ST(1)
 182     value           : push the value of the local variable named ST(1)
 183     url_extract     : push the value of the ST(1) part of the url parameters.
 184
 185 III. Macros
 186 ###########
 187
 188  1. Macro "control"
 189  ------------------
 190  When asking for a page, you can pass arguments to it through the url.
 191 (eg using a <form>)
 192  Ex: http://host:port/page.html?var=value&var2=value2&...
 193
 194  The "control" macro warm a page to parse such arguments and give control
 195 on which one will be authorized.
 196
 197 param1 of this macro say which command are allowed, if empty then all
 198 commands will work.
 199
 200 Url commands are :
 201
 202   | Name      | argument     |
 203   -----------------------------------------------------------------
 204   | play      | item(integer)| Play the specified item
 205   | stop      |              | Stop
 206   | pause     |              | Pause
 207   | next      |              | Go to the next playlist element
 208   | previous  |              | Got to the previous playlist element
 209   | add       | mrl(string)  | Add a mrl to the playlist
 210   | delete    | item(integer)| Deletes an (list of) element of the playlist
 211   | empty     |              | Empty the playlist
 212   | close     | id(hexa)     | Close a specific connection
 213   | shutdown  |              | Quit vlc
 214
 215 For example, you  can restrict the execution of the  shutdown command to
 216 protected pages (through a .access) using the control macro in all pages
 217 unprotected.
 218
 219  2. Macro "get"
 220  --------------
 221
 222  This macro will  be replaced by the value of  the configuration variable
 223 which name is stored in param1 and the type is given by param2.
 224
 225  - param1 should be a existing name of a configuration variable
 226  - param2 should be the correct type of this variable. You have
 227         - int
 228         - float
 229         - string
 230
 231 Example:
 232  <vlc id="get" param1="sout" param2="string" />
 233 will be replaced in the output page by the value of sout.
 234
 235  3. Macro "set"
 236  --------------
 237
 238  This macro allow to set the value of a configuration variable.
 239  The name is given by param1 and the type by param2 (like for get).
 240 The value is retrieve from the url using the name in param1.
 241
 242  So if player.html contain <vlc id="set" param1="sout" param2="string" />
 243 and then you can call http://host:ip/player.html?sout=sout_value to
 244 set sout to the value "sout_value"
 245
 246  If the url doesn't contain sout, then nothing is done.
 247
 248  4. Macro "rpn"
 249  -------------
 250  This macro allows you to interpret RPN commands.
 251  See II.
 252
 253
 254  5. Macro "if" "else" "end"
 255  --------------------------
 256  It allows to control the parsing of the html page.
 257
 258  -> if param1 isn't empty, it is first executed with the RPN evaluator.
 259  -> if the first element from the stack isn't 0 the test value is true
 260 else false.
 261
 262 ex:
 263  <vlc id="if" param1="1 2 =" />
 264     <!-- Never reached -->
 265  <vlc id="else" />
 266     <p> Test succeed 1 isn't equal to 2 <p>
 267  <vlc id="end" />
 268
 269  You can also just use "if" and "end".
 270
 271  6. Macro "value"
 272  ----------------
 273  ->if param1 isn't empty, it is first executed with the RPN evaluator.
 274  ->the macro is replaced with the value of the first element of the stack.
 275
 276  Remarks: if  it's in  fact a  locale variable name,  the value  of this
 277 variable will be displayed (instead of it name).
 278
 279  7. Macro "foreach" "end"
 280  ------------------------
 281
 282  param1 : name of the variable used for the loop
 283  param2 : name of the set to be build:
 284         - "integer" : take the first element from the stack to construct
 285           a set of integer. The stack element should be a string like:
 286            first:last[:step][,first2:last2[:step2][,...]
 287            Ex: 1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8
 288
 289         - "directory" : take the first  element of the stack as the base
 290           directory and construct a set of filename and directly in it.
 291            Each element has the following fields:
 292             - name : file/directory name
 293             - type : "directory" or "file" or "unknown"
 294             - size : size of the file
 295             - date
 296
 297         - "playlist" :
 298           Fields:
 299             - current : 1 if currently selected else 0
 300             - index   : the index value (to be used for example for the
 301                         "delete" control command.
 302             - name
 303
 304         - "informations"  : Create informations for  the current playing
 305           stream.
 306           Fields:
 307             - name : Category name
 308             - value : Category value
 309             - info : a new set so you can parse it with another foreach.
 310              Sub fields :
 311                 - name : Info name
 312                 - value Info value
 313         - "hosts" : Create the list of host we are listening.
 314           Fields:
 315             - id  : opaque id
 316             - host:
 317             - ip  :
 318             - port:
 319
 320         - "urls" : Create the list of urls currently available
 321           Fields:
 322             - id    :
 323             - stream: 1 if it's a stream else 0.
 324             - url   :
 325             - mime  :
 326             - protected: 1 if protected else 0.
 327             - used  :
 328         - "connections" : Create the list of current connections.
 329           Fields:
 330             - id : opaque id, used by "control" macro (with close command)
 331             - ip :
 332             - url:
 333             - status: HTTP error code.
 334
 335         - the name of a foreach variable if it's a set of set of value.
 336           Ex :
 337             <vlc id="foreach" param1="cat" param2="informations" />
 338                 <p> <vlc id="value" param1="cat.name" />
 339                 <ul>
 340                 <vlc id="foreach" param1="info" param2="cat.info" />
 341                     <li>
 342                     <vlc id="value" param1="info.name" /> :
 343                             <vlc id="value" param1="info.value" />
 344                     </li>
 345                 <vlc id="end" />
 346                 </ul>
 347             <vlc id="end" />
 348
 349 IV. Conclusion
 350 ##############
 351
 352  Have a look at share/http directory of the VLC sources...
 353
 354  Any remarks, suggestions, ... -> fenrir@via.ecp.fr
 355