root
/
xz
mirror of https://git.tukaani.org/xz.git
1
0
Fork 0
Code Issues Releases Wiki Activity

liblzma: Improve documentation in check.h. 

All functions now explicitly specify parameter and return values.
Also moved the note about SHA-256 functions not being exported to the
top of the file.
This commit is contained in:
Jia Tan 2023-01-27 22:44:06 +08:00
parent 9c71db4e88
commit 43ec344c86
1 changed files with 28 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
src/liblzma/api/lzma/check.h
View File

@ -72,12 +72,17 @@ typedef enum {
/**
* \brief Test if the given Check ID is supported
*
* Return true if the given Check ID is supported by this liblzma build.
* Otherwise false is returned. It is safe to call this with a value that
* is not in the range [0, 15]; in that case the return value is always false.
* LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always supported (even if
* liblzma is built with limited features).
*
* You can assume that LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always
* supported (even if liblzma is built with limited features).
* \note It is safe to call this with a value that is not in the
* range [0, 15]; in that case the return value is always false.
*
* \param check Check ID
*
* \return lzma_bool:
* - true if Check ID is supported by this liblzma build.
* - false otherwise.
*/
extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
lzma_nothrow lzma_attr_const;
@ -91,7 +96,10 @@ extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
* the Check field with the specified Check ID. The values are:
* { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }
*
* If the argument is not in the range [0, 15], UINT32_MAX is returned.
* \param check Check ID
*
* \return Size of the Check field in bytes. If the argument is not in
* the range [0, 15], UINT32_MAX is returned.
*/
extern LZMA_API(uint32_t) lzma_check_size(lzma_check check)
lzma_nothrow lzma_attr_const;
@ -127,25 +135,32 @@ extern LZMA_API(uint32_t) lzma_crc32(
*
* Calculate CRC64 using the polynomial from the ECMA-182 standard.
*
* This function is used similarly to lzma_crc32(). See its documentation.
* This function is used similarly to lzma_crc32().
*
* \param buf Pointer to the input buffer
* \param size Size of the input buffer
* \param crc Previously returned CRC value. This is used to
* calculate the CRC of a big buffer in smaller chunks.
* Set to zero when starting a new calculation.
*
* \return Updated CRC value, which can be passed to this function
* again to continue CRC calculation.
*/
extern LZMA_API(uint64_t) lzma_crc64(
const uint8_t *buf, size_t size, uint64_t crc)
lzma_nothrow lzma_attr_pure;
/*
* SHA-256 functions are currently not exported to public API.
* Contact Lasse Collin if you think it should be.
*/
/**
* \brief Get the type of the integrity check
*
* This function can be called only immediately after lzma_code() has
* returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK.
* Calling this function in any other situation has undefined behavior.
*
* \param strm Pointer to lzma_stream meeting the above conditions.
*
* \return Check ID in the lzma_stream, or undefined if called improperly.
*/
extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm)
lzma_nothrow;