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
  12 from given url or string. Returns a table with urldecoded values.
  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 @class function
  17 @name urldecode_params
  18 @param url      The url or string which contains x-www-urlencoded form data
  19 @param tbl      Use the given table for storing values (optional)
  20 @return         Table containing the urldecoded parameters
  21 @see                    urlencode_params
  22 ]]
  23
  24 ---[[
  25 Encode each key-value-pair in given table to x-www-urlencoded format,
  26
  27 separated by "&". Tables are encoded as parameters with multiple values by
  28 repeating the parameter name with each value.
  29 @class function
  30 @name urlencode_params
  31 @param tbl      Table with the values
  32 @return         String containing encoded values
  33 @see                    urldecode_params
  34 ]]
  35
  36 ---[[
  37 Creates a ltn12 source from the given socket. The source will return it's
  38
  39 data line by line with the trailing \r\n stripped of.
  40 @class function
  41 @name header_source
  42 @param sock     Readable network socket
  43 @return         Ltn12 source function
  44 ]]
  45
  46 ---[[
  47 Decode a mime encoded http message body with multipart/form-data
  48
  49 Content-Type. Stores all extracted data associated with its parameter name
  50 in the params table within the given message object. Multiple parameter
  51 values are stored as tables, ordinary ones as strings.
  52 If an optional file callback function is given then it is feeded with the
  53 file contents chunk by chunk and only the extracted file name is stored
  54 within the params table. The callback function will be called subsequently
  55 with three arguments:
  56  o Table containing decoded (name, file) and raw (headers) mime header data
  57  o String value containing a chunk of the file data
  58  o Boolean which indicates wheather the current chunk is the last one (eof)
  59 @class function
  60 @name mimedecode_message_body
  61 @param src              Ltn12 source function
  62 @param msg              HTTP message object
  63 @param filecb   File callback function (optional)
  64 @return                 Value indicating successful operation (not nil means "ok")
  65 @return                 String containing the error if unsuccessful
  66 @see                            parse_message_header
  67 ]]
  68
  69 ---[[
  70 Decode an urlencoded http message body with application/x-www-urlencoded
  71
  72 Content-Type. Stores all extracted data associated with its parameter name
  73 in the params table within the given message object. Multiple parameter
  74 values are stored as tables, ordinary ones as strings.
  75 @class function
  76 @name urldecode_message_body
  77 @param src      Ltn12 source function
  78 @param msg      HTTP message object
  79 @return         Value indicating successful operation (not nil means "ok")
  80 @return         String containing the error if unsuccessful
  81 @see                    parse_message_header
  82 ]]
  83
  84 ---[[
  85 Try to extract an http message header including information like protocol
  86
  87 version, message headers and resulting CGI environment variables from the
  88 given ltn12 source.
  89 @class function
  90 @name parse_message_header
  91 @param src      Ltn12 source function
  92 @return         HTTP message object
  93 @see                    parse_message_body
  94 ]]
  95
  96 ---[[
  97 Try to extract and decode a http message body from the given ltn12 source.
  98
  99 This function will examine the Content-Type within the given message object
 100 to select the appropriate content decoder.
 101 Currently the application/x-www-urlencoded and application/form-data
 102 mime types are supported. If the encountered content encoding can't be
 103 handled then the whole message body will be stored unaltered as "content"
 104 property within the given message object.
 105 @class function
 106 @name parse_message_body
 107 @param src              Ltn12 source function
 108 @param msg              HTTP message object
 109 @param filecb   File data callback (optional, see mimedecode_message_body())
 110 @return                 Value indicating successful operation (not nil means "ok")
 111 @return                 String containing the error if unsuccessful
 112 @see                            parse_message_header
 113 ]]
 114
 115 ---[[
 116 Table containing human readable messages for several http status codes.
 117
 118 @class table
 119 ]]
 120