libsoup/soup-form.c

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /* soup-form.c : utility functions for HTML forms */
   3
   4 /*
   5  * Copyright 2008 Red Hat, Inc.
   6  */
   7
   8 #ifdef HAVE_CONFIG_H
   9 #include <config.h>
  10 #endif
  11
  12 #include <string.h>
  13
  14 #include "soup-form.h"
  15 #include "soup-message.h"
  16 #include "soup-uri.h"
  17
  18 /**
  19  * SECTION:soup-form
  20  * @short_description: HTML form handling
  21  * @see_also: #SoupMultipart
  22  *
  23  * libsoup contains several help methods for processing HTML forms as
  24  * defined by <ulink
  25  * url="http://www.w3.org/TR/html401/interact/forms.html#h-17.13">the
  26  * HTML 4.01 specification</ulink>.
  27  **/
  28
  29 /**
  30  * SOUP_FORM_MIME_TYPE_URLENCODED:
  31  *
  32  * A macro containing the value
  33  * <literal>"application/x-www-form-urlencoded"</literal>; the default
  34  * MIME type for POSTing HTML form data.
  35  *
  36  * Since: 2.26
  37  **/
  38
  39 /**
  40  * SOUP_FORM_MIME_TYPE_MULTIPART:
  41  *
  42  * A macro containing the value
  43  * <literal>"multipart/form-data"</literal>; the MIME type used for
  44  * posting form data that contains files to be uploaded.
  45  *
  46  * Since: 2.26
  47  **/
  48
  49 #define XDIGIT(c) ((c) <= '9' ? (c) - '0' : ((c) & 0x4F) - 'A' + 10)
  50 #define HEXCHAR(s) ((XDIGIT (s[1]) << 4) + XDIGIT (s[2]))
  51
  52 static gboolean
  53 form_decode (char *part)
  54 {
  55         unsigned char *s, *d;
  56
  57         s = d = (unsigned char *)part;
  58         do {
  59                 if (*s == '%') {
  60                         if (!g_ascii_isxdigit (s[1]) ||
  61                             !g_ascii_isxdigit (s[2]))
  62                                 return FALSE;
  63                         *d++ = HEXCHAR (s);
  64                         s += 2;
  65                 } else if (*s == '+')
  66                         *d++ = ' ';
  67                 else
  68                         *d++ = *s;
  69         } while (*s++);
  70
  71         return TRUE;
  72 }
  73
  74 /**
  75  * soup_form_decode:
  76  * @encoded_form: data of type "application/x-www-form-urlencoded"
  77  *
  78  * Decodes @form, which is an urlencoded dataset as defined in the
  79  * HTML 4.01 spec.
  80  *
  81  * Return value: (element-type utf8 utf8) (transfer full): a hash
  82  * table containing the name/value pairs from @encoded_form, which you
  83  * can free with g_hash_table_destroy().
  84  **/
  85 GHashTable *
  86 soup_form_decode (const char *encoded_form)
  87 {
  88         GHashTable *form_data_set;
  89         char **pairs, *eq, *name, *value;
  90         int i;
  91
  92         form_data_set = g_hash_table_new_full (g_str_hash, g_str_equal,
  93                                                g_free, NULL);
  94         pairs = g_strsplit (encoded_form, "&", -1);
  95         for (i = 0; pairs[i]; i++) {
  96                 name = pairs[i];
  97                 eq = strchr (name, '=');
  98                 if (eq) {
  99                         *eq = '\0';
 100                         value = eq + 1;
 101                 } else
 102                         value = NULL;
 103                 if (!value || !form_decode (name) || !form_decode (value)) {
 104                         g_free (name);
 105                         continue;
 106                 }
 107
 108                 g_hash_table_replace (form_data_set, name, value);
 109         }
 110         g_free (pairs);
 111
 112         return form_data_set;
 113 }
 114
 115 /**
 116  * soup_form_decode_multipart:
 117  * @msg: a #SoupMessage containing a "multipart/form-data" request body
 118  * @file_control_name: the name of the HTML file upload control, or %NULL
 119  * @filename: (out): return location for the name of the uploaded file
 120  * @content_type: (out): return location for the MIME type of the uploaded file
 121  * @file: (out): return location for the uploaded file data
 122  *
 123  * Decodes the "multipart/form-data" request in @msg; this is a
 124  * convenience method for the case when you have a single file upload
 125  * control in a form. (Or when you don't have any file upload
 126  * controls, but are still using "multipart/form-data" anyway.) Pass
 127  * the name of the file upload control in @file_control_name, and
 128  * soup_form_decode_multipart() will extract the uploaded file data
 129  * into @filename, @content_type, and @file. All of the other form
 130  * control data will be returned (as strings, as with
 131  * soup_form_decode()) in the returned #GHashTable.
 132  *
 133  * You may pass %NULL for @filename and/or @content_type if you do not
 134  * care about those fields. soup_form_decode_multipart() may also
 135  * return %NULL in those fields if the client did not provide that
 136  * information. You must free the returned filename and content-type
 137  * with g_free(), and the returned file data with soup_buffer_free().
 138  *
 139  * If you have a form with more than one file upload control, you will
 140  * need to decode it manually, using soup_multipart_new_from_message()
 141  * and soup_multipart_get_part().
 142  *
 143  * Return value: (element-type utf8 utf8) (transfer full): a hash
 144  * table containing the name/value pairs (other than
 145  * @file_control_name) from @msg, which you can free with
 146  * g_hash_table_destroy(). On error, it will return %NULL.
 147  *
 148  * Since: 2.26
 149  **/
 150 GHashTable *
 151 soup_form_decode_multipart (SoupMessage *msg, const char *file_control_name,
 152                             char **filename, char **content_type,
 153                             SoupBuffer **file)
 154 {
 155         SoupMultipart *multipart;
 156         GHashTable *form_data_set, *params;
 157         SoupMessageHeaders *part_headers;
 158         SoupBuffer *part_body;
 159         char *disposition, *name;
 160         int i;
 161
 162         multipart = soup_multipart_new_from_message (msg->request_headers,
 163                                                      msg->request_body);
 164         if (!multipart)
 165                 return NULL;
 166
 167         if (filename)
 168                 *filename = NULL;
 169         if (content_type)
 170                 *content_type = NULL;
 171         *file = NULL;
 172
 173         form_data_set = g_hash_table_new_full (g_str_hash, g_str_equal,
 174                                                g_free, g_free);
 175         for (i = 0; i < soup_multipart_get_length (multipart); i++) {
 176                 soup_multipart_get_part (multipart, i, &part_headers, &part_body);
 177                 if (!soup_message_headers_get_content_disposition (
 178                             part_headers, &disposition, &params))
 179                         continue;
 180                 name = g_hash_table_lookup (params, "name");
 181                 if (g_ascii_strcasecmp (disposition, "form-data") != 0 ||
 182                     !name) {
 183                         g_free (disposition);
 184                         g_hash_table_destroy (params);
 185                         continue;
 186                 }
 187
 188                 if (!strcmp (name, file_control_name)) {
 189                         if (filename)
 190                                 *filename = g_strdup (g_hash_table_lookup (params, "filename"));
 191                         if (content_type)
 192                                 *content_type = g_strdup (soup_message_headers_get_content_type (part_headers, NULL));
 193                         if (file)
 194                                 *file = soup_buffer_copy (part_body);
 195                 } else {
 196                         g_hash_table_insert (form_data_set,
 197                                              g_strdup (name),
 198                                              g_strndup (part_body->data,
 199                                                         part_body->length));
 200                 }
 201
 202                 g_free (disposition);
 203                 g_hash_table_destroy (params);
 204         }
 205
 206         soup_multipart_free (multipart);
 207         return form_data_set;
 208 }
 209
 210 static void
 211 append_form_encoded (GString *str, const char *in)
 212 {
 213         const unsigned char *s = (const unsigned char *)in;
 214
 215         while (*s) {
 216                 if (*s == ' ') {
 217                         g_string_append_c (str, '+');
 218                         s++;
 219                 } else if (!g_ascii_isalnum (*s))
 220                         g_string_append_printf (str, "%%%02X", (int)*s++);
 221                 else
 222                         g_string_append_c (str, *s++);
 223         }
 224 }
 225
 226 static void
 227 encode_pair (GString *str, const char *name, const char *value)
 228 {
 229         g_return_if_fail (name != NULL);
 230         g_return_if_fail (value != NULL);
 231
 232         if (str->len)
 233                 g_string_append_c (str, '&');
 234         append_form_encoded (str, name);
 235         g_string_append_c (str, '=');
 236         append_form_encoded (str, value);
 237 }
 238
 239 static void
 240 hash_encode_foreach (gpointer name, gpointer value, gpointer str)
 241 {
 242         encode_pair (str, name, value);
 243 }
 244
 245 /**
 246  * soup_form_encode:
 247  * @first_field: name of the first form field
 248  * @...: value of @first_field, followed by additional field names
 249  * and values, terminated by %NULL.
 250  *
 251  * Encodes the given field names and values into a value of type
 252  * "application/x-www-form-urlencoded", as defined in the HTML 4.01
 253  * spec.
 254  *
 255  * This method requires you to know the names of the form fields (or
 256  * at the very least, the total number of fields) at compile time; for
 257  * working with dynamic forms, use soup_form_encode_hash() or
 258  * soup_form_encode_datalist().
 259  *
 260  * Return value: the encoded form
 261  **/
 262 char *
 263 soup_form_encode (const char *first_field, ...)
 264 {
 265         va_list args;
 266         char *encoded;
 267
 268         va_start (args, first_field);
 269         encoded = soup_form_encode_valist (first_field, args);
 270         va_end (args);
 271
 272         return encoded;
 273 }
 274
 275 /**
 276  * soup_form_encode_hash:
 277  * @form_data_set: (element-type utf8 utf8): a hash table containing
 278  * name/value pairs (as strings)
 279  *
 280  * Encodes @form_data_set into a value of type
 281  * "application/x-www-form-urlencoded", as defined in the HTML 4.01
 282  * spec.
 283  *
 284  * Note that the HTML spec states that "The control names/values are
 285  * listed in the order they appear in the document." Since this method
 286  * takes a hash table, it cannot enforce that; if you care about the
 287  * ordering of the form fields, use soup_form_encode_datalist().
 288  *
 289  * Return value: the encoded form
 290  **/
 291 char *
 292 soup_form_encode_hash (GHashTable *form_data_set)
 293 {
 294         GString *str = g_string_new (NULL);
 295
 296         g_hash_table_foreach (form_data_set, hash_encode_foreach, str);
 297         return g_string_free (str, FALSE);
 298 }
 299
 300 static void
 301 datalist_encode_foreach (GQuark key_id, gpointer value, gpointer str)
 302 {
 303         encode_pair (str, g_quark_to_string (key_id), value);
 304 }
 305
 306 /**
 307  * soup_form_encode_datalist:
 308  * @form_data_set: a datalist containing name/value pairs
 309  *
 310  * Encodes @form_data_set into a value of type
 311  * "application/x-www-form-urlencoded", as defined in the HTML 4.01
 312  * spec. Unlike soup_form_encode_hash(), this preserves the ordering
 313  * of the form elements, which may be required in some situations.
 314  *
 315  * Return value: the encoded form
 316  **/
 317 char *
 318 soup_form_encode_datalist (GData **form_data_set)
 319 {
 320         GString *str = g_string_new (NULL);
 321
 322         g_datalist_foreach (form_data_set, datalist_encode_foreach, str);
 323         return g_string_free (str, FALSE);
 324 }
 325
 326 /**
 327  * soup_form_encode_valist:
 328  * @first_field: name of the first form field
 329  * @args: pointer to additional values, as in soup_form_encode()
 330  *
 331  * See soup_form_encode(). This is mostly an internal method, used by
 332  * various other methods such as soup_uri_set_query_from_fields() and
 333  * soup_form_request_new().
 334  *
 335  * Return value: the encoded form
 336  **/
 337 char *
 338 soup_form_encode_valist (const char *first_field, va_list args)
 339 {
 340         GString *str = g_string_new (NULL);
 341         const char *name, *value;
 342
 343         name = first_field;
 344         value = va_arg (args, const char *);
 345         while (name && value) {
 346                 encode_pair (str, name, value);
 347
 348                 name = va_arg (args, const char *);
 349                 if (name)
 350                         value = va_arg (args, const char *);
 351         }
 352
 353         return g_string_free (str, FALSE);
 354 }
 355
 356 static SoupMessage *
 357 soup_form_request_for_data (const char *method, const char *uri_string,
 358                             char *form_data)
 359 {
 360         SoupMessage *msg;
 361         SoupURI *uri;
 362
 363         uri = soup_uri_new (uri_string);
 364         if (!uri)
 365                 return NULL;
 366
 367         if (!strcmp (method, "GET")) {
 368                 g_free (uri->query);
 369                 uri->query = form_data;
 370
 371                 msg = soup_message_new_from_uri (method, uri);
 372         } else if (!strcmp (method, "POST") || !strcmp (method, "PUT")) {
 373                 msg = soup_message_new_from_uri (method, uri);
 374
 375                 soup_message_set_request (
 376                         msg, SOUP_FORM_MIME_TYPE_URLENCODED,
 377                         SOUP_MEMORY_TAKE,
 378                         form_data, strlen (form_data));
 379         } else {
 380                 g_warning ("invalid method passed to soup_form_request_new");
 381                 g_free (form_data);
 382
 383                 /* Don't crash */
 384                 msg = soup_message_new_from_uri (method, uri);
 385         }
 386         soup_uri_free (uri);
 387
 388         return msg;
 389 }
 390
 391 /**
 392  * soup_form_request_new:
 393  * @method: the HTTP method, either "GET" or "POST"
 394  * @uri: the URI to send the form data to
 395  * @first_field: name of the first form field
 396  * @...: value of @first_field, followed by additional field names
 397  * and values, terminated by %NULL.
 398  *
 399  * Creates a new %SoupMessage and sets it up to send the given data
 400  * to @uri via @method. (That is, if @method is "GET", it will encode
 401  * the form data into @uri's query field, and if @method is "POST", it
 402  * will encode it into the %SoupMessage's request_body.)
 403  *
 404  * Return value: (transfer full): the new %SoupMessage
 405  **/
 406 SoupMessage *
 407 soup_form_request_new (const char *method, const char *uri,
 408                        const char  *first_field, ...)
 409 {
 410         va_list args;
 411         char *form_data;
 412
 413         va_start (args, first_field);
 414         form_data = soup_form_encode_valist (first_field, args);
 415         va_end (args);
 416
 417         return soup_form_request_for_data (method, uri, form_data);
 418 }
 419
 420 /**
 421  * soup_form_request_new_from_hash:
 422  * @method: the HTTP method, either "GET" or "POST"
 423  * @uri: the URI to send the form data to
 424  * @form_data_set: (element-type utf8 utf8): the data to send to @uri
 425  *
 426  * Creates a new %SoupMessage and sets it up to send @form_data_set to
 427  * @uri via @method, as with soup_form_request_new().
 428  *
 429  * Return value: (transfer full): the new %SoupMessage
 430  **/
 431 SoupMessage *
 432 soup_form_request_new_from_hash (const char *method, const char *uri,
 433                                  GHashTable *form_data_set)
 434 {
 435         return soup_form_request_for_data (
 436                 method, uri, soup_form_encode_hash (form_data_set));
 437 }
 438
 439 /**
 440  * soup_form_request_new_from_datalist:
 441  * @method: the HTTP method, either "GET" or "POST"
 442  * @uri: the URI to send the form data to
 443  * @form_data_set: the data to send to @uri
 444  *
 445  * Creates a new %SoupMessage and sets it up to send @form_data_set to
 446  * @uri via @method, as with soup_form_request_new().
 447  *
 448  * Return value: (transfer full): the new %SoupMessage
 449  **/
 450 SoupMessage *
 451 soup_form_request_new_from_datalist (const char *method, const char *uri,
 452                                      GData **form_data_set)
 453 {
 454         return soup_form_request_for_data (
 455                 method, uri, soup_form_encode_datalist (form_data_set));
 456 }
 457
 458 /**
 459  * soup_form_request_new_from_multipart:
 460  * @uri: the URI to send the form data to
 461  * @multipart: a "multipart/form-data" #SoupMultipart
 462  *
 463  * Creates a new %SoupMessage and sets it up to send @multipart to
 464  * @uri via POST.
 465  *
 466  * To send a <literal>"multipart/form-data"</literal> POST, first
 467  * create a #SoupMultipart, using %SOUP_FORM_MIME_TYPE_MULTIPART as
 468  * the MIME type. Then use soup_multipart_append_form_string() and
 469  * soup_multipart_append_form_file() to add the value of each form
 470  * control to the multipart. (These are just convenience methods, and
 471  * you can use soup_multipart_append_part() if you need greater
 472  * control over the part headers.) Finally, call
 473  * soup_form_request_new_from_multipart() to serialize the multipart
 474  * structure and create a #SoupMessage.
 475  *
 476  * Return value: (transfer full): the new %SoupMessage
 477  *
 478  * Since: 2.26
 479  **/
 480 SoupMessage *
 481 soup_form_request_new_from_multipart (const char *uri,
 482                                       SoupMultipart *multipart)
 483 {
 484         SoupMessage *msg;
 485
 486         msg = soup_message_new ("POST", uri);
 487         soup_multipart_to_message (multipart, msg->request_headers,
 488                                    msg->request_body);
 489         return msg;
 490 }