Move inline documentation into separate files.

Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>

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 000000000..67a60d9e7
--- /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
+]]
+