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-2008 by Andreas Schneider <mail@cynapses.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 50
54 #define LIBCSYNC_VERSION_MICRO 8
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 ".csync"
67 #define CSYNC_CONF_FILE "csync.conf"
68 #define CSYNC_LOG_FILE "csync_log.conf"
69 #define CSYNC_EXCLUDE_FILE "csync_exclude.conf"
70 #define CSYNC_LOCK_FILE "lock"
71 
72 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
73  int echo, int verify, void *userdata);
74 
95 };
97 
98 /**
99  * Instruction enum. In the file traversal structure, it describes
100  * the csync state of a file.
101  */
107  CSYNC_INSTRUCTION_NEW = 0x00000008,
113  /* instructions for the propagator */
116 };
117 
118 /**
119  * CSync File Traversal structure.
120  *
121  * This structure is passed to the visitor function for every file
122  * which is seen.
123  * Note: The file size is missing here because type off_t is depending
124  * on the large file support in your build. Make sure to check
125  * that cmake and the callback app are compiled with the same
126  * setting for it, such as:
127  * -D_LARGEFILE64_SOURCE or -D_LARGEFILE_SOURCE
128  *
129  */
131  const char *path;
132  /* off_t size; */
133  time_t modtime;
134 #ifdef _WIN32
135  uint32_t uid;
136  uint32_t gid;
137 #else
138  uid_t uid;
139  gid_t gid;
140 #endif
141  mode_t mode;
142  int type;
144 };
146 
147 /**
148  * csync handle
149  */
150 typedef struct csync_s CSYNC;
151 
152 /**
153  * @brief Allocate a csync context.
154  *
155  * @param csync The context variable to allocate.
156  *
157  * @return 0 on success, less than 0 if an error occured.
158  */
159 int csync_create(CSYNC **csync, const char *local, const char *remote);
160 
161 /**
162  * @brief Initialize the file synchronizer.
163  *
164  * This function loads the configuration, the statedb and locks the client.
165  *
166  * @param ctx The context to initialize.
167  *
168  * @return 0 on success, less than 0 if an error occured.
169  */
170 int csync_init(CSYNC *ctx);
171 
172 /**
173  * @brief Update detection
174  *
175  * @param ctx The context to run the update detection on.
176  *
177  * @return 0 on success, less than 0 if an error occured.
178  */
179 int csync_update(CSYNC *ctx);
180 
181 /**
182  * @brief Reconciliation
183  *
184  * @param ctx The context to run the reconciliation on.
185  *
186  * @return 0 on success, less than 0 if an error occured.
187  */
188 int csync_reconcile(CSYNC *ctx);
189 
190 /**
191  * @brief Propagation
192  *
193  * @param ctx The context to run the propagation on.
194  *
195  * @return 0 on success, less than 0 if an error occured.
196  */
197 int csync_propagate(CSYNC *ctx);
198 
199 /**
200  * @brief Destroy the csync context
201  *
202  * Writes the statedb, unlocks csync and frees the memory.
203  *
204  * @param ctx The context to destroy.
205  *
206  * @return 0 on success, less than 0 if an error occured.
207  */
208 int csync_destroy(CSYNC *ctx);
209 
210 /**
211  * @brief Check if csync is the required version or get the version
212  * string.
213  *
214  * @param req_version The version required.
215  *
216  * @return If the version of csync is newer than the version
217  * required it will return a version string.
218  * NULL if the version is older.
219  *
220  * Example:
221  *
222  * @code
223  * if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) {
224  * fprintf(stderr, "libcsync version is too old!\n");
225  * exit(1);
226  * }
227  *
228  * if (debug) {
229  * printf("csync %s\n", csync_version(0));
230  * }
231  * @endcode
232  */
233 const char *csync_version(int req_version);
234 
235 /**
236  * @brief Add an additional exclude list.
237  *
238  * @param ctx The context to add the exclude list.
239  *
240  * @param path The path pointing to the file.
241  *
242  * @return 0 on success, less than 0 if an error occured.
243  */
244 int csync_add_exclude_list(CSYNC *ctx, const char *path);
245 
246 /**
247  * @brief Get the config directory.
248  *
249  * @param ctx The csync context.
250  *
251  * @return The path of the config directory or NULL on error.
252  */
253 const char *csync_get_config_dir(CSYNC *ctx);
254 
255 /**
256  * @brief Change the config directory.
257  *
258  * @param ctx The csync context.
259  *
260  * @param path The path to the new config directory.
261  *
262  * @return 0 on success, less than 0 if an error occured.
263  */
264 int csync_set_config_dir(CSYNC *ctx, const char *path);
265 
266 /**
267  * @brief Remove the complete config directory.
268  *
269  * @param ctx The csync context.
270  *
271  * @return 0 on success, less than 0 if an error occured.
272  */
274 
275 /**
276  * @brief Enable the usage of the statedb. It is enabled by default.
277  *
278  * @param ctx The csync context.
279  *
280  * @return 0 on success, less than 0 if an error occured.
281  */
282 int csync_enable_statedb(CSYNC *ctx);
283 
284 /**
285  * @brief Disable the usage of the statedb. It is enabled by default.
286  *
287  * @param ctx The csync context.
288  *
289  * @return 0 on success, less than 0 if an error occured.
290  */
291 int csync_disable_statedb(CSYNC *ctx);
292 
293 /**
294  * @brief Check if the statedb usage is enabled.
295  *
296  * @param ctx The csync context.
297  *
298  * @return 1 if it is enabled, 0 if it is disabled.
299  */
301 
302 /**
303  * @brief Get the userdata saved in the context.
304  *
305  * @param ctx The csync context.
306  *
307  * @return The userdata saved in the context, NULL if an error
308  * occured.
309  */
310 void *csync_get_userdata(CSYNC *ctx);
311 
312 /**
313  * @brief Save userdata to the context which is passed to the auth
314  * callback function.
315  *
316  * @param ctx The csync context.
317  *
318  * @param userdata The userdata to be stored in the context.
319  *
320  * @return 0 on success, less than 0 if an error occured.
321  */
322 int csync_set_userdata(CSYNC *ctx, void *userdata);
323 
324 /**
325  * @brief Get the authentication callback set.
326  *
327  * @param ctx The csync context.
328  *
329  * @return The authentication callback set or NULL if an error
330  * occured.
331  */
333 
334 /**
335  * @brief Set the authentication callback.
336  *
337  * @param ctx The csync context.
338  *
339  * @param cb The authentication callback.
340  *
341  * @return 0 on success, less than 0 if an error occured.
342  */
344 
345 /**
346  * @brief Get the path of the statedb file used.
347  *
348  * @param ctx The csync context.
349  *
350  * @return The path to the statedb file, NULL if an error occured.
351  */
352 const char *csync_get_statedb_file(CSYNC *ctx);
353 
354 /**
355  * @brief Enable the creation of backup copys if files are changed on both sides
356  *
357  * @param ctx The csync context.
358  *
359  * @return 0 on success, less than 0 if an error occured.
360  */
362 
363 /**
364  * @brief Flag to tell csync that only a local run is intended. Call before csync_init
365  *
366  * @param local_only Bool flag to indicate local only mode.
367  *
368  * @return 0 on success, less than 0 if an error occured.
369  */
370 int csync_set_local_only( CSYNC *ctx, bool local_only );
371 
372 /**
373  * @brief Retrieve the flag to tell csync that only a local run is intended.
374  *
375  * @return 1: stay local only, 0: local and remote mode
376  */
377 bool csync_get_local_only( CSYNC *ctx );
378 
379 /* Used for special modes or debugging */
380 int csync_get_status(CSYNC *ctx);
381 
382 /* Used for special modes or debugging */
383 int csync_set_status(CSYNC *ctx, int status);
384 
386 
387 /**
388  * @brief Walk the local file tree and call a visitor function for each file.
389  *
390  * @param ctx The csync context.
391  * @param visitor A callback function to handle the file info.
392  * @param filter A filter, built from or'ed csync_instructions_e
393  *
394  * @return 0 on success, less than 0 if an error occured.
395  */
396 int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
397 
398 /**
399  * @brief Walk the remote file tree and call a visitor function for each file.
400  *
401  * @param ctx The csync context.
402  * @param visitor A callback function to handle the file info.
403  * @param filter A filter, built from and'ed csync_instructions_e
404  *
405  * @return 0 on success, less than 0 if an error occured.
406  */
407 int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
408 
409 /**
410  * @brief Get the error code from the last operation.
411  *
412  * @return An error code defined by structure CSYNC_ERROR_CODE
413  */
414 CSYNC_ERROR_CODE csync_get_error(CSYNC *ctx);
415 
416 #ifdef LOG_TO_CALLBACK
417 
418 typedef void (*csync_log_callback)(const char *msg);
419 
420 void csync_set_log_callback( csync_log_callback );
421 
422 void csync_log_cb(char *catName, int a_priority,
423  const char* a_format,...);
424 #endif
425 
426 
427 #ifdef __cplusplus
428 }
429 #endif
430 
431 /**
432  * }@
433  */
434 #endif /* _CSYNC_H */
435 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */