| libsoup Reference Manual | ||||
|---|---|---|---|---|
SoupBuffer;
enum SoupMemoryUse;
SoupBuffer* soup_buffer_new (SoupMemoryUse use,
gconstpointer data,
gsize length);
SoupBuffer* soup_buffer_new_subbuffer (SoupBuffer *parent,
gsize offset,
gsize length);
SoupBuffer* soup_buffer_copy (SoupBuffer *buffer);
void soup_buffer_free (SoupBuffer *buffer);
SoupMessageBody;
SoupMessageBody* soup_message_body_new (void);
void soup_message_body_free (SoupMessageBody *body);
void soup_message_body_append (SoupMessageBody *body,
SoupMemoryUse use,
gconstpointer data,
gsize length);
void soup_message_body_append_buffer (SoupMessageBody *body,
SoupBuffer *buffer);
void soup_message_body_truncate (SoupMessageBody *body);
void soup_message_body_complete (SoupMessageBody *body);
SoupBuffer* soup_message_body_flatten (SoupMessageBody *body);
SoupBuffer* soup_message_body_get_chunk (SoupMessageBody *body,
goffset offset);
SoupMessageBody represents the request or response body of a SoupMessage.
In addition to SoupMessageBody, libsoup also defines a "smaller" data buffer type, SoupBuffer, which is primarily used as a component of SoupMessageBody. In particular, when using chunked encoding to transmit or receive a message, each chunk is represented as a 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.
const char * |
the data |
gsize |
length of data
|
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.
| 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. | |
The caller has allocated the memory for the
SoupBuffer's use; libsoup will assume ownership of it and free it
(with g_free()) when it is done with it.
|
|
| The passed-in data belongs to the caller; the SoupBuffer will copy it into new memory, leaving the caller free to reuse the original memory. | |
The passed-in data belongs to the caller,
but will remain valid for the lifetime of the SoupBuffer. The
difference between this and SOUP_MEMORY_STATIC is that if you copy
a SOUP_MEMORY_TEMPORARY buffer, it will make a copy of the memory
as well, rather than reusing the original memory.
|
SoupBuffer* soup_buffer_new (SoupMemoryUse use, gconstpointer data, gsize length);
Creates a new SoupBuffer containing length bytes from data.
|
how data is to be used by the buffer
|
|
data |
|
length of data
|
Returns : |
the new SoupBuffer. |
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.)
|
the parent SoupBuffer |
|
offset within parent to start at
|
|
number of bytes to copy from parent
|
Returns : |
the new SoupBuffer. |
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.
|
a SoupBuffer |
Returns : |
the new (or newly-reffed) buffer |
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.)
|
a SoupBuffer |
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).
const char * |
the data |
goffset |
length of data
|
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. |
void soup_message_body_append (SoupMessageBody *body, SoupMemoryUse use, gconstpointer data, gsize length);
Appends length bytes from data to body according to use.
|
a SoupMessageBody |
|
how to use data
|
|
data to append |
|
length of data
|
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.)
|
a SoupMessageBody |
|
a SoupBuffer |
void soup_message_body_truncate (SoupMessageBody *body);
Deletes all of the data in body.
|
a SoupMessageBody |
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.
|
a SoupMessageBody |
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).
|
a SoupMessageBody |
Returns : |
a SoupBuffer containing the same data as body.
(You must free this buffer if you do not want it.)
|
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).
|
a SoupMessageBody |
|
an offset |
Returns : |
a SoupBuffer, or NULL.
|