SoupMessageBody: libsoup Reference Manual

## SoupMessageBody SoupMessageBody — HTTP message body |

## Functions

SoupMessageBody * | soup_message_body_new ()
SoupMessageBody * | soup_message_body_ref ()
void | soup_message_body_unref ()
void | soup_message_body_set_accumulate ()
gboolean | soup_message_body_get_accumulate ()
void | soup_message_body_append ()
void | soup_message_body_append_bytes ()
void | soup_message_body_append_take ()
void | soup_message_body_truncate ()
void | soup_message_body_complete ()
GBytes * | soup_message_body_flatten ()
GBytes * | soup_message_body_get_chunk ()
void | soup_message_body_got_chunk ()
void | soup_message_body_wrote_chunk ()

## Types and Values

enum | SoupMemoryUse
| SoupMessageBody

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