Message.setChunkAllocator

Sets an alternate chunk-allocation function to use when reading @msg's body when using the traditional (ie, non-#SoupRequest<!-- -->-based) API. Every time data is available to read, libsoup will call @allocator, which should return a #SoupBuffer. (See #SoupChunkAllocator for additional details.) Libsoup will then read data from the network into that buffer, and update the buffer's <literal>length</literal> to indicate how much data it read.

Generally, a custom chunk allocator would be used in conjunction with soup_message_body_set_accumulate() %FALSE and #SoupMessage::got_chunk, as part of a strategy to avoid unnecessary copying of data. However, you cannot assume that every call to the allocator will be followed by a call to your #SoupMessage::got_chunk handler; if an I/O error occurs, then the buffer will be unreffed without ever having been used. If your buffer-allocation strategy requires special cleanup, use soup_buffer_new_with_owner() rather than doing the cleanup from the #SoupMessage::got_chunk handler.

The other thing to remember when using non-accumulating message bodies is that the buffer passed to the #SoupMessage::got_chunk handler will be unreffed after the handler returns, just as it would be in the non-custom-allocated case. If you want to hand the chunk data off to some other part of your program to use later, you'll need to ref the #SoupBuffer (or its owner, in the soup_buffer_new_with_owner() case) to ensure that the data remains valid.