luci-base: refactor luci.http

[project/luci.git] / modules / luci-base / luasrc / http / protocol.luadoc

diff --git a/modules/luci-base/luasrc/http/protocol.luadoc b/modules/luci-base/luasrc/http/protocol.luadoc
index 19a0a34..0c9ff6f 100644 (file)
--- a/modules/luci-base/luasrc/http/protocol.luadoc
+++ b/modules/luci-base/luasrc/http/protocol.luadoc
@@ -7,70 +7,42 @@ decoding and to retrive form data from raw http messages.
 module "luci.http.protocol"
 
 ---[[
 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 ";"
 Extract and split urlencoded data pairs, separated bei either "&" or ";"

-

 from given url or string. Returns a table with urldecoded values.
 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.
 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
+@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 each key-value-pair in given table to x-www-urlencoded format,
 ]]
 
 ---[[
 Encode each key-value-pair in given table to x-www-urlencoded format,

+separated by "&".

 
 

-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
-]]
+Tables are encoded as parameters with multiple values by repeating the
+parameter name with each value.

 
 

----[[
-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
+@class                         function
+@name                  urlencode_params
+@param tbl             Table with the values
+@return                        String containing encoded values
+@see                   urldecode_params

 ]]
 
 ---[[
 ]]
 
 ---[[

-Decode a mime encoded http message body with multipart/form-data
+Decode a mime encoded http message body with multipart/form-data Content-Type.

 
 

-Content-Type. Stores all extracted data associated with its parameter name
+Stores all extracted data associated with its parameter name

 in the params table within the given message object. Multiple parameter
 values are stored as tables, ordinary ones as strings.
 in the params table within 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
 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


@@ -78,65 +50,50 @@ 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)
  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
+
+@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
 @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
+@see                   parse_message_header

 ]]
 
 ---[[
 Decode an urlencoded http message body with application/x-www-urlencoded
 ]]
 
 ---[[
 Decode an urlencoded http message body with application/x-www-urlencoded

+Content-Type.

 
 

-Content-Type. Stores all extracted data associated with its parameter name
-in the params table within 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
-]]
+Stores all extracted data associated with its parameter name in the params
+table within the given message object. Multiple parameter values are stored
+as tables, ordinary ones as strings.

 
 

----[[
-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
+@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 and decode a http message body from the given ltn12 source.
 ]]
 
 ---[[
 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.
 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.
 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
+
+@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
 @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
+@see                   parse_message_header

 ]]
 ]]

-