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
42extern "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
146 /* instructions for the propagator */
148 CSYNC_INSTRUCTION_UPDATED = 0x00000400
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 */
183typedef struct csync_s CSYNC;
184
185typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
186 int echo, int verify, void *userdata);
187
188typedef 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 */
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 */
209int 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 */
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 */
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 */
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 */
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 */
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 */
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 */
292const 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 */
303int 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 */
312const 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 */
323int 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 */
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 */
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 */
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 */
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 */
411int csync_set_log_level(int level);
412
413/**
414 * @brief Get the log verbosity
415 *
416 * @return The log verbosity, -1 on error.
417 */
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 */
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 */
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 */
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 */
478int 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 */
486
487/* Used for special modes or debugging */
489
490/* Used for special modes or debugging */
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 */
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 */
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 */
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 */
534int 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 */
548int 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 */
569typedef 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 */
596typedef 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: */
struct csync_s::@3 remote
char path[1]
void * userdata
struct csync_s::@2 local
int csync_create(CSYNC **csync, const char *local, const char *remote)
Allocate a csync context.
int csync_treewalk_visit_func(TREE_WALK_FILE *, void *)
Definition csync.h:493
const char * path
Definition csync.h:164
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
const char * csync_get_config_dir(CSYNC *ctx)
Get the config directory.
int csync_enable_statedb(CSYNC *ctx)
Enable the usage of the statedb.
int csync_set_log_callback(csync_log_callback cb)
Set the logging callback.
csync_instructions_e
Definition csync.h:135
int csync_set_module_property(CSYNC *ctx, const char *key, void *value)
Set a property to module.
bool csync_status_ok(CSYNC *ctx)
Check internal csync status.
int csync_commit(CSYNC *ctx)
Commit the sync results to journal.
csync_notify_type_e
Definition csync.h:554
int csync_set_overall_progress_callback(CSYNC *ctx, csync_overall_progress_callback cb)
Set a progress callback for the overall files.
int csync_propagate(CSYNC *ctx)
Propagation.
int csync_get_status(CSYNC *ctx)
enum csync_instructions_e instruction
Definition csync.h:176
int csync_set_file_progress_callback(CSYNC *ctx, csync_file_progress_callback cb)
Set a progress callback for individual files.
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
bool csync_get_local_only(CSYNC *ctx)
Retrieve the flag to tell csync that only a local run is intended.
int csync_set_status(CSYNC *ctx, int status)
int csync_set_log_level(int level)
Set the log level.
int csync_set_local_only(CSYNC *ctx, bool local_only)
Flag to tell csync that only a local run is intended.
void(* csync_log_callback)(int verbosity, const char *function, const char *buffer, void *userdata)
Definition csync.h:188
int csync_disable_statedb(CSYNC *ctx)
Disable the usage of the statedb.
const char * csync_get_status_string(CSYNC *ctx)
Get the csync status string.
int csync_get_log_level(void)
Get the log verbosity.
int csync_set_auth_callback(CSYNC *ctx, csync_auth_callback cb)
Set the authentication callback.
void * csync_get_log_userdata(void)
get the userdata set for the logging callback.
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_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.
csync_log_callback csync_get_log_callback(void)
Get the logging callback set.
csync_auth_callback csync_get_auth_callback(CSYNC *ctx)
Get the authentication callback set.
int csync_remove_config_dir(CSYNC *ctx)
Remove the complete config directory.
const char * csync_get_statedb_file(CSYNC *ctx)
Get the path of the statedb file used.
int csync_is_statedb_disabled(CSYNC *ctx)
Check if the statedb usage is enabled.
int csync_init(CSYNC *ctx)
Initialize the file synchronizer.
int csync_reconcile(CSYNC *ctx)
Reconciliation.
int csync_destroy(CSYNC *ctx)
Destroy the csync context.
const char * csync_version(int req_version)
Check if csync is the required version or get the version string.
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_set_log_userdata(void *data)
Set the userdata passed to the logging callback.
void * csync_get_userdata(CSYNC *ctx)
Get the userdata saved in the context.
int csync_add_exclude_list(CSYNC *ctx, const char *path)
Add an additional exclude list.
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_auth_callback)(const char *prompt, char *buf, size_t len, int echo, int verify, void *userdata)
Definition csync.h:185
csync_status_codes_e
Instruction enum.
Definition csync.h:77
@ CSYNC_INSTRUCTION_SYNC
Definition csync.h:143
@ CSYNC_INSTRUCTION_REMOVE
Definition csync.h:138
@ CSYNC_INSTRUCTION_DELETED
Definition csync.h:147
@ CSYNC_INSTRUCTION_EVAL
Definition csync.h:137
@ CSYNC_INSTRUCTION_IGNORE
Definition csync.h:142
@ CSYNC_INSTRUCTION_UPDATED
Definition csync.h:148
@ CSYNC_INSTRUCTION_ERROR
Definition csync.h:145
@ CSYNC_INSTRUCTION_NEW
Definition csync.h:140
@ CSYNC_INSTRUCTION_STAT_ERROR
Definition csync.h:144
@ CSYNC_INSTRUCTION_RENAME
Definition csync.h:139
@ CSYNC_INSTRUCTION_NONE
Definition csync.h:136
@ CSYNC_INSTRUCTION_CONFLICT
Definition csync.h:141
@ CSYNC_NOTIFY_PROGRESS
Definition csync.h:555
@ CSYNC_NOTIFY_FINISHED_UPLOAD
Definition csync.h:556
@ CSYNC_NOTIFY_START_UPLOAD
Definition csync.h:554
@ CSYNC_NOTIFY_START_DOWNLOAD
Definition csync.h:554
@ CSYNC_NOTIFY_FINISHED_DOWNLOAD
Definition csync.h:555
@ CSYNC_STATUS_FILESYSTEM_UNKNOWN
Definition csync.h:88
@ CSYNC_STATUS_PERMISSION_DENIED
Definition csync.h:107
@ CSYNC_STATUS_NOT_FOUND
Definition csync.h:108
@ CSYNC_STATUS_UPDATE_ERROR
Definition csync.h:92
@ CSYNC_STATUS_REMOTE_CREATE_ERROR
Definition csync.h:96
@ CSYNC_STATUS_MERGE_FILETREE_ERROR
Definition csync.h:115
@ CSYNC_STATUS_TREE_ERROR
Definition csync.h:89
@ CSYNC_STATUS_SERVICE_UNAVAILABLE
Definition csync.h:112
@ CSYNC_STATUS_STATEDB_WRITE_ERROR
Definition csync.h:85
@ CSYNC_STATUS_OUT_OF_SPACE
Definition csync.h:110
@ CSYNC_STATUS_FILE_EXISTS
Definition csync.h:109
@ CSYNC_STATUS_PROXY_AUTH_ERROR
Definition csync.h:103
@ CSYNC_STATUS_CONNECT_ERROR
Definition csync.h:104
@ CSYNC_STATUS_REMOTE_ACCESS_ERROR
Definition csync.h:95
@ CSYNC_STATUS_TIMESKEW
Definition csync.h:87
@ CSYNC_STATUS_CSYNC_STATUS_ERROR
Definition csync.h:116
@ CSYNC_STATUS_OK
Definition csync.h:78
@ CSYNC_STATUS_ERROR
Definition csync.h:80
@ CSYNC_STATUS_PROXY_ERROR
Definition csync.h:100
@ CSYNC_STATUS_FILE_SIZE_ERROR
Definition csync.h:113
@ CSYNC_STATUS_OPENDIR_ERROR
Definition csync.h:117
@ CSYNC_STATUS_CONTEXT_LOST
Definition csync.h:114
@ CSYNC_STATUS_MEMORY_ERROR
Definition csync.h:90
@ CSYNC_STATUS_NO_MODULE
Definition csync.h:86
@ CSYNC_STATUS_READDIR_ERROR
Definition csync.h:118
@ CSYNC_STATUS_LOCAL_CREATE_ERROR
Definition csync.h:98
@ CSYNC_STATUS_UNSUCCESSFUL
Definition csync.h:82
@ CSYNC_STATUS_REMOTE_STAT_ERROR
Definition csync.h:97
@ CSYNC_STATUS_STATEDB_LOAD_ERROR
Definition csync.h:84
@ CSYNC_STATUS_PROPAGATE_ERROR
Definition csync.h:94
@ CSYNC_STATUS_HTTP_ERROR
Definition csync.h:106
@ CSYNC_STATUS_SERVER_AUTH_ERROR
Definition csync.h:102
@ CSYNC_STATUS_NO_LOCK
Definition csync.h:83
@ CSYNC_STATUS_TIMEOUT
Definition csync.h:105
@ CSYNC_STATUS_LOOKUP_ERROR
Definition csync.h:101
@ CSYNC_STATUS_LOCAL_STAT_ERROR
Definition csync.h:99
@ CSYNC_STATUS_RECONCILE_ERROR
Definition csync.h:93
@ CSYNC_STATUS_QUOTA_EXCEEDED
Definition csync.h:111
@ CSYNC_STATUS_PARAM_ERROR
Definition csync.h:91
@ CSYNC_STATUS_OPEN_ERROR
Definition csync.h:119
csync public structure
CSync File Traversal structure.
Definition csync.h:163