summaryrefslogtreecommitdiffhomepage
path: root/modules/luci-base/luasrc/http/protocol.luadoc
diff options
context:
space:
mode:
authorJo-Philipp Wich <jow@openwrt.org>2015-01-29 16:26:15 +0100
committerJo-Philipp Wich <jow@openwrt.org>2015-01-29 16:26:46 +0100
commit84346cd178ca0740817edc6f81d8f90e7bc6e00c (patch)
treedd8f6dbb041a2813ac5d91571cdac0b3dc004f1a /modules/luci-base/luasrc/http/protocol.luadoc
parentcf7e2695cc676dff02561a1a45d6de8140170b17 (diff)
Move inline documentation into separate files.
Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>
Diffstat (limited to 'modules/luci-base/luasrc/http/protocol.luadoc')
-rw-r--r--modules/luci-base/luasrc/http/protocol.luadoc142
1 files changed, 142 insertions, 0 deletions
diff --git a/modules/luci-base/luasrc/http/protocol.luadoc b/modules/luci-base/luasrc/http/protocol.luadoc
new file mode 100644
index 0000000000..67a60d9e7a
--- /dev/null
+++ b/modules/luci-base/luasrc/http/protocol.luadoc
@@ -0,0 +1,142 @@
+---[[
+LuCI http protocol class.
+
+This class contains several functions useful for http message- and content
+decoding and to retrive form data from raw http messages.
+]]
+module "luci.http.protocol"
+
+---[[
+Decode an urlencoded string - optionally without decoding
+
+the "+" sign to " " - and return the decoded string.
+@class function
+@name urldecode
+@param str Input string in x-www-urlencoded format
+@param no_plus Don't decode "+" signs to spaces
+@return The decoded string
+@see urlencode
+]]
+
+---[[
+Extract and split urlencoded data pairs, separated bei either "&" or ";"
+
+from given url or string. Returns a table with urldecoded values.
+Simple parameters are stored as string values associated with the parameter
+name within the table. Parameters with multiple values are stored as array
+containing the corresponding values.
+@class function
+@name urldecode_params
+@param url The url or string which contains x-www-urlencoded form data
+@param tbl Use the given table for storing values (optional)
+@return Table containing the urldecoded parameters
+@see urlencode_params
+]]
+
+---[[
+Encode given string to x-www-urlencoded format.
+
+@class function
+@name urlencode
+@param str String to encode
+@return String containing the encoded data
+@see urldecode
+]]
+
+---[[
+Encode each key-value-pair in given table to x-www-urlencoded format,
+
+separated by "&". Tables are encoded as parameters with multiple values by
+repeating the parameter name with each value.
+@class function
+@name urlencode_params
+@param tbl Table with the values
+@return String containing encoded values
+@see urldecode_params
+]]
+
+---[[
+Creates a ltn12 source from the given socket. The source will return it's
+
+data line by line with the trailing \r\n stripped of.
+@class function
+@name header_source
+@param sock Readable network socket
+@return Ltn12 source function
+]]
+
+---[[
+Decode a mime encoded http message body with multipart/form-data
+
+Content-Type. Stores all extracted data associated with its parameter name
+in the params table withing the given message object. Multiple parameter
+values are stored as tables, ordinary ones as strings.
+If an optional file callback function is given then it is feeded with the
+file contents chunk by chunk and only the extracted file name is stored
+within the params table. The callback function will be called subsequently
+with three arguments:
+ o Table containing decoded (name, file) and raw (headers) mime header data
+ o String value containing a chunk of the file data
+ o Boolean which indicates wheather the current chunk is the last one (eof)
+@class function
+@name mimedecode_message_body
+@param src Ltn12 source function
+@param msg HTTP message object
+@param filecb File callback function (optional)
+@return Value indicating successful operation (not nil means "ok")
+@return String containing the error if unsuccessful
+@see parse_message_header
+]]
+
+---[[
+Decode an urlencoded http message body with application/x-www-urlencoded
+
+Content-Type. Stores all extracted data associated with its parameter name
+in the params table withing the given message object. Multiple parameter
+values are stored as tables, ordinary ones as strings.
+@class function
+@name urldecode_message_body
+@param src Ltn12 source function
+@param msg HTTP message object
+@return Value indicating successful operation (not nil means "ok")
+@return String containing the error if unsuccessful
+@see parse_message_header
+]]
+
+---[[
+Try to extract an http message header including information like protocol
+
+version, message headers and resulting CGI environment variables from the
+given ltn12 source.
+@class function
+@name parse_message_header
+@param src Ltn12 source function
+@return HTTP message object
+@see parse_message_body
+]]
+
+---[[
+Try to extract and decode a http message body from the given ltn12 source.
+
+This function will examine the Content-Type within the given message object
+to select the appropriate content decoder.
+Currently the application/x-www-urlencoded and application/form-data
+mime types are supported. If the encountered content encoding can't be
+handled then the whole message body will be stored unaltered as "content"
+property within the given message object.
+@class function
+@name parse_message_body
+@param src Ltn12 source function
+@param msg HTTP message object
+@param filecb File data callback (optional, see mimedecode_message_body())
+@return Value indicating successful operation (not nil means "ok")
+@return String containing the error if unsuccessful
+@see parse_message_header
+]]
+
+---[[
+Table containing human readable messages for several http status codes.
+
+@class table
+]]
+