HTML Form Support: libsoup Reference Manual

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

## Functions

GHashTable * | soup_form_decode ()
GHashTable * | soup_form_decode_multipart ()
char * | soup_form_encode ()
char * | soup_form_encode_datalist ()
char * | soup_form_encode_hash ()
char * | soup_form_encode_valist ()
SoupMessage * | soup_form_request_new ()
SoupMessage * | soup_form_request_new_from_datalist ()
SoupMessage * | soup_form_request_new_from_hash ()
SoupMessage * | soup_form_request_new_from_multipart ()

## Types and Values

#define | SOUP_FORM_MIME_TYPE_MULTIPART
#define | SOUP_FORM_MIME_TYPE_URLENCODED

## Includes

    #include <libsoup/soup.h>

## Description

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

## Functions

### 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.

#### Parameters

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 container]

### 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()`.

#### Parameters

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`.

[nullable][element-type utf8 utf8][transfer container]

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()`.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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.)

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

uri | the URI to send the form data to |
multipart | a "multipart/form-data" SoupMultipart |

#### Returns

the new `SoupMessage`.

[transfer full]

Since: 2.26

## Types and Values

### 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

## See Also

SoupMultipart