$treeview $search $mathjax $extrastylesheet
librsync
2.0.2
$projectbrief
|
$projectbrief
|
$searchbox |
00001 # IO callbacks {#api_callbacks} 00002 00003 librsync jobs use IO callbacks to read and write files in pull mode. 00004 It uses a "copy callback" to read data from the basis file for 00005 "patch" operations in both push and pull mode. 00006 00007 These callbacks 00008 might write the data directly to a file or network connection, or they 00009 can do some additional work such as compression or encryption. 00010 00011 Callbacks are passed a `void *` baton, which is chosen by the application when 00012 setting up the job. The baton can hold context or state for the 00013 callback, such as a file handle or descriptor. 00014 00015 There are three types of callbacks, for input, output, and a special 00016 "copy callback" for random-access reads of the basis file when patching. 00017 00018 ## Input and output callbacks 00019 00020 Input and output callbacks are both of type ::rs_driven_cb. These 00021 are used for all operations in pull mode only (see \ref api_pull). 00022 00023 The callbacks are passed to rs_job_drive() and are called repeatedly 00024 until the job completes, fails, or permanently blocks. 00025 00026 Input and output callbacks can and must choose their own buffers, which they 00027 provide as pointers to librsync as the job proceeds. There are many 00028 possibilities: 00029 00030 * The application may allocate a buffer when starting the job, 00031 and shuffle data in and out of it as the job proceeds. As librsync 00032 produces data in the output buffer, it is written out e.g. to a socket, 00033 and the output pointer is then reset. 00034 00035 * The application may allocate a single output buffer adequate to hold all 00036 the output, and then the output callback need do nothing but let librsync 00037 gradually consume it. 00038 00039 * The input or output pointers might point into a mmap'd file. 00040 00041 * The input and output buffers might be provided by some other library. 00042 00043 The caller is responsible for freeing the buffer, and for remembering where 00044 it previously asked librsync to write output. 00045 00046 ## Input callbacks 00047 00048 Input callbacks are passed a ::rs_buffers_s struct into which they can store 00049 a pointer to the data they have read. Note that librsync does not allocate 00050 the buffer, the caller must do so. The input callback should update 00051 ::rs_buffers_s::next_in, ::rs_buffers_s::avail_in, and set ::rs_buffers_s::eof_in 00052 if it's reached the end of the input. 00053 00054 When an input callback reaches end-of-file and can return no more data, it 00055 should return ::RS_INPUT_ENDED. If the callback has just a 00056 little data left before end of file, then it should return that data 00057 with ::RS_DONE. On the next call, unless the file has grown, it can 00058 return ::RS_INPUT_ENDED. 00059 00060 ## Output callbacks 00061 00062 Output callbacks are also passed a ::rs_buffers_s struct. On the first call, 00063 the output callback should store a pointer to its buffer into 00064 ::rs_buffers_s::next_out, and the length into ::rs_buffers_s::avail_out. On 00065 subsequent calls, librsync will have used some of this buffer and updated 00066 those fields. The caller should then write out the used buffer space, 00067 and possibly update the buffer to the place it wants new output to go. 00068 00069 If the callback processes only part of the requested data, it should 00070 still return ::RS_DONE. 00071 In this case librsync will call the callback again later 00072 until it either completes, fails, or blocks. 00073 00074 The key thing to understand about ::rs_buffers_s is that the counts and 00075 pointers are from librsync's point of view: the next byte, and the number 00076 of bytes, that it should read or write. 00077 00078 ## Copy callbacks 00079 00080 Copy callbacks are used from both push-mode (rs_job_iter()) and pull-mode 00081 (rs_job_drive()) invocations, only when doing a "patch" operation started by 00082 rs_patch_begin(). 00083 00084 Copy callbacks have type ::rs_copy_cb. 00085 00086 Copy callbacks are directly passed a buffer and length into which they 00087 should write the data read from the basis file. 00088 00089 ## Callback lifecycle 00090 00091 IO callbacks are only called from within rs_job_drive() or 00092 rs_job_iter(). 00093 00094 Different callbacks may be called several times in a 00095 single invocation of rs_job_iter() or rs_job_drive(). 00096 00097 ## Return values 00098 00099 Callbacks return a ::rs_result value to indicate success, an error, or 00100 being blocked. 00101 00102 If the callbacks return an error, that error will typically be passed 00103 back to the application.