modules/luci-base/luasrc/http/protocol.luadoc

   1 ---[[
   2 LuCI http protocol class.
   3
   4 This class contains several functions useful for http message- and content
   5 decoding and to retrive form data from raw http messages.
   6 ]]
   7 module "luci.http.protocol"
   8
   9 ---[[
  10 Extract and split urlencoded data pairs, separated bei either "&" or ";"
  11 from given url or string. Returns a table with urldecoded values.
  12
  13 Simple parameters are stored as string values associated with the parameter
  14 name within the table. Parameters with multiple values are stored as array
  15 containing the corresponding values.
  16
  17 @class                  function
  18 @name                   urldecode_params
  19 @param url              The url or string which contains x-www-urlencoded form data
  20 @param tbl              Use the given table for storing values (optional)
  21 @return                 Table containing the urldecoded parameters
  22 @see                    urlencode_params
  23 ]]
  24
  25 ---[[
  26 Encode each key-value-pair in given table to x-www-urlencoded format,
  27 separated by "&".
  28
  29 Tables are encoded as parameters with multiple values by repeating the
  30 parameter name with each value.
  31
  32 @class                  function
  33 @name                   urlencode_params
  34 @param tbl              Table with the values
  35 @return                 String containing encoded values
  36 @see                    urldecode_params
  37 ]]
  38
  39 ---[[
  40 Decode a mime encoded http message body with multipart/form-data Content-Type.
  41
  42 Stores all extracted data associated with its parameter name
  43 in the params table within the given message object. Multiple parameter
  44 values are stored as tables, ordinary ones as strings.
  45
  46 If an optional file callback function is given then it is feeded with the
  47 file contents chunk by chunk and only the extracted file name is stored
  48 within the params table. The callback function will be called subsequently
  49 with three arguments:
  50  o Table containing decoded (name, file) and raw (headers) mime header data
  51  o String value containing a chunk of the file data
  52  o Boolean which indicates wheather the current chunk is the last one (eof)
  53
  54 @class                  function
  55 @name                   mimedecode_message_body
  56 @param src              Ltn12 source function
  57 @param msg              HTTP message object
  58 @param filecb   File callback function (optional)
  59 @return                 Value indicating successful operation (not nil means "ok")
  60 @return                 String containing the error if unsuccessful
  61 @see                    parse_message_header
  62 ]]
  63
  64 ---[[
  65 Decode an urlencoded http message body with application/x-www-urlencoded
  66 Content-Type.
  67
  68 Stores all extracted data associated with its parameter name in the params
  69 table within the given message object. Multiple parameter values are stored
  70 as tables, ordinary ones as strings.
  71
  72 @class                  function
  73 @name                   urldecode_message_body
  74 @param src              Ltn12 source function
  75 @param msg              HTTP message object
  76 @return                 Value indicating successful operation (not nil means "ok")
  77 @return                 String containing the error if unsuccessful
  78 @see                    parse_message_header
  79 ]]
  80
  81 ---[[
  82 Try to extract and decode a http message body from the given ltn12 source.
  83 This function will examine the Content-Type within the given message object
  84 to select the appropriate content decoder.
  85
  86 Currently the application/x-www-urlencoded and application/form-data
  87 mime types are supported. If the encountered content encoding can't be
  88 handled then the whole message body will be stored unaltered as "content"
  89 property within the given message object.
  90
  91 @class                  function
  92 @name                   parse_message_body
  93 @param src              Ltn12 source function
  94 @param msg              HTTP message object
  95 @param filecb   File data callback (optional, see mimedecode_message_body())
  96 @return                 Value indicating successful operation (not nil means "ok")
  97 @return                 String containing the error if unsuccessful
  98 @see                    parse_message_header
  99 ]]