diff options
Diffstat (limited to 'libhashsum.h')
| -rw-r--r-- | libhashsum.h | 48 |
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 |