manpagez: man pages & more
html files: libsoup-2.4
Home | html | info | man

HTML Form Support

HTML Form Support — HTML form handling

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

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.