SoupMessageBody

SoupMessageBody — HTTP message body

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── SoupMessageBody

Includes

#include <libsoup/soup.h>

Description

SoupMessageBody represents the request or response body of a SoupMessage.

Functions

soup_message_body_new ()

SoupMessageBody *
soup_message_body_new (void);

Creates a new SoupMessageBody. SoupMessage uses this internally; you will not normally need to call it yourself.

Returns

a new SoupMessageBody.


soup_message_body_ref ()

SoupMessageBody *
soup_message_body_ref (SoupMessageBody *body);

Atomically increments the reference count of body by one.

Parameters

body

a SoupMessageBody

 

Returns

the passed in SoupMessageBody


soup_message_body_unref ()

void
soup_message_body_unref (SoupMessageBody *body);

Atomically decrements the reference count of body by one. When the reference count reaches zero, the resources allocated by body are freed

Parameters

body

a SoupMessageBody

 

soup_message_body_set_accumulate ()

void
soup_message_body_set_accumulate (SoupMessageBody *body,
                                  gboolean accumulate);

Sets or clears the accumulate flag on body . (The default value is TRUE.) If set to FALSE, body 's data field will not be filled in after the body is fully sent/received, and the chunks that make up body may be discarded when they are no longer needed.

If you set the flag to FALSE on the SoupMessage request_body of a client-side message, it will block the accumulation of chunks into body 's data field, but it will not normally cause the chunks to be discarded after being written like in the server-side SoupMessage response_body case, because the request body needs to be kept around in case the request needs to be sent a second time due to redirection or authentication.

Parameters

body

a SoupMessageBody

 

accumulate

whether or not to accumulate body chunks in body

 

soup_message_body_get_accumulate ()

gboolean
soup_message_body_get_accumulate (SoupMessageBody *body);

Gets the accumulate flag on body ; see soup_message_body_set_accumulate() for details.

Parameters

body

a SoupMessageBody

 

Returns

the accumulate flag for body .


soup_message_body_append ()

void
soup_message_body_append (SoupMessageBody *body,
                          SoupMemoryUse use,
                          gconstpointer data,
                          gsize length);

Appends length bytes from data to body according to use .

Parameters

body

a SoupMessageBody

 

use

how to use data

 

data

data to append.

[array length=length][element-type guint8]

length

length of data

 

soup_message_body_append_bytes ()

void
soup_message_body_append_bytes (SoupMessageBody *body,
                                GBytes *buffer);

Appends the data from buffer to body .

Parameters

body

a SoupMessageBody

 

buffer

a GBytes

 

soup_message_body_append_take ()

void
soup_message_body_append_take (SoupMessageBody *body,
                               guchar *data,
                               gsize length);

Appends length bytes from data to body .

This function is exactly equivalent to soup_message_body_append() with SOUP_MEMORY_TAKE as second argument; it exists mainly for convenience and simplifying language bindings.

[rename-to soup_message_body_append]

Parameters

body

a SoupMessageBody

 

data

data to append.

[array length=length][transfer full]

length

length of data

 

soup_message_body_truncate ()

void
soup_message_body_truncate (SoupMessageBody *body);

Deletes all of the data in body .

Parameters

body

a SoupMessageBody

 

soup_message_body_complete ()

void
soup_message_body_complete (SoupMessageBody *body);

Tags body as being complete; Call this when using chunked encoding after you have appended the last chunk.

Parameters

body

a SoupMessageBody

 

soup_message_body_flatten ()

GBytes *
soup_message_body_flatten (SoupMessageBody *body);

Fills in body 's data field with a buffer containing all of the data in body (plus an additional '\0' byte not counted by body 's length field).

Return: (transfer full): a GBytes containing the same data as body . (You must g_bytes_unref() this if you do not want it.)

Parameters

body

a SoupMessageBody

 

soup_message_body_get_chunk ()

GBytes *
soup_message_body_get_chunk (SoupMessageBody *body,
                             goffset offset);

Gets a GBytes containing data from body starting at offset . The size of the returned chunk is unspecified. You can iterate through the entire body by first calling soup_message_body_get_chunk() with an offset of 0, and then on each successive call, increment the offset by the length of the previously-returned chunk.

If offset is greater than or equal to the total length of body , then the return value depends on whether or not soup_message_body_complete() has been called or not; if it has, then soup_message_body_get_chunk() will return a 0-length chunk (indicating the end of body ). If it has not, then soup_message_body_get_chunk() will return NULL (indicating that body may still potentially have more data, but that data is not currently available).

Parameters

body

a SoupMessageBody

 

offset

an offset

 

Returns

a GBytes, or NULL.

[nullable]


soup_message_body_got_chunk ()

void
soup_message_body_got_chunk (SoupMessageBody *body,
                             GBytes *chunk);

Handles the SoupMessageBody part of receiving a chunk of data from the network. Normally this means appending chunk to body , exactly as with soup_message_body_append_bytes(), but if you have set body 's accumulate flag to FALSE, then that will not happen.

This is a low-level method which you should not normally need to use.

Parameters

body

a SoupMessageBody

 

chunk

a GBytes received from the network

 

soup_message_body_wrote_chunk ()

void
soup_message_body_wrote_chunk (SoupMessageBody *body,
                               GBytes *chunk);

Handles the SoupMessageBody part of writing a chunk of data to the network. Normally this is a no-op, but if you have set body 's accumulate flag to FALSE, then this will cause chunk to be discarded to free up memory.

This is a low-level method which you should not need to use, and there are further restrictions on its proper use which are not documented here.

Parameters

body

a SoupMessageBody

 

chunk

a GBytes returned from soup_message_body_get_chunk()

 

Types and Values

enum SoupMemoryUse

The lifetime of the memory being passed.

Members

SOUP_MEMORY_STATIC

The memory is statically allocated and constant; libsoup can use the passed-in buffer directly and not need to worry about it being modified or freed.

 

SOUP_MEMORY_TAKE

The caller has allocated the memory and libsoup will assume ownership of it and free it with g_free().

 

SOUP_MEMORY_COPY

The passed-in data belongs to the caller and libsoup will copy it into new memory leaving the caller free to reuse the original memory.

 

SoupMessageBody

typedef struct {
	const char *data;
	goffset     length;
} SoupMessageBody;

A SoupMessage request or response body.

Note that while length always reflects the full length of the message body, data is normally NULL, and will only be filled in after soup_message_body_flatten() is called. For client-side messages, this automatically happens for the response body after it has been fully read. Likewise, for server-side messages, the request body is automatically filled in after being read.

As an added bonus, when data is filled in, it is always terminated with a '\0' byte (which is not reflected in length ).

Members

const char *data;

the data.

[array length=length][element-type guint8]

goffset length;

length of data

 

See Also

SoupMessage