Add support for extended hash + add support for output hash to custom buffer when supported

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 47 insertions, 1 deletions

diff --git a/libhashsum.h b/libhashsum.h
index b10f2f4..22f7488 100644
--- a/libhashsum.h
+++ b/libhashsum.h
@@ -375,7 +375,7 @@ struct libhashsum_hasher {
 	size_t (*process)(struct libhashsum_hasher *this, const void *data, size_t bytes);
 
 	/**
-	 * Update the hash state given it's final
+	 * Update the hash state given its final
 	 * input data
 	 * 
 	 * Regardless of the algorithm's standard, the function
@@ -385,6 +385,9 @@ struct libhashsum_hasher {
 	 * bit and the most significant bit will be used as the
 	 * last bit
 	 * 
+	 * `this->hash_output` will be set to point to a buffer
+	 * in `this->state` containing the hash
+	 * 
 	 * @param   this        The object containing this function pointer
 	 * @param   data        The new input data
 	 * @param   bytes       The number of bytes available in `data` for reading
@@ -410,6 +413,13 @@ struct libhashsum_hasher {
 	 * bit and the most significant bit will be used as the
 	 * last bit
 	 * 
+	 * `this->hash_output` will be set to point to a buffer
+	 * in `this->state` containing the hash. However if
+	 * `this->hash_output` is already non-`NULL`, the function
+	 * _may_ choose to immediately output to the buffer that
+	 * `this->hash_output` pointers to (the application must
+	 * make sure it is sufficiently large).
+	 * 
 	 * @param   this        The object containing this function pointer
 	 * @param   data        The new input data, the function may rewrite its content
 	 * @param   bytes       The number of bytes available in `data` for reading
@@ -427,6 +437,42 @@ struct libhashsum_hasher {
 	int (*finalise)(struct libhashsum_hasher *this, void *data, size_t bytes, unsigned extra_bits, size_t size);
 
 	/**
+	 * Extend the hash with an additional `this->hash_size` bytes
+	 * 
+	 * This pointer will be set to `NULL` when the object initialised,
+	 * but once `*.finalise` or `*.finalise_const` is called, it
+	 * will be set a point to a function _if_ the algorithm supports
+	 * extending the hash indefinitely (if there is a limit, this
+	 * pointer will be set to `NULL` once the limit has been reached)
+	 * 
+	 * If the hash function supports generating hashes before the
+	 * entire file has been processed, this pointer be non-`NULL`
+	 * immediately when the object is initialised, however the
+	 * hash function does not support extending the hash, calling
+	 * this function, `*.finalise`, or `*.finalise_const` will
+	 * reset this pointer to `NULL`. (No currently supported hash
+	 * function supports this behaviour.)
+	 * 
+	 * `this->hash_output` will be set to point to a buffer
+	 * in `this->state` containing the hash extent. Note that
+	 * this overrides any hash previously generated for `this`.
+	 * 
+	 * @param  this    The object containing this function pointer
+	 * @param  skip    Non-zero if the function need not set
+	 *                 `this->hash_output` and output the hash extent
+	 *                 (note that the function may ignore this argument)
+	 * @param  buffer  If non-`NULL`, the function _may_ choose output the
+	 *                 hash extent to the provided buffer (the application
+	 *                 must ensure it is sufficently large). If the function
+	 *                 does output to the provided buffer, it will reset
+	 *                 `this->hash_output` to `NULL`.
+	 * 
+	 * @since  1.0
+	 */
+	LIBHASHSUM_1_NONNULL_
+	void (*stretch)(struct libhashsum_hasher *this, int skip, void *buffer);
+
+	/**
 	 * Unless this pointer its `NULL`, it points to
 	 * function that shall be once the object (`this`)
 	 * is not needed anymore