![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
#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);
#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
#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
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() .
|
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
and/or content_type
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
|
filename : |
return location for the name of the uploaded file |
content_type : |
return location for the MIME type of the uploaded file |
file : |
return location for the uploaded file data |
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 .
|
Since 2.26
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 |
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 |
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) |
Returns : | the encoded form |
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 |
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
|
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
|
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
|
Returns : | the new SoupMessage
|
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
|
Since 2.26