doc
csync.h
Go to the documentation of this file.
1 /*
2  * libcsync -- a library to sync a directory with another
3  *
4  * Copyright (c) 2006-2012 by Andreas Schneider <asn@cryptomilk.org>
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19  */
20 
21 /**
22  * @file csync.h
23  *
24  * @brief Application developer interface for csync.
25  *
26  * @defgroup csyncPublicAPI csync public API
27  *
28  * @{
29  */
30 
31 #ifndef _CSYNC_H
32 #define _CSYNC_H
33 
34 #include <stdbool.h>
35 #include <stdint.h>
36 #include <unistd.h>
37 #include <sys/types.h>
38 
39 #include "csync_version.h"
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 /*
46  * csync file declarations
47  */
48 #define CSYNC_CONF_DIR ".ocsync"
49 #define CSYNC_CONF_FILE "ocsync.conf"
50 #define CSYNC_EXCLUDE_FILE "ocsync_exclude.conf"
51 #define CSYNC_LOCK_FILE ".csync.lock"
52 
88 
90 };
92 
93 /**
94  * Instruction enum. In the file traversal structure, it describes
95  * the csync state of a file.
96  */
98  CSYNC_INSTRUCTION_NONE = 0x00000000,
99  CSYNC_INSTRUCTION_EVAL = 0x00000001,
102  CSYNC_INSTRUCTION_NEW = 0x00000008,
108  /* instructions for the propagator */
111 };
112 
118 };
119 
132 };
133 
136 
137  /* individual file progress information */
138  const char *path;
139  int64_t curr_bytes;
140  int64_t file_size;
141 
142  /* overall progress */
147 
148 };
150 
151 /**
152  * CSync File Traversal structure.
153  *
154  * This structure is passed to the visitor function for every file
155  * which is seen.
156  * Note: The file size is missing here because type int64_t is depending
157  * on the large file support in your build. Make sure to check
158  * that cmake and the callback app are compiled with the same
159  * setting for it, such as:
160  * -D_LARGEFILE64_SOURCE or -D_LARGEFILE_SOURCE
161  *
162  */
164  const char *path;
165  /* off_t size; */
166  time_t modtime;
167 #ifdef _WIN32
168  uint32_t uid;
169  uint32_t gid;
170 #else
171  uid_t uid;
172  gid_t gid;
173 #endif
174  mode_t mode;
177 
178  const char *rename_path;
179  const char *md5;
180  const char *error_string;
181 };
183 
184 /**
185  * csync handle
186  */
187 typedef struct csync_s CSYNC;
188 
189 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
190  int echo, int verify, void *userdata);
191 
192 typedef void (*csync_log_callback) (CSYNC *ctx,
193  int verbosity,
194  const char *function,
195  const char *buffer,
196  void *userdata);
197 
198 /**
199  * @brief Allocate a csync context.
200  *
201  * @param csync The context variable to allocate.
202  *
203  * @return 0 on success, less than 0 if an error occured.
204  */
205 int csync_create(CSYNC **csync, const char *local, const char *remote);
206 
207 /**
208  * @brief Initialize the file synchronizer.
209  *
210  * This function loads the configuration, the statedb and locks the client.
211  *
212  * @param ctx The context to initialize.
213  *
214  * @return 0 on success, less than 0 if an error occured.
215  */
216 int csync_init(CSYNC *ctx);
217 
218 /**
219  * @brief Update detection
220  *
221  * @param ctx The context to run the update detection on.
222  *
223  * @return 0 on success, less than 0 if an error occured.
224  */
225 int csync_update(CSYNC *ctx);
226 
227 /**
228  * @brief Reconciliation
229  *
230  * @param ctx The context to run the reconciliation on.
231  *
232  * @return 0 on success, less than 0 if an error occured.
233  */
234 int csync_reconcile(CSYNC *ctx);
235 
236 /**
237  * @brief Propagation
238  *
239  * @param ctx The context to run the propagation on.
240  *
241  * @return 0 on success, less than 0 if an error occured.
242  */
243 int csync_propagate(CSYNC *ctx);
244 
245 /**
246  * @brief Commit the sync results to journal
247  *
248  * @param ctx The context to commit.
249  *
250  * @return 0 on success, less than 0 if an error occured.
251  */
252 int csync_commit(CSYNC *ctx);
253 
254 /**
255  * @brief Destroy the csync context
256  *
257  * Writes the statedb, unlocks csync and frees the memory.
258  *
259  * @param ctx The context to destroy.
260  *
261  * @return 0 on success, less than 0 if an error occured.
262  */
263 int csync_destroy(CSYNC *ctx);
264 
265 /**
266  * @brief Check if csync is the required version or get the version
267  * string.
268  *
269  * @param req_version The version required.
270  *
271  * @return If the version of csync is newer than the version
272  * required it will return a version string.
273  * NULL if the version is older.
274  *
275  * Example:
276  *
277  * @code
278  * if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) {
279  * fprintf(stderr, "libcsync version is too old!\n");
280  * exit(1);
281  * }
282  *
283  * if (debug) {
284  * printf("csync %s\n", csync_version(0));
285  * }
286  * @endcode
287  */
288 const char *csync_version(int req_version);
289 
290 /**
291  * @brief Add an additional exclude list.
292  *
293  * @param ctx The context to add the exclude list.
294  *
295  * @param path The path pointing to the file.
296  *
297  * @return 0 on success, less than 0 if an error occured.
298  */
299 int csync_add_exclude_list(CSYNC *ctx, const char *path);
300 
301 /**
302  * @brief Removes all items imported from exclude lists.
303  *
304  * @param ctx The context to add the exclude list.
305  */
307 
308 /**
309  * @brief Get the config directory.
310  *
311  * @param ctx The csync context.
312  *
313  * @return The path of the config directory or NULL on error.
314  */
315 const char *csync_get_config_dir(CSYNC *ctx);
316 
317 /**
318  * @brief Change the config directory.
319  *
320  * @param ctx The csync context.
321  *
322  * @param path The path to the new config directory.
323  *
324  * @return 0 on success, less than 0 if an error occured.
325  */
326 int csync_set_config_dir(CSYNC *ctx, const char *path);
327 
328 /**
329  * @brief Remove the complete config directory.
330  *
331  * @param ctx The csync context.
332  *
333  * @return 0 on success, less than 0 if an error occured.
334  */
336 
337 /**
338  * @brief Enable the usage of the statedb. It is enabled by default.
339  *
340  * @param ctx The csync context.
341  *
342  * @return 0 on success, less than 0 if an error occured.
343  */
344 int csync_enable_statedb(CSYNC *ctx);
345 
346 /**
347  * @brief Disable the usage of the statedb. It is enabled by default.
348  *
349  * @param ctx The csync context.
350  *
351  * @return 0 on success, less than 0 if an error occured.
352  */
353 int csync_disable_statedb(CSYNC *ctx);
354 
355 /**
356  * @brief Check if the statedb usage is enabled.
357  *
358  * @param ctx The csync context.
359  *
360  * @return 1 if it is enabled, 0 if it is disabled.
361  */
363 
364 /**
365  * @brief Get the userdata saved in the context.
366  *
367  * @param ctx The csync context.
368  *
369  * @return The userdata saved in the context, NULL if an error
370  * occured.
371  */
372 void *csync_get_userdata(CSYNC *ctx);
373 
374 /**
375  * @brief Save userdata to the context which is passed to the auth
376  * callback function.
377  *
378  * @param ctx The csync context.
379  *
380  * @param userdata The userdata to be stored in the context.
381  *
382  * @return 0 on success, less than 0 if an error occured.
383  */
384 int csync_set_userdata(CSYNC *ctx, void *userdata);
385 
386 /**
387  * @brief Get the authentication callback set.
388  *
389  * @param ctx The csync context.
390  *
391  * @return The authentication callback set or NULL if an error
392  * occured.
393  */
395 
396 /**
397  * @brief Set the authentication callback.
398  *
399  * @param ctx The csync context.
400  *
401  * @param cb The authentication callback.
402  *
403  * @return 0 on success, less than 0 if an error occured.
404  */
406 
407 /**
408  * @brief Set the log verbosity.
409  *
410  * @param ctx The csync context.
411  *
412  * @param[in] verbosity The log verbosity.
413  *
414  * @return 0 on success, < 0 if an error occured.
415  */
416 int csync_set_log_verbosity(CSYNC *ctx, int verbosity);
417 
418 /**
419  * @brief Get the log verbosity
420  *
421  * @param[in] ctx The csync context to ask for the log verbosity.
422  *
423  * @return The log verbosity, -1 on error.
424  */
426 
427 /**
428  * @brief Get the logging callback set.
429  *
430  * @param ctx The csync context.
431  *
432  * @return The logging callback set or NULL if an error
433  * occured.
434  */
436 
437 /**
438  * @brief Set the logging callback.
439  *
440  * @param ctx The csync context.
441  *
442  * @param cb The logging callback.
443  *
444  * @return 0 on success, less than 0 if an error occured.
445  */
447 
448 /**
449  * @brief Get the path of the statedb file used.
450  *
451  * @param ctx The csync context.
452  *
453  * @return The path to the statedb file, NULL if an error occured.
454  */
455 const char *csync_get_statedb_file(CSYNC *ctx);
456 
457 /**
458  * @brief Enable the creation of backup copys if files are changed on both sides
459  *
460  * @param ctx The csync context.
461  *
462  * @return 0 on success, less than 0 if an error occured.
463  */
465 
466 /**
467  * @brief Flag to tell csync that only a local run is intended. Call before csync_init
468  *
469  * @param local_only Bool flag to indicate local only mode.
470  *
471  * @return 0 on success, less than 0 if an error occured.
472  */
473 int csync_set_local_only( CSYNC *ctx, bool local_only );
474 
475 /**
476  * @brief Retrieve the flag to tell csync that only a local run is intended.
477  *
478  * @return 1: stay local only, 0: local and remote mode
479  */
480 bool csync_get_local_only( CSYNC *ctx );
481 
482 /* Used for special modes or debugging */
483 int csync_get_status(CSYNC *ctx);
484 
485 /* Used for special modes or debugging */
486 int csync_set_status(CSYNC *ctx, int status);
487 
489 
490 /**
491  * @brief Walk the local file tree and call a visitor function for each file.
492  *
493  * @param ctx The csync context.
494  * @param visitor A callback function to handle the file info.
495  * @param filter A filter, built from or'ed csync_instructions_e
496  *
497  * @return 0 on success, less than 0 if an error occured.
498  */
499 int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
500 
501 /**
502  * @brief Walk the remote file tree and call a visitor function for each file.
503  *
504  * @param ctx The csync context.
505  * @param visitor A callback function to handle the file info.
506  * @param filter A filter, built from and'ed csync_instructions_e
507  *
508  * @return 0 on success, less than 0 if an error occured.
509  */
510 int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
511 
512 /**
513  * @brief Set iconv source codec for filenames.
514  *
515  * @param from Source codec.
516  *
517  * @return 0 on success, or an iconv error number.
518  */
519 int csync_set_iconv_codec(const char *from);
520 
521 /**
522  * @brief Get the error code from the last operation.
523  *
524  * @return An error code defined by structure CSYNC_ERROR_CODE
525  */
526 CSYNC_ERROR_CODE csync_get_error(CSYNC *ctx);
527 
528 /**
529  * @brief csync_get_error_string - return a string with error information
530  * @param ctx
531  * @return A pointer to an error string or NULL.
532  */
533 const char *csync_get_error_string(CSYNC *ctx);
534 
535 /**
536  * @brief Set a property to module
537  *
538  * @param ctx The csync context.
539  *
540  * @param key The property key
541  *
542  * @param value An opaque pointer to the data.
543  *
544  * @return 0 on success, less than 0 if an error occured.
545  */
546 int csync_set_module_property(CSYNC *ctx, const char *key, void *value);
547 
548 /**
549  * @brief Callback definition for file progress callback.
550  *
551  * @param progress A struct containing progress information.
552  *
553  * @param userdata User defined data for the callback.
554  */
555 typedef void (*csync_progress_callback)( CSYNC_PROGRESS *progress, void *userdata);
556 
557 /**
558  * @brief Set a progress callback.
559  *
560  * This callback reports about up- or download progress of a individual file
561  * as well as overall progress.
562  */
564 
566 
567 /**
568  * @brief Aborts the current sync run as soon as possible. Can be called from another thread.
569  *
570  * @param ctx The csync context.
571  */
572 void csync_request_abort(CSYNC *ctx);
573 
574 /**
575  * @brief Clears the abort flag. Can be called from another thread.
576  *
577  * @param ctx The csync context.
578  */
579 void csync_resume(CSYNC *ctx);
580 
581 /**
582  * @brief Checks for the abort flag, to be used from the modules.
583  *
584  * @param ctx The csync context.
585  */
586 int csync_abort_requested(CSYNC *ctx);
587 
588 #ifdef __cplusplus
589 }
590 #endif
591 
592 /**
593  * }@
594  */
595 #endif /* _CSYNC_H */
596 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */