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     - stream_position : current position of the VLC in the stream (percentage)
 114     - stream_time : current position of the VLC in the stream (in seconds)
 115     - stream_length : total length of the current stream (in seconds)
 116     - volume : current volume level
 117     - stream_state : current state of the VLC (playing, paused, stop)
 118
 119  Variables could have fields, just use . to access them.
 120   Ex: var.field, var.field.subfield, ...
 121  A field could in fact be a set, so use [] to access a particular element.
 122   Ex: var.field[2], var.field[3].subfield[12]
 123
 124  Remarks: you cannot create (yet) such variables with fields.
 125
 126  4. Remarks:
 127  -----------
 128  The stacks, and locales variables context  is reseted before a page is
 129 executed.
 130
 131 II. RPN evaluator
 132 #################
 133
 134  RPN means Reverse Polish Notation.
 135
 136  1.introduction
 137  --------------
 138
 139  RPN could be strange but it's a fast and easy way to write expressions.
 140 It also avoid the use of ( and ).
 141
 142  Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *
 143  The idea beyond it is :
 144   - if it is a number or a string (using '') push it on the stack
 145   - if it is an operator (like +), pop the arguments from the stack,
 146   execute the operators and then push the result onto the stack.
 147  The result of the RPN sequence is the value at the top of the stack.
 148
 149
 150 Ex: instead of writing (1+2)*5 you enter 1 2 + 5 *
 151
 152 stack:      Word processed
 153  <empty>    1                   1 is pushed on the stack
 154  1          2                   2 same things
 155  1 | 2      +                   + : remove 1 and 2 and write 3 on the stack
 156  3          5                   5 is pushed on the stack
 157  3 | 5      *                   * : remove 3 and 5 and write 15
 158  15                             <- result
 159
 160
 161  2. Operators.
 162  -------------
 163
 164  Notation : ST(1) means the first stack element, ST(2) the second one ...
 165  and op the operator.
 166
 167 You have access to :
 168
 169  * standard arithmetics operators:
 170     +, -, *, /, %   : push the result of ST(1) op ST(2)
 171  * standard binary operators:
 172     !               : push !ST(1)
 173     ^, &, |         : push the result of ST(1) op ST(2)
 174  * test:
 175     =, <, <=, >, >= : do ST(1) op ST(2) and push -1 if true else 0
 176  * string:
 177     strcat          : push the result of 'ST(1)ST(2)'
 178     strcmp          : compare ST(1) and ST(2), push -1, 0, or 1
 179     strncmp         : compare the ST(3) first characters of ST(1) and ST(2),
 180                       push -1, 0, or 1
 181     strlen          : push the length of ST(1)
 182  * stack manipulation
 183     dup             : duplicate ST(1) on the stack
 184     drop            : remove ST(1)
 185     swap            : swap ST(1) and ST(2)
 186     flush           : empty the stack
 187  * variables manipulation:
 188     store           : store ST(2) in a locale variable named ST(1)
 189     value           : push the value of the local variable named ST(1)
 190     url_extract     : push the value of the ST(1) part of the url parameters.
 191
 192 III. Macros
 193 ###########
 194
 195  1. Macro "control"
 196  ------------------
 197  When asking for a page, you can pass arguments to it through the url.
 198 (eg using a <form>)
 199  Ex: http://host:port/page.html?var=value&var2=value2&...
 200
 201  The "control" macro warm a page to parse such arguments and give control
 202 on which one will be authorized.
 203
 204 param1 of this macro say which command are allowed, if empty then all
 205 commands will work.
 206
 207 Url commands are :
 208
 209   | Name       | arguments    |
 210   -------------------------------------------------------------------------------
 211   | play       | item(integer)| Play the specified item
 212   | stop       |              | Stop
 213   | pause      |              | Pause
 214   | next       |              | Go to the next playlist element
 215   | previous   |              | Got to the previous playlist element
 216   | fullscreen |              | toggle fullscreen
 217   | volume     | value(string)| set volume level (absolute or relative)
 218   | seek       | seek_value   | c.f. notes
 219   | add        | mrl(string)  | Add a mrl to the playlist (with its options)
 220   | delete     | item(integer)| Deletes an (list of) element of the playlist
 221   | keep       | item(integer)| Deletes all but (list of) element of the playlist
 222   | sort       | type,order   | c.f. notes
 223   | empty      |              | Empty the playlist
 224   | close      | id(hexa)     | Close a specific connection
 225   | shutdown   |              | Quit vlc
 226
 227 For example, you  can restrict the execution of the  shutdown command to
 228 protected pages (through a .access) using the control macro in all pages
 229 unprotected.
 230
 231 Notes:
 232  Seek: The seek command is used to seek in current playing stream. the
 233 seek_value argument is a string which represents a relative or absolute
 234 position in the stream: a percentage, or a time.
 235 For examples "+12min 42sec", "01:13:43", "-12%", "42%", or
 236 "1 hour 12 minutes" are valid argument values.
 237  Sort: sorts the playlist by type (string), and with the order (integer).
 238 If order is "0", it is normal order. Otherwise it is reverse order. The
 239 type can be "title", "group", "author".
 240
 241
 242  2. Macro "get"
 243  --------------
 244
 245  This macro will  be replaced by the value of  the configuration variable
 246 which name is stored in param1 and the type is given by param2.
 247
 248  - param1 should be a existing name of a configuration variable
 249  - param2 should be the correct type of this variable. You have
 250         - int
 251         - float
 252         - string
 253
 254 Example:
 255  <vlc id="get" param1="sout" param2="string" />
 256 will be replaced in the output page by the value of sout.
 257
 258  3. Macro "set"
 259  --------------
 260
 261  This macro allow to set the value of a configuration variable.
 262  The name is given by param1 and the type by param2 (like for get).
 263 The value is retrieve from the url using the name in param1.
 264
 265  So if player.html contain <vlc id="set" param1="sout" param2="string" />
 266 and then you can call http://host:ip/player.html?sout=sout_value to
 267 set sout to the value "sout_value"
 268
 269  If the url doesn't contain sout, then nothing is done.
 270
 271  4. Macro "rpn"
 272  -------------
 273  This macro allows you to interpret RPN commands.
 274  See II.
 275
 276
 277  5. Macro "if" "else" "end"
 278  --------------------------
 279  It allows to control the parsing of the html page.
 280
 281  -> if param1 isn't empty, it is first executed with the RPN evaluator.
 282  -> if the first element from the stack isn't 0 the test value is true
 283 else false.
 284
 285 ex:
 286  <vlc id="if" param1="1 2 =" />
 287     <!-- Never reached -->
 288  <vlc id="else" />
 289     <p> Test succeed 1 isn't equal to 2 <p>
 290  <vlc id="end" />
 291
 292  You can also just use "if" and "end".
 293
 294  6. Macro "value"
 295  ----------------
 296  ->if param1 isn't empty, it is first executed with the RPN evaluator.
 297  ->the macro is replaced with the value of the first element of the stack.
 298
 299  Remarks: if  it's in  fact a  locale variable name,  the value  of this
 300 variable will be displayed (instead of it name).
 301
 302  7. Macro "foreach" "end"
 303  ------------------------
 304
 305  param1 : name of the variable used for the loop
 306  param2 : name of the set to be build:
 307         - "integer" : take the first element from the stack to construct
 308           a set of integer. The stack element should be a string like:
 309            first:last[:step][,first2:last2[:step2][,...]
 310            Ex: 1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8
 311
 312         - "directory" : take the first  element of the stack as the base
 313           directory and construct a set of filename and directly in it.
 314            Each element has the following fields:
 315             - name : file/directory name
 316             - type : "directory" or "file" or "unknown"
 317             - size : size of the file
 318             - date
 319
 320         - "playlist" :
 321           Fields:
 322             - current : 1 if currently selected else 0
 323             - index   : the index value (to be used for example for the
 324                         "delete" control command.
 325             - name
 326             - group   : the group number
 327
 328         - "informations"  : Create informations for  the current playing
 329           stream.
 330           Fields:
 331             - name : Category name
 332             - value : Category value
 333             - info : a new set so you can parse it with another foreach.
 334              Sub fields :
 335                 - name : Info name
 336                 - value Info value
 337         - "hosts" : Create the list of host we are listening.
 338           Fields:
 339             - id  : opaque id
 340             - host:
 341             - ip  :
 342             - port:
 343
 344         - "urls" : Create the list of urls currently available
 345           Fields:
 346             - id    :
 347             - stream: 1 if it's a stream else 0.
 348             - url   :
 349             - mime  :
 350             - protected: 1 if protected else 0.
 351             - used  :
 352         - "connections" : Create the list of current connections.
 353           Fields:
 354             - id : opaque id, used by "control" macro (with close command)
 355             - ip :
 356             - url:
 357             - status: HTTP error code.
 358
 359         - the name of a foreach variable if it's a set of set of value.
 360           Ex :
 361             <vlc id="foreach" param1="cat" param2="informations" />
 362                 <p> <vlc id="value" param1="cat.name" />
 363                 <ul>
 364                 <vlc id="foreach" param1="info" param2="cat.info" />
 365                     <li>
 366                     <vlc id="value" param1="info.name" /> :
 367                             <vlc id="value" param1="info.value" />
 368                     </li>
 369                 <vlc id="end" />
 370                 </ul>
 371             <vlc id="end" />
 372
 373 IV. Conclusion
 374 ##############
 375
 376  Have a look at share/http directory of the VLC sources...
 377
 378  Any remarks, suggestions, ... -> fenrir@via.ecp.fr
 379