From 50a3244dfbd0608d1400724a6663a8a6cf82cbfd Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Fri, 11 Jul 2008 11:27:46 +0300 Subject: [PATCH] 1008: document the format of uri.string and uri.post --- src/protocol/uri.h | 32 ++++++++++++++++++++++++++++---- src/viewer/text/form.c | 34 +++++++++++++++++++++++++++++++--- 2 files changed, 59 insertions(+), 7 deletions(-) diff --git a/src/protocol/uri.h b/src/protocol/uri.h index 680c66bd0..74548003a 100644 --- a/src/protocol/uri.h +++ b/src/protocol/uri.h @@ -22,7 +22,13 @@ struct string; /* TODO: We should probably add path+query members instead of data. */ struct uri { - /* The start of the uri (and thus start of the protocol string). */ + /** The start of the URI (and thus start of the protocol %string). + * The format of the whole %string is like: + * "http6://elinks.cz/dir/file?query#frag" ::POST_CHAR post_data "\0" + * + * The post_data is not really %part of the URI but ELinks keeps it + * in the same %string and can then distinguish between cache entries + * for different POST requests. See uri.post for its syntax. */ unsigned char *string; /* The internal type of protocol. Can _never_ be PROTOCOL_UNKNOWN. */ @@ -40,9 +46,27 @@ struct uri { * It can never be NULL but can have zero length. */ unsigned char *data; unsigned char *fragment; - /* @post can contain some special encoded form data, used internally - * to make form data handling more efficient. The data is marked by - * POST_CHAR in the uri string. */ + + /** POST data attached to the URI. If uri.string contains a + * ::POST_CHAR, then @c post points to the following + * character. Otherwise NULL. The syntax of the POST data + * is: + * + * [content-type '\\n'] + * (hexadecimal-byte | ::FILE_CHAR file-name ::FILE_CHAR)* + * + * - If content-type is present, ELinks sends "Content-Type: ", + * content-type, and CRLF in the head of the POST request. + * + * - Each hexadecimal-byte is a byte for the body of the POST + * request. It is encoded as two lower-case hexadecimal + * digits, most significant first. For example, "0a" for + * ::ASCII_LF. + * + * - file-name is the name of a file that ELinks should send + * to the server. It is in the charset accepted by open(), + * and not encoded. Therefore, file names that contain + * ::FILE_CHAR cannot be used. */ unsigned char *post; /* @protocollen should only be usable if @protocol is either diff --git a/src/viewer/text/form.c b/src/viewer/text/form.c index c3868bd1d..49a95251a 100644 --- a/src/viewer/text/form.c +++ b/src/viewer/text/form.c @@ -869,7 +869,35 @@ add_boundary(struct string *data, struct boundary_info *boundary) } -/** @todo FIXME: shouldn't we encode data at send time (in http.c) ? --Zas */ +/** Format a multipart/form-data body for a POST request. + * + * @param ses + * Display an info_box() in the terminal of this session if an error + * occurs. + * @param[in] l + * List of values to be sent to the server. + * @param[out] data + * Append the body here. This is in the same format as uri.post, + * except this never has a Content-Type at the beginning, and the + * literal parts are not encoded in hexadecimal. Therefore the + * result would be ambiguous without @a bfs. + * @param[out] boundary + * A random boundary %string, and a list of offsets where the + * boundary was used, so that the caller can in principle change the + * %string and update all of its uses if the original one conflicts + * with some of the submitted values. However, the caller does not + * do that nowadays because reading through the attached files would + * be too expensive. It just assumes the boundary is random enough. + * @param[out] bfs + * List of offsets of names of files to be uploaded. This is how + * the caller knows which occurrences of ::FILE_CHAR in @a data + * should be encoded and which ones should not. + * @param[in] cp_from + * Codepage of the submitted-value strings in @a l. + * @param[in] cp_to + * Codepage wanted by the server. + * + * @todo FIXME: shouldn't we encode data at send time (in http.c) ? --Zas */ static void encode_multipart(struct session *ses, LIST_OF(struct submitted_value) *l, struct string *data, struct boundary_info *boundary, @@ -888,9 +916,9 @@ encode_multipart(struct session *ses, LIST_OF(struct submitted_value) *l, add_crlf_to_string(data); /** @bug FIXME: name is not encoded. - * from RFC 1867: + * From RFC 1867: * multipart/form-data contains a series of parts. - * Each part is expected to contain a content-disposition + * Each %part is expected to contain a content-disposition * header where the value is "form-data" and a name attribute * specifies the field name within the form, * e.g., 'content-disposition: form-data; name="xxxxx"',