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     strsub          : extract substring of ST(1) from character number ST(2)
 183                       to character number ST(3)
 184  * stack manipulation
 185     dup             : duplicate ST(1) on the stack
 186     drop            : remove ST(1)
 187     swap            : swap ST(1) and ST(2)
 188     flush           : empty the stack
 189  * variables manipulation:
 190     store           : store ST(2) in a locale variable named ST(1)
 191     value           : push the value of the local variable named ST(1)
 192     url_extract     : push the value of the ST(1) part of the url parameters.
 193
 194 III. Macros
 195 ###########
 196
 197  1. Macro "control"
 198  ------------------
 199  When asking for a page, you can pass arguments to it through the url.
 200 (eg using a <form>)
 201  Ex: http://host:port/page.html?var=value&var2=value2&...
 202
 203  The "control" macro warm a page to parse such arguments and give control
 204 on which one will be authorized.
 205
 206 param1 of this macro say which command are allowed, if empty then all
 207 commands will work.
 208
 209 Url commands are :
 210
 211   | Name       | arguments    |
 212   -------------------------------------------------------------------------------
 213   | play       | item(integer)| Play the specified item
 214   | stop       |              | Stop
 215   | pause      |              | Pause
 216   | next       |              | Go to the next playlist element
 217   | previous   |              | Got to the previous playlist element
 218   | fullscreen |              | toggle fullscreen
 219   | volume     | value(string)| set volume level (absolute or relative)
 220   | seek       | seek_value   | c.f. notes
 221   | add        | mrl(string)  | Add a mrl to the playlist (with its options)
 222   | delete     | item(integer)| Deletes an (list of) element of the playlist
 223   | keep       | item(integer)| Deletes all but (list of) element of the playlist
 224   | sort       | type,order   | c.f. notes
 225   | empty      |              | Empty the playlist
 226   | close      | id(hexa)     | Close a specific connection
 227   | shutdown   |              | Quit vlc
 228
 229 For example, you  can restrict the execution of the  shutdown command to
 230 protected pages (through a .access) using the control macro in all pages
 231 unprotected.
 232
 233 Notes:
 234  Seek: The seek command is used to seek in current playing stream. the
 235 seek_value argument is a string which represents a relative or absolute
 236 position in the stream: a percentage, or a time.
 237 For examples "+12min 42sec", "01:13:43", "-12%", "42%", or
 238 "1 hour 12 minutes" are valid argument values.
 239  Sort: sorts the playlist by type (string), and with the order (integer).
 240 If order is "0", it is normal order. Otherwise it is reverse order. The
 241 type can be "title", "group", "author".
 242
 243
 244  2. Macro "get"
 245  --------------
 246
 247  This macro will  be replaced by the value of  the configuration variable
 248 which name is stored in param1 and the type is given by param2.
 249
 250  - param1 should be a existing name of a configuration variable
 251  - param2 should be the correct type of this variable. You have
 252         - int
 253         - float
 254         - string
 255
 256 Example:
 257  <vlc id="get" param1="sout" param2="string" />
 258 will be replaced in the output page by the value of sout.
 259
 260  3. Macro "set"
 261  --------------
 262
 263  This macro allow to set the value of a configuration variable.
 264  The name is given by param1 and the type by param2 (like for get).
 265 The value is retrieve from the url using the name in param1.
 266
 267  So if player.html contain <vlc id="set" param1="sout" param2="string" />
 268 and then you can call http://host:ip/player.html?sout=sout_value to
 269 set sout to the value "sout_value"
 270
 271  If the url doesn't contain sout, then nothing is done.
 272
 273  4. Macro "rpn"
 274  -------------
 275  This macro allows you to interpret RPN commands.
 276  See II.
 277
 278
 279  5. Macro "if" "else" "end"
 280  --------------------------
 281  It allows to control the parsing of the html page.
 282
 283  -> if param1 isn't empty, it is first executed with the RPN evaluator.
 284  -> if the first element from the stack isn't 0 the test value is true
 285 else false.
 286
 287 ex:
 288  <vlc id="if" param1="1 2 =" />
 289     <!-- Never reached -->
 290  <vlc id="else" />
 291     <p> Test succeed 1 isn't equal to 2 <p>
 292  <vlc id="end" />
 293
 294  You can also just use "if" and "end".
 295
 296  6. Macro "value"
 297  ----------------
 298  ->if param1 isn't empty, it is first executed with the RPN evaluator.
 299  ->the macro is replaced with the value of the first element of the stack.
 300
 301  Remarks: if  it's in  fact a  locale variable name,  the value  of this
 302 variable will be displayed (instead of it name).
 303
 304  7. Macro "foreach" "end"
 305  ------------------------
 306
 307  param1 : name of the variable used for the loop
 308  param2 : name of the set to be build:
 309         - "integer" : take the first element from the stack to construct
 310           a set of integer. The stack element should be a string like:
 311            first:last[:step][,first2:last2[:step2][,...]
 312            Ex: 1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8
 313
 314         - "directory" : take the first  element of the stack as the base
 315           directory and construct a set of filename and directly in it.
 316            Each element has the following fields:
 317             - name : file/directory name
 318             - type : "directory" or "file" or "unknown"
 319             - size : size of the file
 320             - date
 321
 322         - "playlist" :
 323           Fields:
 324             - current : 1 if currently selected else 0
 325             - index   : the index value (to be used for example for the
 326                         "delete" control command.
 327             - name    : the name of the item (it is equal to uri most of the time).
 328             - uri     : the URI of the item
 329             - group   : the group number
 330
 331         - "informations"  : Create informations for  the current playing
 332           stream.
 333           Fields:
 334             - name : Category name
 335             - value : Category value
 336             - info : a new set so you can parse it with another foreach.
 337              Sub fields :
 338                 - name : Info name
 339                 - value Info value
 340         - "hosts" : Create the list of host we are listening.
 341           Fields:
 342             - id  : opaque id
 343             - host:
 344             - ip  :
 345             - port:
 346
 347         - "urls" : Create the list of urls currently available
 348           Fields:
 349             - id    :
 350             - stream: 1 if it's a stream else 0.
 351             - url   :
 352             - mime  :
 353             - protected: 1 if protected else 0.
 354             - used  :
 355         - "connections" : Create the list of current connections.
 356           Fields:
 357             - id : opaque id, used by "control" macro (with close command)
 358             - ip :
 359             - url:
 360             - status: HTTP error code.
 361
 362         - the name of a foreach variable if it's a set of set of value.
 363           Ex :
 364             <vlc id="foreach" param1="cat" param2="informations" />
 365                 <p> <vlc id="value" param1="cat.name" />
 366                 <ul>
 367                 <vlc id="foreach" param1="info" param2="cat.info" />
 368                     <li>
 369                     <vlc id="value" param1="info.name" /> :
 370                             <vlc id="value" param1="info.value" />
 371                     </li>
 372                 <vlc id="end" />
 373                 </ul>
 374             <vlc id="end" />
 375
 376 IV. Conclusion
 377 ##############
 378
 379  Have a look at share/http directory of the VLC sources...
 380
 381  Any remarks, suggestions, ... -> fenrir@via.ecp.fr
 382