Function

compression_stream_process

Performs compression or decompression using an initialized compression stream structure.

Declaration

compression_status compression_stream_process(compression_stream *stream, int flags);

Parameters

stream

A pointer to an allocated and fully initialized compression_stream structure.

flags

A constant of type compression_stream_flags; this should be COMPRESSION_STREAM_FINALIZE if there is no further input data, or 0 otherwise.

Return Value

A value of type compression_status, interpreted as follows:

  • COMPRESSION_STATUS_OK means that processing was successful, but the stream may produce more output. Call the function again with updated parameters.

  • COMPRESSION_STATUS_END means that processing was successful, and the stream will produce no more output (this only occurs if flags is set to COMPRESSION_STREAM_FINALIZE).

  • COMPRESSION_STATUS_ERROR means an error occurred.

Discussion

Each time compression_stream_process is called successfully, the function consumes data from the source buffer and writes data into the destination buffer, until it reaches the end of one of the buffers and returns either COMPRESSION_STATUS_OK or COMPRESSION_STATUS_END.

After a successful call, the function updates the buffer parameters in the stream object: the function increments src_ptr (and decrements src_size) by the number of input bytes consumed. Likewise, the function incremets dst_ptr (and decrements dst_size) by the number of output bytes produced. The sum (src_ptr + src_size) remains unchanged, and so does (dst_ptr + dst_size). At this point, either src_size or dst_size will be 0, indicating that the source buffer is empty or the destination buffer is full.

If the source buffer is empty, you can refill it with more data and adjust the parameters, or point to a different buffer for the next call. If you don't provide any more input data, set flags to COMPRESSION_STREAM_FINALIZE and call again.

If the destination buffer is full and the return value is not COMPRESSION_STATUS_END, there may still be input available for processing. To let this happen, you might grow the buffer, move the pointer back to reuse the buffer, or point to a new destination buffer, and then call again.

See Also

Multiple-Step Compression

Compressing and Decompressing Files with Stream Compression

Perform compression or the appropriate kind of decompression to a file based on its path extension.

compression_stream

A structure representing a compression stream.

compression_stream_init

Initializes a compression stream for either compression or decompression.

compression_stream_destroy

Frees any memory allocated by stream initialization function.

compression_status

A set of values used to represent the status of stream compression.

compression_stream_flags

A set of values used to represent stream compression flags.

compression_stream_operation

A set of values used to represent a stream compression operation.