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) 2008-2013 by Andreas Schneider <asn@cryptomilk.org>
5  * Copyright (c) 2012-2013 by Klaas Freitag <freitag@owncloud.com>
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21 
22 /**
23  * @file csync.h
24  *
25  * @brief Application developer interface for csync.
26  *
27  * @defgroup csyncPublicAPI csync public API
28  *
29  * @{
30  */
31 
32 #ifndef _CSYNC_H
33 #define _CSYNC_H
34 
35 #include <stdbool.h>
36 #include <stdint.h>
37 #include <unistd.h>
38 #include <sys/types.h>
39 #include <config.h>
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 #define CSYNC_STRINGIFY(s) CSYNC_TOSTRING(s)
46 #define CSYNC_TOSTRING(s) #s
47 
48 /* csync version macros */
49 #define CSYNC_VERSION_INT(a, b, c) ((a) << 16 | (b) << 8 | (c))
50 #define CSYNC_VERSION_DOT(a, b, c) a ##.## b ##.## c
51 #define CSYNC_VERSION(a, b, c) CSYNC_VERSION_DOT(a, b, c)
52 
53 /* csync version */
54 #define LIBCSYNC_VERSION_MAJOR 0
55 #define LIBCSYNC_VERSION_MINOR 50
56 #define LIBCSYNC_VERSION_MICRO 0
57 
58 #define LIBCSYNC_VERSION_INT CSYNC_VERSION_INT(LIBCSYNC_VERSION_MAJOR, \
59  LIBCSYNC_VERSION_MINOR, \
60  LIBCSYNC_VERSION_MICRO)
61 #define LIBCSYNC_VERSION CSYNC_VERSION(LIBCSYNC_VERSION_MAJOR, \
62  LIBCSYNC_VERSION_MINOR, \
63  LIBCSYNC_VERSION_MICRO)
64 
65 /*
66  * csync file declarations
67  */
68 #define CSYNC_CONF_DIR ".csync"
69 #define CSYNC_CONF_FILE "csync.conf"
70 #define CSYNC_EXCLUDE_FILE "csync_exclude.conf"
71 #define CSYNC_LOCK_FILE "lock"
72 
73 /**
74  * Instruction enum. In the file traversal structure, it describes
75  * the csync state of a file.
76  */
79 
80  CSYNC_STATUS_ERROR = 1024, /* don't use this code,
81  just use in csync_status_ok */
120 };
121 
123 
124 #ifndef likely
125 # define likely(x) (x)
126 #endif
127 #ifndef unlikely
128 # define unlikely(x) (x)
129 #endif
130 
131 #define CSYNC_STATUS_IS_OK(x) (likely((x) == CSYNC_STATUS_OK))
132 #define CSYNC_STATUS_IS_ERR(x) (unlikely((x) >= CSYNC_STATUS_ERROR))
133 #define CSYNC_STATUS_IS_EQUAL(x, y) ((x) == (y))
134 
140  CSYNC_INSTRUCTION_NEW = 0x00000008,
146  /* instructions for the propagator */
149 };
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 off_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;
175  int type;
177 };
179 
180 /**
181  * csync handle
182  */
183 typedef struct csync_s CSYNC;
184 
185 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
186  int echo, int verify, void *userdata);
187 
188 typedef void (*csync_log_callback) (int verbosity,
189  const char *function,
190  const char *buffer,
191  void *userdata);
192 
193 /**
194  * @brief Check internal csync status.
195  *
196  * @param csync The context to check.
197  *
198  * @return true if status is error free, false for error states.
199  */
200 bool csync_status_ok(CSYNC *ctx);
201 
202 /**
203  * @brief Allocate a csync context.
204  *
205  * @param csync The context variable to allocate.
206  *
207  * @return 0 on success, less than 0 if an error occured.
208  */
209 int csync_create(CSYNC **csync, const char *local, const char *remote);
210 
211 /**
212  * @brief Initialize the file synchronizer.
213  *
214  * This function loads the configuration, the statedb and locks the client.
215  *
216  * @param ctx The context to initialize.
217  *
218  * @return 0 on success, less than 0 if an error occured.
219  */
220 int csync_init(CSYNC *ctx);
221 
222 /**
223  * @brief Update detection
224  *
225  * @param ctx The context to run the update detection on.
226  *
227  * @return 0 on success, less than 0 if an error occured.
228  */
229 int csync_update(CSYNC *ctx);
230 
231 /**
232  * @brief Reconciliation
233  *
234  * @param ctx The context to run the reconciliation on.
235  *
236  * @return 0 on success, less than 0 if an error occured.
237  */
238 int csync_reconcile(CSYNC *ctx);
239 
240 /**
241  * @brief Propagation
242  *
243  * @param ctx The context to run the propagation on.
244  *
245  * @return 0 on success, less than 0 if an error occured.
246  */
247 int csync_propagate(CSYNC *ctx);
248 
249 /**
250  * @brief Commit the sync results to journal
251  *
252  * @param ctx The context to commit.
253  *
254  * @return 0 on success, less than 0 if an error occured.
255  */
256 int csync_commit(CSYNC *ctx);
257 
258 /**
259  * @brief Destroy the csync context
260  *
261  * Writes the statedb, unlocks csync and frees the memory.
262  *
263  * @param ctx The context to destroy.
264  *
265  * @return 0 on success, less than 0 if an error occured.
266  */
267 int csync_destroy(CSYNC *ctx);
268 
269 /**
270  * @brief Check if csync is the required version or get the version
271  * string.
272  *
273  * @param req_version The version required.
274  *
275  * @return If the version of csync is newer than the version
276  * required it will return a version string.
277  * NULL if the version is older.
278  *
279  * Example:
280  *
281  * @code
282  * if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) {
283  * fprintf(stderr, "libcsync version is too old!\n");
284  * exit(1);
285  * }
286  *
287  * if (debug) {
288  * printf("csync %s\n", csync_version(0));
289  * }
290  * @endcode
291  */
292 const char *csync_version(int req_version);
293 
294 /**
295  * @brief Add an additional exclude list.
296  *
297  * @param ctx The context to add the exclude list.
298  *
299  * @param path The path pointing to the file.
300  *
301  * @return 0 on success, less than 0 if an error occured.
302  */
303 int csync_add_exclude_list(CSYNC *ctx, const char *path);
304 
305 /**
306  * @brief Get the config directory.
307  *
308  * @param ctx The csync context.
309  *
310  * @return The path of the config directory or NULL on error.
311  */
312 const char *csync_get_config_dir(CSYNC *ctx);
313 
314 /**
315  * @brief Change the config directory.
316  *
317  * @param ctx The csync context.
318  *
319  * @param path The path to the new config directory.
320  *
321  * @return 0 on success, less than 0 if an error occured.
322  */
323 int csync_set_config_dir(CSYNC *ctx, const char *path);
324 
325 /**
326  * @brief Remove the complete config directory.
327  *
328  * @param ctx The csync context.
329  *
330  * @return 0 on success, less than 0 if an error occured.
331  */
333 
334 /**
335  * @brief Enable the usage of the statedb. It is enabled by default.
336  *
337  * @param ctx The csync context.
338  *
339  * @return 0 on success, less than 0 if an error occured.
340  */
341 int csync_enable_statedb(CSYNC *ctx);
342 
343 /**
344  * @brief Disable the usage of the statedb. It is enabled by default.
345  *
346  * @param ctx The csync context.
347  *
348  * @return 0 on success, less than 0 if an error occured.
349  */
350 int csync_disable_statedb(CSYNC *ctx);
351 
352 /**
353  * @brief Check if the statedb usage is enabled.
354  *
355  * @param ctx The csync context.
356  *
357  * @return 1 if it is enabled, 0 if it is disabled.
358  */
360 
361 /**
362  * @brief Get the userdata saved in the context.
363  *
364  * @param ctx The csync context.
365  *
366  * @return The userdata saved in the context, NULL if an error
367  * occured.
368  */
369 void *csync_get_userdata(CSYNC *ctx);
370 
371 /**
372  * @brief Save userdata to the context which is passed to the auth
373  * callback function.
374  *
375  * @param ctx The csync context.
376  *
377  * @param userdata The userdata to be stored in the context.
378  *
379  * @return 0 on success, less than 0 if an error occured.
380  */
381 int csync_set_userdata(CSYNC *ctx, void *userdata);
382 
383 /**
384  * @brief Get the authentication callback set.
385  *
386  * @param ctx The csync context.
387  *
388  * @return The authentication callback set or NULL if an error
389  * occured.
390  */
392 
393 /**
394  * @brief Set the authentication callback.
395  *
396  * @param ctx The csync context.
397  *
398  * @param cb The authentication callback.
399  *
400  * @return 0 on success, less than 0 if an error occured.
401  */
403 
404 /**
405  * @brief Set the log level.
406  *
407  * @param[in] level The log verbosity.
408  *
409  * @return 0 on success, < 0 if an error occured.
410  */
411 int csync_set_log_level(int level);
412 
413 /**
414  * @brief Get the log verbosity
415  *
416  * @return The log verbosity, -1 on error.
417  */
418 int csync_get_log_level(void);
419 
420 /**
421  * @brief Get the logging callback set.
422  *
423  * @return The logging callback set or NULL if an error
424  * occured.
425  */
427 
428 /**
429  * @brief Set the logging callback.
430  *
431  * @param cb The logging callback.
432  *
433  * @return 0 on success, less than 0 if an error occured.
434  */
436 
437 /**
438  * @brief get the userdata set for the logging callback.
439  *
440  * @return The userdata or NULL.
441  */
442 void *csync_get_log_userdata(void);
443 
444 /**
445  * @brief Set the userdata passed to the logging callback.
446  *
447  * @param[in] data The userdata to set.
448  *
449  * @return 0 on success, less than 0 if an error occured.
450  */
451 int csync_set_log_userdata(void *data);
452 
453 /**
454  * @brief Get the path of the statedb file used.
455  *
456  * @param ctx The csync context.
457  *
458  * @return The path to the statedb file, NULL if an error occured.
459  */
460 const char *csync_get_statedb_file(CSYNC *ctx);
461 
462 /**
463  * @brief Enable the creation of backup copys if files are changed on both sides
464  *
465  * @param ctx The csync context.
466  *
467  * @return 0 on success, less than 0 if an error occured.
468  */
470 
471 /**
472  * @brief Flag to tell csync that only a local run is intended. Call before csync_init
473  *
474  * @param local_only Bool flag to indicate local only mode.
475  *
476  * @return 0 on success, less than 0 if an error occured.
477  */
478 int csync_set_local_only( CSYNC *ctx, bool local_only );
479 
480 /**
481  * @brief Retrieve the flag to tell csync that only a local run is intended.
482  *
483  * @return 1: stay local only, 0: local and remote mode
484  */
485 bool csync_get_local_only( CSYNC *ctx );
486 
487 /* Used for special modes or debugging */
488 int csync_get_status(CSYNC *ctx);
489 
490 /* Used for special modes or debugging */
491 int csync_set_status(CSYNC *ctx, int status);
492 
494 
495 /**
496  * @brief Walk the local file tree and call a visitor function for each file.
497  *
498  * @param ctx The csync context.
499  * @param visitor A callback function to handle the file info.
500  * @param filter A filter, built from and'ed csync_instructions_e
501  *
502  * @return 0 on success, less than 0 if an error occured.
503  */
504 int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
505 
506 /**
507  * @brief Walk the remote file tree and call a visitor function for each file.
508  *
509  * @param ctx The csync context.
510  * @param visitor A callback function to handle the file info.
511  * @param filter A filter, built from and'ed csync_instructions_e
512  *
513  * @return 0 on success, less than 0 if an error occured.
514  */
515 int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
516 
517 /**
518  * @brief Get the csync status string.
519  *
520  * @param ctx The csync context.
521  *
522  * @return A const pointer to a string with more precise status info.
523  */
524 const char *csync_get_status_string(CSYNC *ctx);
525 
526 #ifdef WITH_ICONV
527 /**
528  * @brief Set iconv source codec for filenames.
529  *
530  * @param from Source codec.
531  *
532  * @return 0 on success, or an iconv error number.
533  */
534 int csync_set_iconv_codec(const char *from);
535 #endif
536 
537 /**
538  * @brief Set a property to module
539  *
540  * @param ctx The csync context.
541  *
542  * @param key The property key
543  *
544  * @param value An opaque pointer to the data.
545  *
546  * @return 0 on success, less than 0 if an error occured.
547  */
548 int csync_set_module_property(CSYNC *ctx, const char *key, void *value);
549 
550 
551 /*
552  * Progress callbacks.
553  */
557 
558 /**
559  * @brief Callback definition for individual file progress callback.
560  *
561  * @param remote_url The currently handled file.
562  *
563  * @param kind The type of progress.
564  *
565  * @param o1 The current transmitted bytes.
566  *
567  * @param o2 The size of the file.
568  */
569 typedef void (*csync_file_progress_callback) (const char *remote_url, enum csync_notify_type_e kind,
570  long long o1, long long o2, void *userdata);
571 
572 /**
573  * @brief Set a progress callback for individual files.
574  *
575  * This callback reports about up- or download progress of a individual file.
576  *
577  * @param ctx The csync context.
578  *
579  * @param cb The callback
580  */
582 
583 /**
584  * @brief Callback definition for overall progress callback.
585  *
586  * @param file_no The current number of up- or downloaded files.
587  *
588  * @param file_cnt The overall number of files to transmit.
589  *
590  * @param o1 The current transmitted bytes.
591  *
592  * @param o2 The overall sum of bytes to transmit.
593  *
594  * @param userdata The user data pointer.
595  */
596 typedef void (*csync_overall_progress_callback) (const char *file_name,
597  int file_no,
598  int file_cnt,
599  long long o1,
600  long long o2,
601  void *userdata);
602 
603 /**
604  * @brief Set a progress callback for the overall files.
605  *
606  * This callback reports about overall up- or download progress.
607  *
608  * @param ctx The csync context.
609  *
610  * @param cb The callback
611  */
613 
614 #ifdef __cplusplus
615 }
616 #endif
617 
618 /**
619  * }@
620  */
621 #endif /* _CSYNC_H */
622 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */
csync_auth_callback csync_get_auth_callback(CSYNC *ctx)
Get the authentication callback set.
csync_instructions_e
Definition: csync.h:135
int csync_get_status(CSYNC *ctx)
int csync_is_statedb_disabled(CSYNC *ctx)
Check if the statedb usage is enabled.
const char * path
Definition: csync.h:164
int csync_set_auth_callback(CSYNC *ctx, csync_auth_callback cb)
Set the authentication callback.
int csync_set_file_progress_callback(CSYNC *ctx, csync_file_progress_callback cb)
Set a progress callback for individual files.
csync_notify_type_e
Definition: csync.h:554
int(* csync_auth_callback)(const char *prompt, char *buf, size_t len, int echo, int verify, void *userdata)
Definition: csync.h:185
int csync_set_log_userdata(void *data)
Set the userdata passed to the logging callback.
const char * csync_get_statedb_file(CSYNC *ctx)
Get the path of the statedb file used.
struct csync_s::@2 local
void * csync_get_log_userdata(void)
get the userdata set for the logging callback.
CSync File Traversal structure.
Definition: csync.h:163
int csync_set_status(CSYNC *ctx, int status)
int csync_treewalk_visit_func(TREE_WALK_FILE *, void *)
Definition: csync.h:493
const char * csync_get_status_string(CSYNC *ctx)
Get the csync status string.
void(* csync_log_callback)(int verbosity, const char *function, const char *buffer, void *userdata)
Definition: csync.h:188
bool csync_status_ok(CSYNC *ctx)
Check internal csync status.
int csync_propagate(CSYNC *ctx)
Propagation.
struct csync_s::@3 remote
enum csync_instructions_e instruction
Definition: csync.h:176
int csync_reconcile(CSYNC *ctx)
Reconciliation.
int csync_set_local_only(CSYNC *ctx, bool local_only)
Flag to tell csync that only a local run is intended.
csync public structure
Definition: csync_private.h:89
csync_status_codes_e
Instruction enum.
Definition: csync.h:77
int csync_set_module_property(CSYNC *ctx, const char *key, void *value)
Set a property to module.
int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter)
Walk the local file tree and call a visitor function for each file.
int csync_init(CSYNC *ctx)
Initialize the file synchronizer.
int csync_get_log_level(void)
Get the log verbosity.
int csync_set_overall_progress_callback(CSYNC *ctx, csync_overall_progress_callback cb)
Set a progress callback for the overall files.
bool csync_get_local_only(CSYNC *ctx)
Retrieve the flag to tell csync that only a local run is intended.
int csync_disable_statedb(CSYNC *ctx)
Disable the usage of the statedb.
int csync_set_userdata(CSYNC *ctx, void *userdata)
Save userdata to the context which is passed to the auth callback function.
int csync_update(CSYNC *ctx)
Update detection.
int csync_add_exclude_list(CSYNC *ctx, const char *path)
Add an additional exclude list.
int csync_create(CSYNC **csync, const char *local, const char *remote)
Allocate a csync context.
int csync_set_config_dir(CSYNC *ctx, const char *path)
Change the config directory.
enum csync_status_codes_e CSYNC_STATUS
Definition: csync.h:122
int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter)
Walk the remote file tree and call a visitor function for each file.
int csync_enable_conflictcopys(CSYNC *ctx)
Enable the creation of backup copys if files are changed on both sides.
int csync_commit(CSYNC *ctx)
Commit the sync results to journal.
void * csync_get_userdata(CSYNC *ctx)
Get the userdata saved in the context.
csync_log_callback csync_get_log_callback(void)
Get the logging callback set.
char path[1]
Definition: csync_private.h:44
int csync_set_log_level(int level)
Set the log level.
void(* csync_overall_progress_callback)(const char *file_name, int file_no, int file_cnt, long long o1, long long o2, void *userdata)
Callback definition for overall progress callback.
Definition: csync.h:596
void(* csync_file_progress_callback)(const char *remote_url, enum csync_notify_type_e kind, long long o1, long long o2, void *userdata)
Callback definition for individual file progress callback.
Definition: csync.h:569
int csync_destroy(CSYNC *ctx)
Destroy the csync context.
int csync_remove_config_dir(CSYNC *ctx)
Remove the complete config directory.
int csync_set_log_callback(csync_log_callback cb)
Set the logging callback.
int csync_enable_statedb(CSYNC *ctx)
Enable the usage of the statedb.
void * userdata
Definition: csync_private.h:94
const char * csync_get_config_dir(CSYNC *ctx)
Get the config directory.
const char * csync_version(int req_version)
Check if csync is the required version or get the version string.