libs/luci-lib-base/luasrc/http.luadoc

   1 ---[[
   2 LuCI Web Framework high-level HTTP functions.
   3 ]]
   4 module "luci.http"
   5
   6 ---[[
   7 Close the HTTP-Connection.
   8
   9 @class                  function
  10 @name                   close
  11 ]]
  12
  13 ---[[
  14 Return the request content if the request was of unknown type.
  15
  16 @class                  function
  17 @name                   content
  18 @return                 HTTP request body
  19 @return                 HTTP request body length
  20 ]]
  21
  22 ---[[
  23 Get a certain HTTP input value or a table of all input values.
  24
  25 @class                  function
  26 @name                   formvalue
  27 @param name             Name of the GET or POST variable to fetch
  28 @param noparse  Don't parse POST data before getting the value
  29 @return                 HTTP input value or table of all input value
  30 ]]
  31
  32 ---[[
  33 Get a table of all HTTP input values with a certain prefix.
  34
  35 @class                  function
  36 @name                   formvaluetable
  37 @param prefix   Prefix
  38 @return                 Table of all HTTP input values with given prefix
  39 ]]
  40
  41 ---[[
  42 Get the value of a certain HTTP-Cookie.
  43
  44 @class                  function
  45 @name                   getcookie
  46 @param name             Cookie Name
  47 @return                 String containing cookie data
  48 ]]
  49
  50 ---[[
  51 Get the value of a certain HTTP environment variable
  52 or the environment table itself.
  53
  54 @class                  function
  55 @name                   getenv
  56 @param name             Environment variable
  57 @return                 HTTP environment value or environment table
  58 ]]
  59
  60 ---[[
  61 Set a handler function for incoming user file uploads.
  62
  63 @class                  function
  64 @name                   setfilehandler
  65 @param callback Handler function
  66 ]]
  67
  68 ---[[
  69 Send a HTTP-Header.
  70
  71 @class                  function
  72 @name                   header
  73 @param key              Header key
  74 @param value    Header value
  75 ]]
  76
  77 ---[[
  78 Set the mime type of following content data.
  79
  80 @class                  function
  81 @name                   prepare_content
  82 @param mime             Mimetype of following content
  83 ]]
  84
  85 ---[[
  86 Get the RAW HTTP input source
  87
  88 @class                  function
  89 @name                   source
  90 @return                 HTTP LTN12 source
  91 ]]
  92
  93 ---[[
  94 Set the HTTP status code and status message.
  95
  96 @class                  function
  97 @name                   status
  98 @param code             Status code
  99 @param message  Status message
 100 ]]
 101
 102 ---[[
 103 Send a chunk of content data to the client.
 104
 105 This function is as a valid LTN12 sink.
 106 If the content chunk is nil this function will automatically invoke close.
 107
 108 @class                  function
 109 @name                   write
 110 @param content  Content chunk
 111 @param src_err  Error object from source (optional)
 112 @see close
 113 ]]
 114
 115 ---[[
 116 Splice data from a filedescriptor to the client.
 117
 118 @class                  function
 119 @name                   splice
 120 @param fp               File descriptor
 121 @param size             Bytes to splice (optional)
 122 ]]
 123
 124 ---[[
 125 Redirects the client to a new URL and closes the connection.
 126
 127 @class                  function
 128 @name                   redirect
 129 @param url              Target URL
 130 ]]
 131
 132 ---[[
 133 Create a querystring out of a table of key - value pairs.
 134
 135 @class                  function
 136 @name                   build_querystring
 137 @param table    Query string source table
 138 @return                 Encoded HTTP query string
 139 ]]
 140
 141 ---[[
 142 Return the URL-decoded equivalent of a string.
 143
 144 @class                  function
 145 @name                   urldecode
 146 @param str              URL-encoded string
 147 @param no_plus  Don't decode + to " "
 148 @return                 URL-decoded string
 149 @see                    urlencode
 150 ]]
 151
 152 ---[[
 153 Return the URL-encoded equivalent of a string.
 154
 155 @class                  function
 156 @name                   urlencode
 157 @param str              Source string
 158 @return                 URL-encoded string
 159 @see                    urldecode
 160 ]]
 161
 162 ---[[
 163 Send the given data as JSON encoded string.
 164
 165 @class                  function
 166 @name                   write_json
 167 @param data             Data to send
 168 ]]
 169
 170 ---[[
 171 Extract and split urlencoded data pairs, separated bei either "&" or ";"
 172 from given url or string. Returns a table with urldecoded values.
 173
 174 Simple parameters are stored as string values associated with the parameter
 175 name within the table. Parameters with multiple values are stored as array
 176 containing the corresponding values.
 177
 178 @class                  function
 179 @name                   urldecode_params
 180 @param url              The url or string which contains x-www-urlencoded form data
 181 @param tbl              Use the given table for storing values (optional)
 182 @return                 Table containing the urldecoded parameters
 183 @see                    urlencode_params
 184 ]]
 185
 186 ---[[
 187 Encode each key-value-pair in given table to x-www-urlencoded format,
 188 separated by "&".
 189
 190 Tables are encoded as parameters with multiple values by repeating the
 191 parameter name with each value.
 192
 193 @class                  function
 194 @name                   urlencode_params
 195 @param tbl              Table with the values
 196 @return                 String containing encoded values
 197 @see                    urldecode_params
 198 ]]
 199
 200 ---[[
 201 Decode a mime encoded http message body with multipart/form-data Content-Type.
 202
 203 Stores all extracted data associated with its parameter name
 204 in the params table within the given message object. Multiple parameter
 205 values are stored as tables, ordinary ones as strings.
 206
 207 If an optional file callback function is given then it is fed with the
 208 file contents chunk by chunk and only the extracted file name is stored
 209 within the params table. The callback function will be called subsequently
 210 with three arguments:
 211  o Table containing decoded (name, file) and raw (headers) mime header data
 212  o String value containing a chunk of the file data
 213  o Boolean which indicates whether the current chunk is the last one (eof)
 214
 215 @class                  function
 216 @name                   mimedecode_message_body
 217 @param src              Ltn12 source function
 218 @param msg              HTTP message object
 219 @param filecb   File callback function (optional)
 220 @return                 Value indicating successful operation (not nil means "ok")
 221 @return                 String containing the error if unsuccessful
 222 @see                    parse_message_header
 223 ]]
 224
 225 ---[[
 226 Decode an urlencoded http message body with application/x-www-urlencoded
 227 Content-Type.
 228
 229 Stores all extracted data associated with its parameter name in the params
 230 table within the given message object. Multiple parameter values are stored
 231 as tables, ordinary ones as strings.
 232
 233 @class                  function
 234 @name                   urldecode_message_body
 235 @param src              Ltn12 source function
 236 @param msg              HTTP message object
 237 @return                 Value indicating successful operation (not nil means "ok")
 238 @return                 String containing the error if unsuccessful
 239 @see                    parse_message_header
 240 ]]
 241
 242 ---[[
 243 Try to extract and decode a http message body from the given ltn12 source.
 244 This function will examine the Content-Type within the given message object
 245 to select the appropriate content decoder.
 246
 247 Currently the application/x-www-urlencoded and application/form-data
 248 mime types are supported. If the encountered content encoding can't be
 249 handled then the whole message body will be stored unaltered as "content"
 250 property within the given message object.
 251
 252 @class                  function
 253 @name                   parse_message_body
 254 @param src              Ltn12 source function
 255 @param msg              HTTP message object
 256 @param filecb   File data callback (optional, see mimedecode_message_body())
 257 @return                 Value indicating successful operation (not nil means "ok")
 258 @return                 String containing the error if unsuccessful
 259 @see                    parse_message_header
 260 ]]