![]() |
![]() |
![]() |
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 .
|