From 7161ad76e2d0ac7de2a6235fcad3b9dfc99e9140 Mon Sep 17 00:00:00 2001 From: Mark Adler Date: Tue, 22 Nov 2016 23:29:19 -0800 Subject: Assure that deflateParams() will not switch functions mid-block. This alters the specification in zlib.h, so that deflateParams() will not change any parameters if there is not enough output space in the event that a block is emitted in order to allow switching the compression function. --- zlib.h | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) (limited to 'zlib.h') diff --git a/zlib.h b/zlib.h index 4544e57..aa130a8 100644 --- a/zlib.h +++ b/zlib.h @@ -695,24 +695,25 @@ ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm, new level and strategy will take effect at the next call of deflate(). If a deflate(strm, Z_BLOCK) is performed by deflateParams(), and it does - not have enough output space to complete, then the parameter change will - take effect at an undetermined location in the uncompressed data provided so - far. In order to assure a change in the parameters at a specific location - in the uncompressed data, the deflate stream should first be flushed with - Z_BLOCK or another flush parameter, and deflate() called until - strm.avail_out is not zero, before the call of deflateParams(). Then no - more input data should be provided before the deflateParams() call. If this - is done, the old level and strategy will be applied to the data compressed - before deflateParams(), and the new level and strategy will be applied to - the the data compressed after deflateParams(). - - deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source stream + not have enough output space to complete, then the parameter change will not + take effect. In this case, deflateParams() 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 + deflate stream should be flushed using deflate() with Z_BLOCK or other flush + request until strm.avail_out is not zero, before calling deflateParams(). + Then no more input data should be provided before the deflateParams() call. + If this is done, the old level and strategy will be applied to the data + compressed before deflateParams(), and the new level and strategy will be + applied to the the data compressed after deflateParams(). + + deflateParams returns Z_OK on success, Z_STREAM_ERROR if the source stream state was inconsistent or if a parameter was invalid, or Z_BUF_ERROR if - there was not enough output space to complete the compression before the - parameters were changed. Note that in the case of a Z_BUF_ERROR, the - parameters are changed nevertheless, and will take effect at an undetermined - location in the previously supplied uncompressed data. Compression may - proceed after a Z_BUF_ERROR. + 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 a Z_BUF_ERROR, the parameters are not changed. A return + value of Z_BUF_ERROR is not fatal, in which case deflateParams() can be + retried with more output space. */ ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm, -- cgit v1.2.3-55-g6feb