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: (allow-none): the name of the HTML file upload control, or %NULL
 119  * @filename: (out) (allow-none): return location for the name of the uploaded file, or %NULL
 120  * @content_type: (out) (allow-none): return location for the MIME type of the uploaded file, or %NULL
 121  * @file: (out) (allow-none): return location for the uploaded file data, or %NULL
 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, @content_type and/or @file 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         g_return_val_if_fail (SOUP_IS_MESSAGE (msg), NULL);
 163
 164         multipart = soup_multipart_new_from_message (msg->request_headers,
 165                                                      msg->request_body);
 166         if (!multipart)
 167                 return NULL;
 168
 169         if (filename)
 170                 *filename = NULL;
 171         if (content_type)
 172                 *content_type = NULL;
 173         if (file)
 174                 *file = NULL;
 175
 176         form_data_set = g_hash_table_new_full (g_str_hash, g_str_equal,
 177                                                g_free, g_free);
 178         for (i = 0; i < soup_multipart_get_length (multipart); i++) {
 179                 soup_multipart_get_part (multipart, i, &part_headers, &part_body);
 180                 if (!soup_message_headers_get_content_disposition (
 181                             part_headers, &disposition, &params))
 182                         continue;
 183                 name = g_hash_table_lookup (params, "name");
 184                 if (g_ascii_strcasecmp (disposition, "form-data") != 0 ||
 185                     !name) {
 186                         g_free (disposition);
 187                         g_hash_table_destroy (params);
 188                         continue;
 189                 }
 190
 191                 if (file_control_name && !strcmp (name, file_control_name)) {
 192                         if (filename)
 193                                 *filename = g_strdup (g_hash_table_lookup (params, "filename"));
 194                         if (content_type)
 195                                 *content_type = g_strdup (soup_message_headers_get_content_type (part_headers, NULL));
 196                         if (file)
 197                                 *file = soup_buffer_copy (part_body);
 198                 } else {
 199                         g_hash_table_insert (form_data_set,
 200                                              g_strdup (name),
 201                                              g_strndup (part_body->data,
 202                                                         part_body->length));
 203                 }
 204
 205                 g_free (disposition);
 206                 g_hash_table_destroy (params);
 207         }
 208
 209         soup_multipart_free (multipart);
 210         return form_data_set;
 211 }
 212
 213 static void
 214 append_form_encoded (GString *str, const char *in)
 215 {
 216         const unsigned char *s = (const unsigned char *)in;
 217
 218         while (*s) {
 219                 if (*s == ' ') {
 220                         g_string_append_c (str, '+');
 221                         s++;
 222                 } else if (!g_ascii_isalnum (*s))
 223                         g_string_append_printf (str, "%%%02X", (int)*s++);
 224                 else
 225                         g_string_append_c (str, *s++);
 226         }
 227 }
 228
 229 static void
 230 encode_pair (GString *str, const char *name, const char *value)
 231 {
 232         g_return_if_fail (name != NULL);
 233         g_return_if_fail (value != NULL);
 234
 235         if (str->len)
 236                 g_string_append_c (str, '&');
 237         append_form_encoded (str, name);
 238         g_string_append_c (str, '=');
 239         append_form_encoded (str, value);
 240 }
 241
 242 static void
 243 hash_encode_foreach (gpointer name, gpointer value, gpointer str)
 244 {
 245         encode_pair (str, name, value);
 246 }
 247
 248 /**
 249  * soup_form_encode:
 250  * @first_field: name of the first form field
 251  * @...: value of @first_field, followed by additional field names
 252  * and values, terminated by %NULL.
 253  *
 254  * Encodes the given field names and values into a value of type
 255  * "application/x-www-form-urlencoded", as defined in the HTML 4.01
 256  * spec.
 257  *
 258  * This method requires you to know the names of the form fields (or
 259  * at the very least, the total number of fields) at compile time; for
 260  * working with dynamic forms, use soup_form_encode_hash() or
 261  * soup_form_encode_datalist().
 262  *
 263  * Return value: the encoded form
 264  **/
 265 char *
 266 soup_form_encode (const char *first_field, ...)
 267 {
 268         va_list args;
 269         char *encoded;
 270
 271         va_start (args, first_field);
 272         encoded = soup_form_encode_valist (first_field, args);
 273         va_end (args);
 274
 275         return encoded;
 276 }
 277
 278 /**
 279  * soup_form_encode_hash:
 280  * @form_data_set: (element-type utf8 utf8): a hash table containing
 281  * name/value pairs (as strings)
 282  *
 283  * Encodes @form_data_set into a value of type
 284  * "application/x-www-form-urlencoded", as defined in the HTML 4.01
 285  * spec.
 286  *
 287  * Note that the HTML spec states that "The control names/values are
 288  * listed in the order they appear in the document." Since this method
 289  * takes a hash table, it cannot enforce that; if you care about the
 290  * ordering of the form fields, use soup_form_encode_datalist().
 291  *
 292  * Return value: the encoded form
 293  **/
 294 char *
 295 soup_form_encode_hash (GHashTable *form_data_set)
 296 {
 297         GString *str = g_string_new (NULL);
 298
 299         g_hash_table_foreach (form_data_set, hash_encode_foreach, str);
 300         return g_string_free (str, FALSE);
 301 }
 302
 303 static void
 304 datalist_encode_foreach (GQuark key_id, gpointer value, gpointer str)
 305 {
 306         encode_pair (str, g_quark_to_string (key_id), value);
 307 }
 308
 309 /**
 310  * soup_form_encode_datalist:
 311  * @form_data_set: a datalist containing name/value pairs
 312  *
 313  * Encodes @form_data_set into a value of type
 314  * "application/x-www-form-urlencoded", as defined in the HTML 4.01
 315  * spec. Unlike soup_form_encode_hash(), this preserves the ordering
 316  * of the form elements, which may be required in some situations.
 317  *
 318  * Return value: the encoded form
 319  **/
 320 char *
 321 soup_form_encode_datalist (GData **form_data_set)
 322 {
 323         GString *str = g_string_new (NULL);
 324
 325         g_datalist_foreach (form_data_set, datalist_encode_foreach, str);
 326         return g_string_free (str, FALSE);
 327 }
 328
 329 /**
 330  * soup_form_encode_valist:
 331  * @first_field: name of the first form field
 332  * @args: pointer to additional values, as in soup_form_encode()
 333  *
 334  * See soup_form_encode(). This is mostly an internal method, used by
 335  * various other methods such as soup_uri_set_query_from_fields() and
 336  * soup_form_request_new().
 337  *
 338  * Return value: the encoded form
 339  **/
 340 char *
 341 soup_form_encode_valist (const char *first_field, va_list args)
 342 {
 343         GString *str = g_string_new (NULL);
 344         const char *name, *value;
 345
 346         name = first_field;
 347         value = va_arg (args, const char *);
 348         while (name && value) {
 349                 encode_pair (str, name, value);
 350
 351                 name = va_arg (args, const char *);
 352                 if (name)
 353                         value = va_arg (args, const char *);
 354         }
 355
 356         return g_string_free (str, FALSE);
 357 }
 358
 359 static SoupMessage *
 360 soup_form_request_for_data (const char *method, const char *uri_string,
 361                             char *form_data)
 362 {
 363         SoupMessage *msg;
 364         SoupURI *uri;
 365
 366         uri = soup_uri_new (uri_string);
 367         if (!uri)
 368                 return NULL;
 369
 370         if (!strcmp (method, "GET")) {
 371                 g_free (uri->query);
 372                 uri->query = form_data;
 373
 374                 msg = soup_message_new_from_uri (method, uri);
 375         } else if (!strcmp (method, "POST") || !strcmp (method, "PUT")) {
 376                 msg = soup_message_new_from_uri (method, uri);
 377
 378                 soup_message_set_request (
 379                         msg, SOUP_FORM_MIME_TYPE_URLENCODED,
 380                         SOUP_MEMORY_TAKE,
 381                         form_data, strlen (form_data));
 382         } else {
 383                 g_warning ("invalid method passed to soup_form_request_new");
 384                 g_free (form_data);
 385
 386                 /* Don't crash */
 387                 msg = soup_message_new_from_uri (method, uri);
 388         }
 389         soup_uri_free (uri);
 390
 391         return msg;
 392 }
 393
 394 /**
 395  * soup_form_request_new:
 396  * @method: the HTTP method, either "GET" or "POST"
 397  * @uri: the URI to send the form data to
 398  * @first_field: name of the first form field
 399  * @...: value of @first_field, followed by additional field names
 400  * and values, terminated by %NULL.
 401  *
 402  * Creates a new %SoupMessage and sets it up to send the given data
 403  * to @uri via @method. (That is, if @method is "GET", it will encode
 404  * the form data into @uri's query field, and if @method is "POST", it
 405  * will encode it into the %SoupMessage's request_body.)
 406  *
 407  * Return value: (transfer full): the new %SoupMessage
 408  **/
 409 SoupMessage *
 410 soup_form_request_new (const char *method, const char *uri,
 411                        const char  *first_field, ...)
 412 {
 413         va_list args;
 414         char *form_data;
 415
 416         va_start (args, first_field);
 417         form_data = soup_form_encode_valist (first_field, args);
 418         va_end (args);
 419
 420         return soup_form_request_for_data (method, uri, form_data);
 421 }
 422
 423 /**
 424  * soup_form_request_new_from_hash:
 425  * @method: the HTTP method, either "GET" or "POST"
 426  * @uri: the URI to send the form data to
 427  * @form_data_set: (element-type utf8 utf8): the data to send to @uri
 428  *
 429  * Creates a new %SoupMessage and sets it up to send @form_data_set to
 430  * @uri via @method, as with soup_form_request_new().
 431  *
 432  * Return value: (transfer full): the new %SoupMessage
 433  **/
 434 SoupMessage *
 435 soup_form_request_new_from_hash (const char *method, const char *uri,
 436                                  GHashTable *form_data_set)
 437 {
 438         return soup_form_request_for_data (
 439                 method, uri, soup_form_encode_hash (form_data_set));
 440 }
 441
 442 /**
 443  * soup_form_request_new_from_datalist:
 444  * @method: the HTTP method, either "GET" or "POST"
 445  * @uri: the URI to send the form data to
 446  * @form_data_set: the data to send to @uri
 447  *
 448  * Creates a new %SoupMessage and sets it up to send @form_data_set to
 449  * @uri via @method, as with soup_form_request_new().
 450  *
 451  * Return value: (transfer full): the new %SoupMessage
 452  **/
 453 SoupMessage *
 454 soup_form_request_new_from_datalist (const char *method, const char *uri,
 455                                      GData **form_data_set)
 456 {
 457         return soup_form_request_for_data (
 458                 method, uri, soup_form_encode_datalist (form_data_set));
 459 }
 460
 461 /**
 462  * soup_form_request_new_from_multipart:
 463  * @uri: the URI to send the form data to
 464  * @multipart: a "multipart/form-data" #SoupMultipart
 465  *
 466  * Creates a new %SoupMessage and sets it up to send @multipart to
 467  * @uri via POST.
 468  *
 469  * To send a <literal>"multipart/form-data"</literal> POST, first
 470  * create a #SoupMultipart, using %SOUP_FORM_MIME_TYPE_MULTIPART as
 471  * the MIME type. Then use soup_multipart_append_form_string() and
 472  * soup_multipart_append_form_file() to add the value of each form
 473  * control to the multipart. (These are just convenience methods, and
 474  * you can use soup_multipart_append_part() if you need greater
 475  * control over the part headers.) Finally, call
 476  * soup_form_request_new_from_multipart() to serialize the multipart
 477  * structure and create a #SoupMessage.
 478  *
 479  * Return value: (transfer full): the new %SoupMessage
 480  *
 481  * Since: 2.26
 482  **/
 483 SoupMessage *
 484 soup_form_request_new_from_multipart (const char *uri,
 485                                       SoupMultipart *multipart)
 486 {
 487         SoupMessage *msg;
 488
 489         msg = soup_message_new ("POST", uri);
 490         soup_multipart_to_message (multipart, msg->request_headers,
 491                                    msg->request_body);
 492         return msg;
 493 }