From 0dea3ebd6785930e513f68c0cf344c4698899271 Mon Sep 17 00:00:00 2001 From: Laurent Aimar Date: Mon, 20 Oct 2003 22:43:36 +0000 Subject: [PATCH] * 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 | 355 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 doc/intf-http.txt diff --git a/doc/intf-http.txt b/doc/intf-http.txt new file mode 100644 index 0000000000..4d25ed397d --- /dev/null +++ b/doc/intf-http.txt @@ -0,0 +1,355 @@ +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 /index.html will be exported as and / 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 : + + + "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: + is correct + Invalid: + <- invalid tag ending + <- 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 + 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
) + 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: + +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 +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: + + + +

Test succeed 1 isn't equal to 2

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

+

    + +
  • + : + +
    • + +
+ + +IV. Conclusion +############## + + Have a look at share/http directory of the VLC sources... + + Any remarks, suggestions, ... -> fenrir@via.ecp.fr + -- GitLab