HTML Form Support

## HTML Form Support HTML Form Support — HTML form handling |

## Synopsis

    #include <libsoup/soup.h>

    #define             SOUP_FORM_MIME_TYPE_MULTIPART
    #define             SOUP_FORM_MIME_TYPE_URLENCODED
    GHashTable *        soup_form_decode                    (const char *encoded_form);
    GHashTable *        soup_form_decode_multipart          (SoupMessage *msg,
                                                             const char *file_control_name,
                                                             char **filename,
                                                             char **content_type,
                                                             SoupBuffer **file);
    char *              soup_form_encode                    (const char *first_field,
                                                             ...);
    char *              soup_form_encode_datalist           (GData **form_data_set);
    char *              soup_form_encode_hash               (GHashTable *form_data_set);
    char *              soup_form_encode_valist             (const char *first_field,
                                                             va_list args);
    SoupMessage *       soup_form_request_new               (const char *method,
                                                             const char *uri,
                                                             const char *first_field,
                                                             ...);
    SoupMessage *       soup_form_request_new_from_datalist (const char *method,
                                                             const char *uri,
                                                             GData **form_data_set);
    SoupMessage *       soup_form_request_new_from_hash     (const char *method,
                                                             const char *uri,
                                                             GHashTable *form_data_set);
    SoupMessage *       soup_form_request_new_from_multipart
                                                            (const char *uri,
                                                             SoupMultipart *multipart);

## Description

libsoup contains several help methods for processing HTML forms as defined by the HTML 4.01 specification.

## Details

### SOUP_FORM_MIME_TYPE_MULTIPART

    #define SOUP_FORM_MIME_TYPE_MULTIPART  "multipart/form-data"

A macro containing the value `"multipart/form-data"`; the MIME type used for posting form data that contains files to be uploaded.

Since 2.26

### SOUP_FORM_MIME_TYPE_URLENCODED

    #define SOUP_FORM_MIME_TYPE_URLENCODED "application/x-www-form-urlencoded"

A macro containing the value `"application/x-www-form-urlencoded"`; the default MIME type for POSTing HTML form data.

Since 2.26

### soup_form_decode ()

    GHashTable *        soup_form_decode                    (const char *encoded_form);

Decodes `form`, which is an urlencoded dataset as defined in the HTML 4.01 spec.

`encoded_form` : | data of type "application/x-www-form-urlencoded"
Returns : | a hash table containing the name/value pairs from `encoded_form`, which you can free with `g_hash_table_destroy()`. [element-type utf8 utf8][transfer full]

### soup_form_decode_multipart ()

    GHashTable *        soup_form_decode_multipart          (SoupMessage *msg,
                                                             const char *file_control_name,
                                                             char **filename,
                                                             char **content_type,
                                                             SoupBuffer **file);

Decodes the "multipart/form-data" request in `msg`; this is a convenience method for the case when you have a single file upload control in a form. (Or when you don't have any file upload controls, but are still using "multipart/form-data" anyway.) Pass the name of the file upload control in `file_control_name`, and `soup_form_decode_multipart()` will extract the uploaded file data into `filename`, `content_type`, and `file`. All of the other form control data will be returned (as strings, as with `soup_form_decode()`) in the returned GHashTable.

You may pass `NULL` for `filename`, `content_type` and/or `file` if you do not care about those fields. `soup_form_decode_multipart()` may also return `NULL` in those fields if the client did not provide that information. You must free the returned filename and content-type with `g_free()`, and the returned file data with `soup_buffer_free()`.

If you have a form with more than one file upload control, you will need to decode it manually, using `soup_multipart_new_from_message()` and `soup_multipart_get_part()`.

`msg` : | a SoupMessage containing a "multipart/form-data" request body
`file_control_name` : | the name of the HTML file upload control, or `NULL`. [allow-none]
`filename` : | return location for the name of the uploaded file, or `NULL`. [out][allow-none]
`content_type` : | return location for the MIME type of the uploaded file, or `NULL`. [out][allow-none]
`file` : | return location for the uploaded file data, or `NULL`. [out][allow-none]
Returns : | a hash table containing the name/value pairs (other than `file_control_name`) from `msg`, which you can free with `g_hash_table_destroy()`. On error, it will return `NULL`. [element-type utf8 utf8][transfer full]

Since 2.26

### soup_form_encode ()

    char *              soup_form_encode                    (const char *first_field,
                                                             ...);

Encodes the given field names and values into a value of type "application/x-www-form-urlencoded", as defined in the HTML 4.01 spec.

This method requires you to know the names of the form fields (or at the very least, the total number of fields) at compile time; for working with dynamic forms, use `soup_form_encode_hash()` or `soup_form_encode_datalist()`.

`first_field` : | name of the first form field
`...` : | value of `first_field`, followed by additional field names and values, terminated by `NULL`.
Returns : | the encoded form

### soup_form_encode_datalist ()

    char *              soup_form_encode_datalist           (GData **form_data_set);

Encodes `form_data_set` into a value of type "application/x-www-form-urlencoded", as defined in the HTML 4.01 spec. Unlike `soup_form_encode_hash()`, this preserves the ordering of the form elements, which may be required in some situations.

`form_data_set` : | a datalist containing name/value pairs
Returns : | the encoded form

### soup_form_encode_hash ()

    char *              soup_form_encode_hash               (GHashTable *form_data_set);

Encodes `form_data_set` into a value of type "application/x-www-form-urlencoded", as defined in the HTML 4.01 spec.

Note that the HTML spec states that "The control names/values are listed in the order they appear in the document." Since this method takes a hash table, it cannot enforce that; if you care about the ordering of the form fields, use `soup_form_encode_datalist()`.

`form_data_set` : | a hash table containing name/value pairs (as strings). [element-type utf8 utf8]
Returns : | the encoded form

### soup_form_encode_valist ()

    char *              soup_form_encode_valist             (const char *first_field,
                                                             va_list args);

See `soup_form_encode()`. This is mostly an internal method, used by various other methods such as `soup_uri_set_query_from_fields()` and `soup_form_request_new()`.

`first_field` : | name of the first form field
`args` : | pointer to additional values, as in `soup_form_encode()`
Returns : | the encoded form

### soup_form_request_new ()

    SoupMessage *       soup_form_request_new               (const char *method,
                                                             const char *uri,
                                                             const char *first_field,
                                                             ...);

Creates a new `SoupMessage` and sets it up to send the given data to `uri` via `method`. (That is, if `method` is "GET", it will encode the form data into `uri`'s query field, and if `method` is "POST", it will encode it into the `SoupMessage`'s request_body.)

`method` : | the HTTP method, either "GET" or "POST"
`uri` : | the URI to send the form data to
`first_field` : | name of the first form field
`...` : | value of `first_field`, followed by additional field names and values, terminated by `NULL`.
Returns : | the new `SoupMessage`. [transfer full]

### soup_form_request_new_from_datalist ()

    SoupMessage *       soup_form_request_new_from_datalist (const char *method,
                                                             const char *uri,
                                                             GData **form_data_set);

Creates a new `SoupMessage` and sets it up to send `form_data_set` to `uri` via `method`, as with `soup_form_request_new()`.

`method` : | the HTTP method, either "GET" or "POST"
`uri` : | the URI to send the form data to
`form_data_set` : | the data to send to `uri`
Returns : | the new `SoupMessage`. [transfer full]

### soup_form_request_new_from_hash ()

    SoupMessage *       soup_form_request_new_from_hash     (const char *method,
                                                             const char *uri,
                                                             GHashTable *form_data_set);

Creates a new `SoupMessage` and sets it up to send `form_data_set` to `uri` via `method`, as with `soup_form_request_new()`.

`method` : | the HTTP method, either "GET" or "POST"
`uri` : | the URI to send the form data to
`form_data_set` : | the data to send to `uri`. [element-type utf8 utf8]
Returns : | the new `SoupMessage`. [transfer full]

### soup_form_request_new_from_multipart ()

    SoupMessage *       soup_form_request_new_from_multipart
                                                            (const char *uri,
                                                             SoupMultipart *multipart);

Creates a new `SoupMessage` and sets it up to send `multipart` to `uri` via POST.

To send a `"multipart/form-data"` POST, first create a SoupMultipart, using `SOUP_FORM_MIME_TYPE_MULTIPART` as the MIME type. Then use `soup_multipart_append_form_string()` and `soup_multipart_append_form_file()` to add the value of each form control to the multipart. (These are just convenience methods, and you can use `soup_multipart_append_part()` if you need greater control over the part headers.) Finally, call `soup_form_request_new_from_multipart()` to serialize the multipart structure and create a SoupMessage.

`uri` : | the URI to send the form data to
`multipart` : | a "multipart/form-data" SoupMultipart
Returns : | the new `SoupMessage`. [transfer full]

Since 2.26

## See Also

SoupMultipart