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 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 #define CSYNC_STRINGIFY(s) CSYNC_TOSTRING(s)
44 #define CSYNC_TOSTRING(s) #s
45 
46 /* csync version macros */
47 #define CSYNC_VERSION_INT(a, b, c) ((a) << 16 | (b) << 8 | (c))
48 #define CSYNC_VERSION_DOT(a, b, c) a ##.## b ##.## c
49 #define CSYNC_VERSION(a, b, c) CSYNC_VERSION_DOT(a, b, c)
50 
51 /* csync version */
52 #define LIBCSYNC_VERSION_MAJOR 0
53 #define LIBCSYNC_VERSION_MINOR 70
54 #define LIBCSYNC_VERSION_MICRO 6
55 
56 #define LIBCSYNC_VERSION_INT CSYNC_VERSION_INT(LIBCSYNC_VERSION_MAJOR, \
57  LIBCSYNC_VERSION_MINOR, \
58  LIBCSYNC_VERSION_MICRO)
59 #define LIBCSYNC_VERSION CSYNC_VERSION(LIBCSYNC_VERSION_MAJOR, \
60  LIBCSYNC_VERSION_MINOR, \
61  LIBCSYNC_VERSION_MICRO)
62 
63 /*
64  * csync file declarations
65  */
66 #define CSYNC_CONF_DIR ".ocsync"
67 #define CSYNC_CONF_FILE "ocsync.conf"
68 #define CSYNC_EXCLUDE_FILE "ocsync_exclude.conf"
69 #define CSYNC_LOCK_FILE "lock"
70 
104 
106 };
108 
109 /**
110  * Instruction enum. In the file traversal structure, it describes
111  * the csync state of a file.
112  */
118  CSYNC_INSTRUCTION_NEW = 0x00000008,
124  /* instructions for the propagator */
127 };
128 
134 };
135 
136 
137 /**
138  * CSync File Traversal structure.
139  *
140  * This structure is passed to the visitor function for every file
141  * which is seen.
142  * Note: The file size is missing here because type off_t is depending
143  * on the large file support in your build. Make sure to check
144  * that cmake and the callback app are compiled with the same
145  * setting for it, such as:
146  * -D_LARGEFILE64_SOURCE or -D_LARGEFILE_SOURCE
147  *
148  */
150  const char *path;
151  /* off_t size; */
152  time_t modtime;
153 #ifdef _WIN32
154  uint32_t uid;
155  uint32_t gid;
156 #else
157  uid_t uid;
158  gid_t gid;
159 #endif
160  mode_t mode;
163 
164  const char *rename_path;
165 };
167 
168 /**
169  * csync handle
170  */
171 typedef struct csync_s CSYNC;
172 
173 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
174  int echo, int verify, void *userdata);
175 
176 typedef void (*csync_log_callback) (CSYNC *ctx,
177  int verbosity,
178  const char *function,
179  const char *buffer,
180  void *userdata);
181 
182 /**
183  * @brief Allocate a csync context.
184  *
185  * @param csync The context variable to allocate.
186  *
187  * @return 0 on success, less than 0 if an error occured.
188  */
189 int csync_create(CSYNC **csync, const char *local, const char *remote);
190 
191 /**
192  * @brief Initialize the file synchronizer.
193  *
194  * This function loads the configuration, the statedb and locks the client.
195  *
196  * @param ctx The context to initialize.
197  *
198  * @return 0 on success, less than 0 if an error occured.
199  */
200 int csync_init(CSYNC *ctx);
201 
202 /**
203  * @brief Update detection
204  *
205  * @param ctx The context to run the update detection on.
206  *
207  * @return 0 on success, less than 0 if an error occured.
208  */
209 int csync_update(CSYNC *ctx);
210 
211 /**
212  * @brief Reconciliation
213  *
214  * @param ctx The context to run the reconciliation on.
215  *
216  * @return 0 on success, less than 0 if an error occured.
217  */
218 int csync_reconcile(CSYNC *ctx);
219 
220 /**
221  * @brief Propagation
222  *
223  * @param ctx The context to run the propagation on.
224  *
225  * @return 0 on success, less than 0 if an error occured.
226  */
227 int csync_propagate(CSYNC *ctx);
228 
229 /**
230  * @brief Destroy the csync context
231  *
232  * Writes the statedb, unlocks csync and frees the memory.
233  *
234  * @param ctx The context to destroy.
235  *
236  * @return 0 on success, less than 0 if an error occured.
237  */
238 int csync_destroy(CSYNC *ctx);
239 
240 /**
241  * @brief Check if csync is the required version or get the version
242  * string.
243  *
244  * @param req_version The version required.
245  *
246  * @return If the version of csync is newer than the version
247  * required it will return a version string.
248  * NULL if the version is older.
249  *
250  * Example:
251  *
252  * @code
253  * if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) {
254  * fprintf(stderr, "libcsync version is too old!\n");
255  * exit(1);
256  * }
257  *
258  * if (debug) {
259  * printf("csync %s\n", csync_version(0));
260  * }
261  * @endcode
262  */
263 const char *csync_version(int req_version);
264 
265 /**
266  * @brief Add an additional exclude list.
267  *
268  * @param ctx The context to add the exclude list.
269  *
270  * @param path The path pointing to the file.
271  *
272  * @return 0 on success, less than 0 if an error occured.
273  */
274 int csync_add_exclude_list(CSYNC *ctx, const char *path);
275 
276 /**
277  * @brief Get the config directory.
278  *
279  * @param ctx The csync context.
280  *
281  * @return The path of the config directory or NULL on error.
282  */
283 const char *csync_get_config_dir(CSYNC *ctx);
284 
285 /**
286  * @brief Change the config directory.
287  *
288  * @param ctx The csync context.
289  *
290  * @param path The path to the new config directory.
291  *
292  * @return 0 on success, less than 0 if an error occured.
293  */
294 int csync_set_config_dir(CSYNC *ctx, const char *path);
295 
296 /**
297  * @brief Remove the complete config directory.
298  *
299  * @param ctx The csync context.
300  *
301  * @return 0 on success, less than 0 if an error occured.
302  */
304 
305 /**
306  * @brief Enable the usage of the statedb. It is enabled by default.
307  *
308  * @param ctx The csync context.
309  *
310  * @return 0 on success, less than 0 if an error occured.
311  */
312 int csync_enable_statedb(CSYNC *ctx);
313 
314 /**
315  * @brief Disable the usage of the statedb. It is enabled by default.
316  *
317  * @param ctx The csync context.
318  *
319  * @return 0 on success, less than 0 if an error occured.
320  */
321 int csync_disable_statedb(CSYNC *ctx);
322 
323 /**
324  * @brief Check if the statedb usage is enabled.
325  *
326  * @param ctx The csync context.
327  *
328  * @return 1 if it is enabled, 0 if it is disabled.
329  */
331 
332 /**
333  * @brief Get the userdata saved in the context.
334  *
335  * @param ctx The csync context.
336  *
337  * @return The userdata saved in the context, NULL if an error
338  * occured.
339  */
340 void *csync_get_userdata(CSYNC *ctx);
341 
342 /**
343  * @brief Save userdata to the context which is passed to the auth
344  * callback function.
345  *
346  * @param ctx The csync context.
347  *
348  * @param userdata The userdata to be stored in the context.
349  *
350  * @return 0 on success, less than 0 if an error occured.
351  */
352 int csync_set_userdata(CSYNC *ctx, void *userdata);
353 
354 /**
355  * @brief Get the authentication callback set.
356  *
357  * @param ctx The csync context.
358  *
359  * @return The authentication callback set or NULL if an error
360  * occured.
361  */
363 
364 /**
365  * @brief Set the authentication callback.
366  *
367  * @param ctx The csync context.
368  *
369  * @param cb The authentication callback.
370  *
371  * @return 0 on success, less than 0 if an error occured.
372  */
374 
375 /**
376  * @brief Set the log verbosity.
377  *
378  * @param ctx The csync context.
379  *
380  * @param[in] verbosity The log verbosity.
381  *
382  * @return 0 on success, < 0 if an error occured.
383  */
384 int csync_set_log_verbosity(CSYNC *ctx, int verbosity);
385 
386 /**
387  * @brief Get the log verbosity
388  *
389  * @param[in] ctx The csync context to ask for the log verbosity.
390  *
391  * @return The log verbosity, -1 on error.
392  */
394 
395 /**
396  * @brief Get the logging callback set.
397  *
398  * @param ctx The csync context.
399  *
400  * @return The logging callback set or NULL if an error
401  * occured.
402  */
404 
405 /**
406  * @brief Set the logging callback.
407  *
408  * @param ctx The csync context.
409  *
410  * @param cb The logging callback.
411  *
412  * @return 0 on success, less than 0 if an error occured.
413  */
415 
416 /**
417  * @brief Get the path of the statedb file used.
418  *
419  * @param ctx The csync context.
420  *
421  * @return The path to the statedb file, NULL if an error occured.
422  */
423 const char *csync_get_statedb_file(CSYNC *ctx);
424 
425 /**
426  * @brief Enable the creation of backup copys if files are changed on both sides
427  *
428  * @param ctx The csync context.
429  *
430  * @return 0 on success, less than 0 if an error occured.
431  */
433 
434 /**
435  * @brief Flag to tell csync that only a local run is intended. Call before csync_init
436  *
437  * @param local_only Bool flag to indicate local only mode.
438  *
439  * @return 0 on success, less than 0 if an error occured.
440  */
441 int csync_set_local_only( CSYNC *ctx, bool local_only );
442 
443 /**
444  * @brief Retrieve the flag to tell csync that only a local run is intended.
445  *
446  * @return 1: stay local only, 0: local and remote mode
447  */
448 bool csync_get_local_only( CSYNC *ctx );
449 
450 /* Used for special modes or debugging */
451 int csync_get_status(CSYNC *ctx);
452 
453 /* Used for special modes or debugging */
454 int csync_set_status(CSYNC *ctx, int status);
455 
457 
458 /**
459  * @brief Walk the local file tree and call a visitor function for each file.
460  *
461  * @param ctx The csync context.
462  * @param visitor A callback function to handle the file info.
463  * @param filter A filter, built from or'ed csync_instructions_e
464  *
465  * @return 0 on success, less than 0 if an error occured.
466  */
467 int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
468 
469 /**
470  * @brief Walk the remote file tree and call a visitor function for each file.
471  *
472  * @param ctx The csync context.
473  * @param visitor A callback function to handle the file info.
474  * @param filter A filter, built from and'ed csync_instructions_e
475  *
476  * @return 0 on success, less than 0 if an error occured.
477  */
478 int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
479 
480 /**
481  * @brief Set iconv source codec for filenames.
482  *
483  * @param from Source codec.
484  *
485  * @return 0 on success, or an iconv error number.
486  */
487 int csync_set_iconv_codec(const char *from);
488 
489 /**
490  * @brief Get the error code from the last operation.
491  *
492  * @return An error code defined by structure CSYNC_ERROR_CODE
493  */
494 CSYNC_ERROR_CODE csync_get_error(CSYNC *ctx);
495 
496 /**
497  * @brief csync_get_error_string - return a string with error information
498  * @param ctx
499  * @return A pointer to an error string or NULL.
500  */
501 const char *csync_get_error_string(CSYNC *ctx);
502 
503 /**
504  * @brief Set a property to module
505  *
506  * @param ctx The csync context.
507  *
508  * @param key The property key
509  *
510  * @param value An opaque pointer to the data.
511  *
512  * @return 0 on success, less than 0 if an error occured.
513  */
514 int csync_set_module_property(CSYNC *ctx, const char *key, void *value);
515 
519 
520 typedef void (*csync_progress_callback) (const char *remote_url, enum csync_notify_type_e kind,
521  long long o1, long long o2, void *userdata);
522 /**
523  * @brief Set a progress callback
524  *
525  * @param ctx The csync context.
526  *
527  * @param cb The callback
528  */
530 
531 
532 
533 #ifdef __cplusplus
534 }
535 #endif
536 
537 /**
538  * }@
539  */
540 #endif /* _CSYNC_H */
541 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */