---

hsync.h File Reference

Main public interface to libhsync. More...

Data Structures
struct	hs_stats
	Performance statistics from a libhsync encoding or decoding operation. More...
struct	hs_mdfour
struct	hs_stream_s
	Stream through which the calling application feeds data to and from the library. More...
Defines
#define	HS_MD4_LENGTH   16
#define	HS_DEFAULT_STRONG_LEN   8
	Default length of strong signatures, in bytes. More...
#define	HS_DEFAULT_BLOCK_LEN   2048
	Default block length, if not determined by any other factors. More...
Typedefs
typedef void	hs_trace_fn_t (int level, char const *msg)
	Callback to write out log messages. More...
typedef struct hs_stats	hs_stats_t
	Performance statistics from a libhsync encoding or decoding operation. More...
typedef struct hs_mdfour	hs_mdfour_t
	MD4 message-digest accumulator. More...
typedef struct hs_signature	hs_signature_t
typedef struct hs_stream_s	hs_stream_t
	Stream through which the calling application feeds data to and from the library. More...
typedef struct hs_job	hs_job_t
	Job of work to be done. More...
typedef hs_result	hs_copy_cb (void *opaque, size_t *len, void **result)
	Callback used to retrieve parts of the basis file. More...
Enumerations
enum	hs_loglevel {   HS_LOG_EMERG = 0, HS_LOG_ALERT = 1, HS_LOG_CRIT = 2, HS_LOG_ERR = 3,   HS_LOG_WARNING = 4, HS_LOG_NOTICE = 5, HS_LOG_INFO = 6, HS_LOG_DEBUG = 7 }
	Log severity levels. More...
enum	hs_result {   HS_DONE = 0, HS_BLOCKED = 1, HS_RUNNING = 2, HS_TEST_SKIPPED = 77,   HS_IO_ERROR = 100, HS_SYNTAX_ERROR = 101, HS_MEM_ERROR = 102, HS_INPUT_ENDED = 103,   HS_BAD_MAGIC = 104, HS_UNIMPLEMENTED = 105, HS_CORRUPT = 106 }
	Return codes from nonblocking hsync operations. More...
Functions
void	hs_trace_set_level (hs_loglevel level)
	Set the least important message severity that will be output. More...
void	hs_trace_to (hs_trace_fn_t *)
	Set trace callback. More...
void	hs_trace_stderr (int level, char const *msg)
	Default trace callback that writes to stderr. More...
int	hs_supports_trace (void)
	Check whether the library was compiled with debugging trace suport. More...
void	hs_hexify (char *to_buf, void const *from_buf, int from_len)
size_t	hs_unbase64 (char *s)
	Decode a base64 buffer in place. More...
void	hs_base64 (unsigned char const *buf, int n, char *out)
	Encode a buffer as base64. More...
char const*	hs_strerror (hs_result r)
	Return an English description of a hs_result value. More...
void	hs_mdfour (unsigned char *out, void const *in, int n)
void	hs_mdfour_begin (hs_mdfour_t *md)
void	hs_mdfour_update (hs_mdfour_t *md, void const *, size_t n)
void	hs_mdfour_result (hs_mdfour_t *md, unsigned char *out)
char*	hs_format_stats (hs_stats_t const *, char *, size_t)
	Return a human-readable representation of statistics. More...
int	hs_log_stats (hs_stats_t const *stats)
void	hs_free_sumset (hs_signature_t *)
	Deep deallocation of checksums. More...
void	hs_sumset_dump (hs_signature_t const *)
	Dump signatures to the log. More...
void	hs_stream_init (hs_stream_t *)
hs_job_t*	hs_accum_begin (hs_stream_t *)
hs_result	hs_job_iter (hs_job_t *)
	Run a hs_job_t state machine until it blocks (HS_BLOCKED), returns an error, or completes (HS_COMPLETE). More...
hs_result	hs_job_free (hs_job_t *)
int	hs_accum_value (hs_job_t *, char *sum, size_t sum_len)
hs_job_t*	hs_sig_begin (hs_stream_t *stream, size_t new_block_len, size_t strong_sum_len)
	Set up a new encoding job. More...
hs_job_t*	hs_delta_begin (hs_stream_t *stream, hs_signature_t *)
	Prepare to compute a delta on a stream. More...
hs_job_t*	hs_loadsig_begin (hs_stream_t *, hs_signature_t **)
	Read a signature from a file into an hs_signature_t structure in memory. More...
hs_job_t*	hs_patch_begin (hs_stream_t *, hs_copy_cb *, void *copy_arg)
	Apply a delta to a basis to recreate the new file. More...
hs_result	hs_build_hash_table (hs_signature_t *sums)
Variables
char const	hs_libhsync_version [] = (PACKAGE " " VERSION)
	Library version string. More...
char const	hs_licence_string []

---

Detailed Description

Main public interface to libhsync.

Author(s):

Martin Pool <mbp@samba.org>

Id:

hsync.h,v 1.69 2001/02/27 22:48:13 mbp Exp

See Introduction for an introduction to use of this library.

---

Define Documentation

#define HS_DEFAULT_STRONG_LEN   8

Default length of strong signatures, in bytes. The MD4 checksum is truncated to this size.

#define HS_DEFAULT_BLOCK_LEN   2048

Default block length, if not determined by any other factors.

---

Typedef Documentation

typedef void hs_trace_fn_t

Callback to write out log messages. Parameters: level   a syslog level. msg   message to be logged.

typedef struct hs_stats hs_stats_t

Performance statistics from a libhsync encoding or decoding operation. See also: hs_format_stats(), hs_log_stats()

struct hs_mdfour hs_mdfour_t

MD4 message-digest accumulator. See also: hs_mdfour(), hs_mdfour_begin(), hs_mdfour_update(), hs_mdfour_result()

typedef struct hs_stream_s hs_stream_t

Stream through which the calling application feeds data to and from the library. See also: struct hs_stream_s

typedef struct hs_job hs_job_t

Job of work to be done. Created by functions such as hs_sig_begin(), and then iterated over by hs_job_iter().

typedef hs_result hs_copy_cb

Callback used to retrieve parts of the basis file.

---

Enumeration Type Documentation

enum hs_loglevel

Log severity levels. These are the same as syslog, at least in glibc. See also: hs_trace_set_level() Enumeration values: HS_LOG_EMERG   System is unusable. HS_LOG_ALERT   Action must be taken immediately. HS_LOG_CRIT   Critical conditions. HS_LOG_ERR   Error conditions. HS_LOG_WARNING   Warning conditions. HS_LOG_NOTICE   Normal but significant condition. HS_LOG_INFO   Informational. HS_LOG_DEBUG   Debug-level messages.

enum hs_result

Return codes from nonblocking hsync operations. Enumeration values: HS_DONE   Completed successfully. HS_BLOCKED   Blocked waiting for more data. HS_RUNNING   Not yet finished or blocked. This value should never be returned to the caller. HS_TEST_SKIPPED   Test neither passed or failed. HS_IO_ERROR   Error in file or network IO. HS_SYNTAX_ERROR   Command line syntax error. HS_MEM_ERROR   Out of memory. HS_INPUT_ENDED   End of input file, possibly unexpected. HS_BAD_MAGIC   Bad magic number at start of stream. Probably not a libhsync file, or possibly the wrong kind of file or from an incompatible library version. HS_UNIMPLEMENTED   Author is lazy. HS_CORRUPT   Unbelievable value in stream.

---

Function Documentation

void hs_trace_set_level ( hs_loglevel level )

Set the least important message severity that will be output.

void hs_trace_to ( hs_trace_fn_t * new_impl )

Set trace callback. The callback scheme allows for use within applications that may have their own particular ways of reporting errors: log files for a web server, perhaps, and an error dialog for a browser. Todo: Do we really need such fine-grained control, or just yes/no tracing?

void hs_trace_stderr ( int level, char const * msg )

Default trace callback that writes to stderr. Implements hs_trace_fn_t, and may be passed to hs_trace_to().

int hs_supports_trace ( void )

Check whether the library was compiled with debugging trace suport. If this returns false, then trying to turn trace on will achieve nothing.

void hs_hexify ( char * to_buf, void const * from_buf, int from_len )

Convert FROM_LEN bytes at FROM_BUF into a hex representation in TO_BUF, which must be twice as long plus one byte for the null terminator.

size_t hs_unbase64 ( char * s )

Decode a base64 buffer in place. Returns: the number of binary bytes.

void hs_base64 ( unsigned char const * buf, int n, char * out )

Encode a buffer as base64.

char const * hs_strerror ( hs_result r )

Return an English description of a hs_result value.

char * hs_format_stats ( hs_stats_t const * stats, char * buf, size_t size )

Return a human-readable representation of statistics. The string is truncated if it does not fit. 100 characters should be sufficient space. Parameters: stats   Statistics from an encoding or decoding operation. buf   Buffer to receive result. size   Size of buffer. Returns: buf

void hs_free_sumset ( hs_signature_t * psums )

Deep deallocation of checksums.

void hs_sumset_dump ( hs_signature_t const * sums )

Dump signatures to the log.

hs_result hs_job_iter ( hs_job_t * job )

Run a hs_job_t state machine until it blocks (HS_BLOCKED), returns an error, or completes (HS_COMPLETE). Returns: The hs_result that caused iteration to stop. Parameters: ending   True if there is no more data after what's in the input buffer. The final block checksum will run across whatever's in there, without trying to accumulate anything else.

hs_job_t * hs_sig_begin ( hs_stream_t * stream, size_t new_block_len, size_t strong_sum_len )

Set up a new encoding job. See also: hs_sig_file()

hs_job_t* hs_delta_begin ( hs_stream_t * stream, hs_signature_t * sig )

Prepare to compute a delta on a stream.

hs_job_t * hs_loadsig_begin ( hs_stream_t * stream, hs_signature_t ** signature )

Read a signature from a file into an hs_signature_t structure in memory. Once there, it can be used to generate a delta to a newer version of the file. Note: After loading the signatures, you must call hs_build_hash_table() before you can use them.

hs_job_t * hs_patch_begin ( hs_stream_t * stream, hs_copy_cb * copy_cb, void * copy_arg )

Apply a delta to a basis to recreate the new file. This gives you back a hs_job_t object, which can be cranked by calling hs_job_iter() and updating the stream pointers. When finished, call hs_job_finish() to dispose of it. Parameters: stream   Contains pointers to input and output buffers, to be adjusted by caller on each iteration. copy_cb   Callback used to retrieve content from the basis file. copy_arg   Opaque environment pointer passed through to the callback. Todo: As output is produced, accumulate the MD4 checksum of the output. Then if we find a CHECKSUM command we can check it's contents against the output. Implement COPY commands. See also: hs_patch_file()

---

Variable Documentation

char const hs_libhsync_version[] = (PACKAGE " " VERSION)

Library version string.

---