/** Return a serialized representation of @a checksum, allocated in
 * @a result_pool. Temporary allocations are performed in @a scratch_pool.
 *
 * Note that @a checksum may not be NULL.
 *
 * @since New in 1.7.
 */
const char *
svn_checksum_serialize(const svn_checksum_t *checksum,
                       apr_pool_t *result_pool,
                       apr_pool_t *scratch_pool);


/** Return @a checksum from the serialized format at @a data. The checksum
 * will be allocated in @a result_pool, with any temporary allocations
 * performed in @a scratch_pool.
 *
 * @since New in 1.7.
 */
svn_error_t *
svn_checksum_deserialize(const svn_checksum_t **checksum,
                         const char *data,
                         apr_pool_t *result_pool,
                         apr_pool_t *scratch_pool);


/** Parse the hex representation @a hex of a checksum of kind @a kind and
 * set @a *checksum to the result, allocating in @a pool.
 *
 * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
 * to @c NULL.
 *
 * @since New in 1.6.
 */
/* ### TODO: When revving this, make it set @a *checksum to a non-NULL struct
 * ###       when @a hex is the all-zeroes checksum.  See
 * ### http://mail-archives.apache.org/mod_mbox/subversion-dev/201609.mbox/%3c00cd26ab-bdb3-67b4-ca6b-063266493874%40apache.org%3e
 */
svn_error_t *
svn_checksum_parse_hex(svn_checksum_t **checksum,
                       svn_checksum_kind_t kind,
                       const char *hex,
                       apr_pool_t *pool);

/**
 * Return in @a *checksum the checksum of type @a kind for the bytes beginning
 * at @a data, and going for @a len.  @a *checksum is allocated in @a pool.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_checksum(svn_checksum_t **checksum,
             svn_checksum_kind_t kind,
             const void *data,
             apr_size_t len,
             apr_pool_t *pool);


/**
 * Return in @a pool a newly allocated checksum populated with the checksum
 * of type @a kind for the empty string.
 *
 * @since New in 1.6.
 */
svn_checksum_t *
svn_checksum_empty_checksum(svn_checksum_kind_t kind,
                            apr_pool_t *pool);


/**
 * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
 * calculating checksums of type @a kind.  @see svn_checksum_final()
 *
 * @since New in 1.6.
 */
svn_checksum_ctx_t *
svn_checksum_ctx_create(svn_checksum_kind_t kind,
                        apr_pool_t *pool);

/**
 * Reset an existing checksum @a ctx to initial state.
 * @see svn_checksum_ctx_create()
 *
 * @since New in 1.10.
 */
svn_error_t *
svn_checksum_ctx_reset(svn_checksum_ctx_t *ctx);

/**
 * Update the checksum represented by @a ctx, with @a len bytes starting at
 * @a data.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_checksum_update(svn_checksum_ctx_t *ctx,
                    const void *data,
                    apr_size_t len);


/**
 * Finalize the checksum used when creating @a ctx, and put the resultant
 * checksum in @a *checksum, allocated in @a pool.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_checksum_final(svn_checksum_t **checksum,
                   const svn_checksum_ctx_t *ctx,
                   apr_pool_t *pool);


/**
 * Return the digest size of @a checksum.
 *
 * @since New in 1.6.
 */
apr_size_t
svn_checksum_size(const svn_checksum_t *checksum);

/**
 * Return @c TRUE iff @a checksum matches the checksum for the empty
 * string.
 *
 * @since New in 1.8.
 */
svn_boolean_t
svn_checksum_is_empty_checksum(svn_checksum_t *checksum);


/**
 * Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and
 * @a expected checksums which do not match.  Use @a fmt, and the following
 * parameters to populate the error message.
 *
 * @note This function does not actually check for the mismatch, it just
 * constructs the error.
 *
 * @a scratch_pool is used for temporary allocations; the returned error
 * will be allocated in its own pool (as is typical).
 *
 * @since New in 1.7.
 */
svn_error_t *
svn_checksum_mismatch_err(const svn_checksum_t *expected,
                          const svn_checksum_t *actual,
                          apr_pool_t *scratch_pool,
                          const char *fmt,
                          ...)
  __attribute__ ((format(printf, 4, 5)));

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* SVN_CHECKSUM_H */