Update the compression level and strategy.

Synopsis

void
params(
    z_params& zs,
    int level,
    Strategy strategy,
    error_code& ec);

Description

This function dynamically updates the compression level and compression strategy. The interpretation of level and strategy is as in reset. This can be used to switch between compression and straight copy of the input data, or to switch to a different kind of input data requiring a different strategy. If the compression approach (which is a function of the level) or the strategy is changed, and if there have been any calls to write since the stream was reset, then the input available so far is compressed with the old level and strategy using write with Flush::block. There are three approaches for the compression levels 0, 1..3, and 4..9 respectively. The new level and strategy will take effect at the next call of write.

If a write with Flush::block is performed by params, and it does not have enough output space to complete, then the parameter change will not take effect. In this case, params can be called again with the same parameters and more output space to try again.

In order to assure a change in the parameters on the first try, the stream should be flushed using write with Flush::block or another flush request until zs.avail_out is not zero, before calling params. Then no more input data should be provided before the call to params. If this is done, the old level and strategy will be applied to the data compressed before params, and the new level and strategy will be applied to the data compressed after params.

Before the call of params, the stream state must be set as for a call of write, since the currently available input may have to be compressed and flushed.

Return Value

error::stream_error if the source stream state was inconsistent or if a parameter was invalid, or error::need_buffers if there was not enough output space to complete the compression of the available input data before a change in the strategy or approach. Note that in the case of error::need_buffers, the parameters are not changed. error::need_buffers is not fatal, in which case params can be retried with more output space.