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