librsync.h File Reference

Main public interface to librsync. More...


Data Structures

struct  rs_stats
 Performance statistics from a librsync encoding or decoding operation. More...
struct  rs_buffers_s
 Stream through which the calling application feeds data to and from the library. More...

Defines

#define RS_MD4_LENGTH   16
#define RS_DEFAULT_STRONG_LEN   8
 Default length of strong signatures, in bytes.
#define RS_DEFAULT_BLOCK_LEN   2048
 Default block length, if not determined by any other factors.

Typedefs

typedef void rs_trace_fn_t (int level, char const *msg)
 Callback to write out log messages.
typedef struct rs_stats rs_stats_t
typedef struct rs_mdfour rs_mdfour_t
 MD4 message-digest accumulator.
typedef unsigned int rs_weak_sum_t
typedef unsigned char rs_strong_sum_t [RS_MD4_LENGTH]
typedef struct rs_signature rs_signature_t
typedef struct rs_buffers_s rs_buffers_t
 Stream through which the calling application feeds data to and from the library.
typedef struct rs_job rs_job_t
 Job of work to be done.
typedef rs_result rs_driven_cb (rs_job_t *job, rs_buffers_t *buf, void *opaque)
typedef rs_result rs_copy_cb (void *opaque, rs_long_t pos, size_t *len, void **buf)
 Callback used to retrieve parts of the basis file.

Enumerations

enum  rs_loglevel {
  RS_LOG_EMERG = 0, RS_LOG_ALERT = 1, RS_LOG_CRIT = 2, RS_LOG_ERR = 3,
  RS_LOG_WARNING = 4, RS_LOG_NOTICE = 5, RS_LOG_INFO = 6, RS_LOG_DEBUG = 7
}
 Log severity levels. More...
enum  rs_result {
  RS_DONE = 0, RS_BLOCKED = 1, RS_RUNNING = 2, RS_TEST_SKIPPED = 77,
  RS_IO_ERROR = 100, RS_SYNTAX_ERROR = 101, RS_MEM_ERROR = 102, RS_INPUT_ENDED = 103,
  RS_BAD_MAGIC = 104, RS_UNIMPLEMENTED = 105, RS_CORRUPT = 106, RS_INTERNAL_ERROR = 107,
  RS_PARAM_ERROR = 108
}
 Return codes from nonblocking rsync operations. More...
enum  rs_work_options { RS_END = 0x01 }
 Bitmask values that may be passed to the options parameter of rs_work(). More...

Functions

void rs_trace_set_level (rs_loglevel level)
 Set the least important message severity that will be output.
void rs_trace_to (rs_trace_fn_t *)
 Set trace callback.
void rs_trace_stderr (int level, char const *msg)
 Default trace callback that writes to stderr.
int rs_supports_trace (void)
 Check whether the library was compiled with debugging trace suport.
void rs_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 rs_unbase64 (char *s)
 Decode a base64 buffer in place.
void rs_base64 (unsigned char const *buf, int n, char *out)
 Encode a buffer as base64.
char const * rs_strerror (rs_result r)
 Return an English description of a rs_result value.
void rs_mdfour (unsigned char *out, void const *in, size_t)
void rs_mdfour_begin (rs_mdfour_t *md)
void rs_mdfour_update (rs_mdfour_t *md, void const *, size_t n)
 Feed some data into the MD4 accumulator.
void rs_mdfour_result (rs_mdfour_t *md, unsigned char *out)
char * rs_format_stats (rs_stats_t const *, char *, size_t)
 Return a human-readable representation of statistics.
int rs_log_stats (rs_stats_t const *stats)
void rs_free_sumset (rs_signature_t *)
 Deep deallocation of checksums.
void rs_sumset_dump (rs_signature_t const *)
 Dump signatures to the log.
rs_result rs_job_iter (rs_job_t *, rs_buffers_t *)
 Run a rs_job_t state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_COMPLETE).
rs_result rs_job_drive (rs_job_t *job, rs_buffers_t *buf, rs_driven_cb in_cb, void *in_opaque, rs_driven_cb out_cb, void *out_opaque)
 Actively process a job, by making callbacks to fill and empty the buffers until the job is done.
const rs_stats_trs_job_statistics (rs_job_t *job)
 Return pointer to statistics accumulated about this job.
rs_result rs_job_free (rs_job_t *)
int rs_accum_value (rs_job_t *, char *sum, size_t sum_len)
rs_job_trs_sig_begin (size_t new_block_len, size_t strong_sum_len)
 Set up a new encoding job.
rs_job_trs_delta_begin (rs_signature_t *)
 Prepare to compute a streaming delta.
rs_job_trs_loadsig_begin (rs_signature_t **)
 Read a signature from a file into an rs_signature_t structure in memory.
rs_job_trs_patch_begin (rs_copy_cb *, void *copy_arg)
 Apply a gloss_delta to a gloss_basis to recreate the new file.
rs_result rs_build_hash_table (rs_signature_t *sums)
void rs_mdfour_file (FILE *in_file, char *result)
 Calculate the MD4 sum of a file.
rs_result rs_sig_file (FILE *old_file, FILE *sig_file, size_t block_len, size_t strong_len, rs_stats_t *)
 Generate the signature of a basis file, and write it out to another.
rs_result rs_loadsig_file (FILE *, rs_signature_t **, rs_stats_t *)
 Load signatures from a signature file into memory.
rs_result rs_file_copy_cb (void *arg, rs_long_t pos, size_t *len, void **buf)
 Default copy implementation that retrieves a part of a stdio file.
rs_result rs_delta_file (rs_signature_t *, FILE *new_file, FILE *delta_file, rs_stats_t *)
rs_result rs_patch_file (FILE *basis_file, FILE *delta_file, FILE *new_file, rs_stats_t *)

Variables

char const rs_librsync_version []
 Library version string.
char const rs_licence_string []
int rs_inbuflen
 Buffer sizes for file IO.
int rs_outbuflen


Detailed Description

Main public interface to librsync.

Author:
Martin Pool <mbp@samba.org>
Version:
librsync-0.9.6
Id
librsync.h,v 1.5 2003/12/16 00:03:40 abo Exp

See intro for an introduction to use of this library.


Define Documentation

#define RS_DEFAULT_STRONG_LEN   8

Default length of strong signatures, in bytes.

The MD4 checksum is truncated to this size.

#define RS_DEFAULT_BLOCK_LEN   2048

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


Typedef Documentation

rs_trace_fn_t

Callback to write out log messages.

Parameters:
level a syslog level.
msg message to be logged.

struct rs_mdfour rs_mdfour_t

MD4 message-digest accumulator.

See also:
rs_mdfour(), rs_mdfour_begin(), rs_mdfour_update(), rs_mdfour_result()

typedef struct rs_buffers_s rs_buffers_t

Stream through which the calling application feeds data to and from the library.

See also:
struct rs_buffers_s

api_buffers

struct rs_job rs_job_t

Job of work to be done.

Created by functions such as rs_sig_begin(), and then iterated over by rs_job_iter().

typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos, size_t *len, void **buf)

Callback used to retrieve parts of the basis file.

Parameters:
pos Position where copying should begin.
len On input, the amount of data that should be retrieved. Updated to show how much is actually available.
buf On input, a buffer of at least *len bytes. May be updated to point to a buffer allocated by the callback if it prefers.


Enumeration Type Documentation

enum rs_loglevel

Log severity levels.

These are the same as syslog, at least in glibc.

See also:
rs_trace_set_level()
Enumerator:
RS_LOG_EMERG  System is unusable.
RS_LOG_ALERT  Action must be taken immediately.
RS_LOG_CRIT  Critical conditions.
RS_LOG_ERR  Error conditions.
RS_LOG_WARNING  Warning conditions.
RS_LOG_NOTICE  Normal but significant condition.
RS_LOG_INFO  Informational.
RS_LOG_DEBUG  Debug-level messages.

enum rs_result

Return codes from nonblocking rsync operations.

Enumerator:
RS_DONE  Completed successfully.

RS_BLOCKED  Blocked waiting for more data.

RS_RUNNING  Not yet finished or blocked.

This value should never be returned to the caller.

RS_TEST_SKIPPED  Test neither passed or failed.

RS_IO_ERROR  Error in file or network IO.

RS_SYNTAX_ERROR  Command line syntax error.

RS_MEM_ERROR  Out of memory.

RS_INPUT_ENDED  End of input file, possibly unexpected.

RS_BAD_MAGIC  Bad magic number at start of stream.

Probably not a librsync file, or possibly the wrong kind of file or from an incompatible library version.

RS_UNIMPLEMENTED  Author is lazy.

RS_CORRUPT  Unbelievable value in stream.

RS_INTERNAL_ERROR  Probably a library bug.

RS_PARAM_ERROR  Bad value passed in to library, probably an application bug.

enum rs_work_options

Bitmask values that may be passed to the options parameter of rs_work().

Enumerator:
RS_END  End of input file; please finish up.


Function Documentation

void rs_trace_set_level ( rs_loglevel  level  ) 

Set the least important message severity that will be output.

void rs_trace_to ( rs_trace_fn_t new_impl  ) 

Set trace callback.

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 rs_trace_stderr ( int  level,
char const *  msg 
)

Default trace callback that writes to stderr.

Implements rs_trace_fn_t, and may be passed to rs_trace_to().

int rs_supports_trace ( void   ) 

Check whether the library was compiled with debugging trace suport.

Check whether the library was compiled with debugging trace suport.

If this returns false, then trying to turn trace on will achieve nothing.

void rs_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 rs_unbase64 ( char *  s  ) 

Decode a base64 buffer in place.

Returns:
the number of binary bytes.

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

Encode a buffer as base64.

char const* rs_strerror ( rs_result  r  ) 

Return an English description of a rs_result value.

void rs_mdfour_update ( rs_mdfour_t md,
void const *  in_void,
size_t  n 
)

Feed some data into the MD4 accumulator.

Parameters:
n Number of bytes fed in.

char* rs_format_stats ( rs_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 rs_free_sumset ( rs_signature_t *   ) 

Deep deallocation of checksums.

void rs_sumset_dump ( rs_signature_t const *   ) 

Dump signatures to the log.

rs_result rs_job_iter ( rs_job_t job,
rs_buffers_t buffers 
)

Run a rs_job_t state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_COMPLETE).

Returns:
The rs_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.

rs_result rs_job_drive ( rs_job_t job,
rs_buffers_t buf,
rs_driven_cb  in_cb,
void *  in_opaque,
rs_driven_cb  out_cb,
void *  out_opaque 
)

Actively process a job, by making callbacks to fill and empty the buffers until the job is done.

const rs_stats_t* rs_job_statistics ( rs_job_t job  ) 

Return pointer to statistics accumulated about this job.

rs_job_t* rs_sig_begin ( size_t  new_block_len,
size_t  strong_sum_len 
)

Set up a new encoding job.

See also:
rs_sig_file()

rs_job_t* rs_delta_begin ( rs_signature_t *   ) 

Prepare to compute a streaming delta.

rs_job_t* rs_loadsig_begin ( rs_signature_t **  signature  ) 

Read a signature from a file into an rs_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 rs_build_hash_table() before you can use them.

rs_job_t* rs_patch_begin ( rs_copy_cb copy_cb,
void *  copy_arg 
)

Apply a gloss_delta to a gloss_basis to recreate the new file.

This gives you back a rs_job_t object, which can be cranked by calling rs_job_iter() and updating the stream pointers. When finished, call rs_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.
Todo:
Implement COPY commands.
See also:
rs_patch_file()

void rs_mdfour_file ( FILE *  in_file,
char *  result 
)

Calculate the MD4 sum of a file.

Parameters:
result Binary (not hex) MD4 of the whole contents of the file.

rs_result rs_sig_file ( FILE *  old_file,
FILE *  sig_file,
size_t  new_block_len,
size_t  strong_len,
rs_stats_t stats 
)

Generate the signature of a basis file, and write it out to another.

Parameters:
new_block_len block size for signature generation, in bytes
strong_len truncated length of strong checksums, in bytes
See also:
rs_sig_begin()

rs_result rs_loadsig_file ( FILE *  sig_file,
rs_signature_t **  sumset,
rs_stats_t stats 
)

Load signatures from a signature file into memory.

Return a pointer to the newly allocated structure in SUMSET.

See also:
rs_readsig_begin()

rs_result rs_file_copy_cb ( void *  arg,
rs_long_t  pos,
size_t *  len,
void **  buf 
)

Default copy implementation that retrieves a part of a stdio file.


Variable Documentation

char const rs_librsync_version[]

Library version string.

int rs_inbuflen

Buffer sizes for file IO.

You probably only need to change these in testing.


Generated on Fri Apr 25 16:29:51 2008 for librsync by  doxygen 1.5.4