SoupBuffer

typedef struct {
	const char *data;
	gsize       length;
} SoupBuffer;

A data buffer, generally used to represent a chunk of a SoupMessageBody.

data is a char because that's generally convenient; in some situations you may need to cast it to guchar or another type.

enum SoupMemoryUse

typedef enum {
	SOUP_MEMORY_STATIC,
	SOUP_MEMORY_TAKE,
	SOUP_MEMORY_COPY,
	SOUP_MEMORY_TEMPORARY
} SoupMemoryUse;

Describes how SoupBuffer should use the data passed in by the caller.

See also soup_buffer_new_with_owner(), which allows to you create a buffer containing data which is owned by another object.

soup_buffer_new ()

SoupBuffer *        soup_buffer_new                     (SoupMemoryUse use,
                                                         gconstpointer data,
                                                         gsize length);

Creates a new SoupBuffer containing length bytes from data.

soup_buffer_new_subbuffer ()

SoupBuffer *        soup_buffer_new_subbuffer           (SoupBuffer *parent,
                                                         gsize offset,
                                                         gsize length);

Creates a new SoupBuffer containing length bytes "copied" from parent starting at offset. (Normally this will not actually copy any data, but will instead simply reference the same data as parent does.)

soup_buffer_new_with_owner ()

SoupBuffer *        soup_buffer_new_with_owner          (gconstpointer data,
                                                         gsize length,
                                                         gpointer owner,
                                                         GDestroyNotify owner_dnotify);

Creates a new SoupBuffer containing length bytes from data. When the SoupBuffer is freed, it will call owner_dnotify, passing owner to it. You must ensure that data will remain valid until owner_dnotify is called.

For example, you could use this to create a buffer containing data returned from libxml without needing to do an extra copy:

1
2
3

xmlDocDumpMemory (doc, &xmlbody, &len);
return soup_buffer_new_with_owner (xmlbody, len, xmlbody,
                                   (GDestroyNotify)xmlFree);

In this example, data and owner are the same, but in other cases they would be different (eg, owner would be a object, and data would be a pointer to one of the object's fields).

soup_buffer_new_take ()

SoupBuffer *        soup_buffer_new_take                (guchar *data,
                                                         gsize length);

Creates a new SoupBuffer containing length bytes from data.

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

Since 2.32

soup_buffer_get_owner ()

gpointer            soup_buffer_get_owner               (SoupBuffer *buffer);

Gets the "owner" object for a buffer created with soup_buffer_new_with_owner().

soup_buffer_get_data ()

void                soup_buffer_get_data                (SoupBuffer *buffer,
                                                         const guint8 **data,
                                                         gsize *length);

This function exists for use by language bindings, because it's not currently possible to get the right effect by annotating the fields of SoupBuffer.

Since 2.32

soup_buffer_copy ()

SoupBuffer *        soup_buffer_copy                    (SoupBuffer *buffer);

Makes a copy of buffer. In reality, SoupBuffer is a refcounted type, and calling soup_buffer_copy() will normally just increment the refcount on buffer and return it. However, if buffer was created with SOUP_MEMORY_TEMPORARY memory, then soup_buffer_copy() will actually return a copy of it, so that the data in the copy will remain valid after the temporary buffer is freed.

soup_buffer_free ()

void                soup_buffer_free                    (SoupBuffer *buffer);

Frees buffer. (In reality, as described in the documentation for soup_buffer_copy(), this is actually an "unref" operation, and may or may not actually free buffer.)

soup_buffer_get_as_bytes ()

GBytes *            soup_buffer_get_as_bytes            (SoupBuffer *buffer);

Creates a GBytes pointing to the same memory as buffer. The GBytes will hold a reference on buffer to ensure that it is not freed while the GBytes is still valid.

Since 2.40

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, unless you set the SOUP_MESSAGE_OVERWRITE_CHUNKS flags. 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).

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.

soup_message_body_free ()

void                soup_message_body_free              (SoupMessageBody *body);

Frees body. You will not normally need to use this, as SoupMessage frees its associated message bodies automatically.

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.

In particular, if you set this flag to FALSE on an "incoming" message body (that is, the "response_body" of a client-side message, or "request_body" of a server-side message), this will cause each chunk of the body to be discarded after its corresponding "got_chunk" signal is emitted. (This is equivalent to setting the deprecated SOUP_MESSAGE_OVERWRITE_CHUNKS flag on the message.)

If you set this flag to FALSE on the "response_body" of a server-side message, it will cause each chunk of the body to be discarded after its corresponding "wrote_chunk" signal is emitted.

If you set the flag to FALSE on the "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 "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. However, if you set the SOUP_MESSAGE_CAN_REBUILD flag on the message, then the chunks will be discarded, and you will be responsible for recreating the request body after the "restarted" signal is emitted.

Since 2.24

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.

Since 2.24

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.

soup_message_body_append_buffer ()

void                soup_message_body_append_buffer     (SoupMessageBody *body,
                                                         SoupBuffer *buffer);

Appends the data from buffer to body. (SoupMessageBody uses SoupBuffers internally, so this is normally a constant-time operation that doesn't actually require copying the data in buffer.)

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

Since 2.32

soup_message_body_truncate ()

void                soup_message_body_truncate          (SoupMessageBody *body);

Deletes all of the data in body.

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.

soup_message_body_flatten ()

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

soup_message_body_get_chunk ()

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

Gets a SoupBuffer 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).

soup_message_body_got_chunk ()

void                soup_message_body_got_chunk         (SoupMessageBody *body,
                                                         SoupBuffer *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_buffer(), 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.

Since 2.24

soup_message_body_wrote_chunk ()

void                soup_message_body_wrote_chunk       (SoupMessageBody *body,
                                                         SoupBuffer *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.

Since 2.24