csync.h

Go to the documentation of this file.
00001 /*
00002  * libcsync -- a library to sync a directory with another
00003  *
00004  * Copyright (c) 2006-2008 by Andreas Schneider <mail@cynapses.org>
00005  *
00006  * This program is free software; you can redistribute it and/or
00007  * modify it under the terms of the GNU General Public License
00008  * as published by the Free Software Foundation; either version 2
00009  * of the License, or (at your option) any later version.
00010  *
00011  * This program is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU General Public License
00017  * along with this program; if not, write to the Free Software Foundation,
00018  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
00019  */
00020 
00021 /**
00022  * @file csync.h
00023  *
00024  * @brief Application developer interface for csync.
00025  *
00026  * @defgroup csyncPublicAPI csync public API
00027  *
00028  * @{
00029  */
00030 
00031 #ifndef _CSYNC_H
00032 #define _CSYNC_H
00033 
00034 #include <stdbool.h>
00035 #include <stdint.h>
00036 #include <unistd.h>
00037 #include <sys/types.h>
00038 
00039 #ifdef __cplusplus
00040 extern "C" {
00041 #endif
00042 
00043 #define CSYNC_STRINGIFY(s) CSYNC_TOSTRING(s)
00044 #define CSYNC_TOSTRING(s) #s
00045 
00046 /* csync version macros */
00047 #define CSYNC_VERSION_INT(a, b, c) ((a) << 16 | (b) << 8 | (c))
00048 #define CSYNC_VERSION_DOT(a, b, c) a ##.## b ##.## c
00049 #define CSYNC_VERSION(a, b, c) CSYNC_VERSION_DOT(a, b, c)
00050 
00051 /* csync version */
00052 #define LIBCSYNC_VERSION_MAJOR  0
00053 #define LIBCSYNC_VERSION_MINOR  50 
00054 #define LIBCSYNC_VERSION_MICRO  8
00055 
00056 #define LIBCSYNC_VERSION_INT CSYNC_VERSION_INT(LIBCSYNC_VERSION_MAJOR, \
00057                                            LIBCSYNC_VERSION_MINOR, \
00058                                            LIBCSYNC_VERSION_MICRO)
00059 #define LIBCSYNC_VERSION     CSYNC_VERSION(LIBCSYNC_VERSION_MAJOR, \
00060                                            LIBCSYNC_VERSION_MINOR, \
00061                                            LIBCSYNC_VERSION_MICRO)
00062 
00063 /*
00064  * csync file declarations
00065  */
00066 #define CSYNC_CONF_DIR ".csync"
00067 #define CSYNC_CONF_FILE "csync.conf"
00068 #define CSYNC_LOG_FILE "csync_log.conf"
00069 #define CSYNC_EXCLUDE_FILE "csync_exclude.conf"
00070 #define CSYNC_LOCK_FILE "lock"
00071 
00072 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
00073     int echo, int verify, void *userdata);
00074 
00075 enum csync_error_codes_e {
00076   CSYNC_ERR_NONE          = 0,
00077   CSYNC_ERR_LOG,
00078   CSYNC_ERR_LOCK,
00079   CSYNC_ERR_STATEDB_LOAD,
00080   CSYNC_ERR_MODULE,
00081   CSYNC_ERR_TIMESKEW,
00082   CSYNC_ERR_FILESYSTEM,
00083   CSYNC_ERR_TREE,
00084   CSYNC_ERR_MEM,
00085   CSYNC_ERR_PARAM,
00086   CSYNC_ERR_RECONCILE,
00087   CSYNC_ERR_PROPAGATE,
00088   CSYNC_ERR_ACCESS_FAILED,
00089   CSYNC_ERR_REMOTE_CREATE,
00090   CSYNC_ERR_REMOTE_STAT,
00091   CSYNC_ERR_LOCAL_CREATE,
00092   CSYNC_ERR_LOCAL_STAT,
00093   CSYNC_ERR_PROXY,
00094   CSYNC_ERR_UNSPEC
00095 };
00096 typedef enum csync_error_codes_e CSYNC_ERROR_CODE;
00097 
00098 /**
00099   * Instruction enum. In the file traversal structure, it describes
00100   * the csync state of a file.
00101   */
00102 enum csync_instructions_e {
00103   CSYNC_INSTRUCTION_NONE       = 0x00000000,
00104   CSYNC_INSTRUCTION_EVAL       = 0x00000001,
00105   CSYNC_INSTRUCTION_REMOVE     = 0x00000002,
00106   CSYNC_INSTRUCTION_RENAME     = 0x00000004,
00107   CSYNC_INSTRUCTION_NEW        = 0x00000008,
00108   CSYNC_INSTRUCTION_CONFLICT   = 0x00000010,
00109   CSYNC_INSTRUCTION_IGNORE     = 0x00000020,
00110   CSYNC_INSTRUCTION_SYNC       = 0x00000040,
00111   CSYNC_INSTRUCTION_STAT_ERROR = 0x00000080,
00112   CSYNC_INSTRUCTION_ERROR      = 0x00000100,
00113   /* instructions for the propagator */
00114   CSYNC_INSTRUCTION_DELETED    = 0x00000200,
00115   CSYNC_INSTRUCTION_UPDATED    = 0x00000400
00116 };
00117 
00118 /**
00119  * CSync File Traversal structure.
00120  *
00121  * This structure is passed to the visitor function for every file
00122  * which is seen.
00123  * Note: The file size is missing here because type off_t is depending
00124  *       on the large file support in your build. Make sure to check
00125  *       that cmake and the callback app are compiled with the same
00126  *       setting for it, such as:
00127  *       -D_LARGEFILE64_SOURCE or -D_LARGEFILE_SOURCE
00128  *
00129  */
00130 struct csync_tree_walk_file_s {
00131     const char *path;
00132     /* off_t       size; */
00133     time_t      modtime;
00134 #ifdef _WIN32
00135     uint32_t    uid;
00136     uint32_t    gid;
00137 #else
00138     uid_t       uid;
00139     gid_t       gid;
00140 #endif
00141     mode_t      mode;
00142     int         type;
00143     enum csync_instructions_e instruction;
00144 };
00145 typedef struct csync_tree_walk_file_s TREE_WALK_FILE;
00146 
00147 /**
00148  * csync handle
00149  */
00150 typedef struct csync_s CSYNC;
00151 
00152 /**
00153  * @brief Allocate a csync context.
00154  *
00155  * @param csync  The context variable to allocate.
00156  *
00157  * @return  0 on success, less than 0 if an error occured.
00158  */
00159 int csync_create(CSYNC **csync, const char *local, const char *remote);
00160 
00161 /**
00162  * @brief Initialize the file synchronizer.
00163  *
00164  * This function loads the configuration, the statedb and locks the client.
00165  *
00166  * @param ctx  The context to initialize.
00167  *
00168  * @return  0 on success, less than 0 if an error occured.
00169  */
00170 int csync_init(CSYNC *ctx);
00171 
00172 /**
00173  * @brief Update detection
00174  *
00175  * @param ctx  The context to run the update detection on.
00176  *
00177  * @return  0 on success, less than 0 if an error occured.
00178  */
00179 int csync_update(CSYNC *ctx);
00180 
00181 /**
00182  * @brief Reconciliation
00183  *
00184  * @param ctx  The context to run the reconciliation on.
00185  *
00186  * @return  0 on success, less than 0 if an error occured.
00187  */
00188 int csync_reconcile(CSYNC *ctx);
00189 
00190 /**
00191  * @brief Propagation
00192  *
00193  * @param ctx  The context to run the propagation on.
00194  *
00195  * @return  0 on success, less than 0 if an error occured.
00196  */
00197 int csync_propagate(CSYNC *ctx);
00198 
00199 /**
00200  * @brief Destroy the csync context
00201  *
00202  * Writes the statedb, unlocks csync and frees the memory.
00203  *
00204  * @param ctx  The context to destroy.
00205  *
00206  * @return  0 on success, less than 0 if an error occured.
00207  */
00208 int csync_destroy(CSYNC *ctx);
00209 
00210 /**
00211  * @brief Check if csync is the required version or get the version
00212  * string.
00213  *
00214  * @param req_version   The version required.
00215  *
00216  * @return              If the version of csync is newer than the version
00217  *                      required it will return a version string.
00218  *                      NULL if the version is older.
00219  *
00220  * Example:
00221  *
00222  * @code
00223  *  if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) {
00224  *    fprintf(stderr, "libcsync version is too old!\n");
00225  *    exit(1);
00226  *  }
00227  *
00228  *  if (debug) {
00229  *    printf("csync %s\n", csync_version(0));
00230  *  }
00231  * @endcode
00232  */
00233 const char *csync_version(int req_version);
00234 
00235 /**
00236  * @brief Add an additional exclude list.
00237  *
00238  * @param ctx           The context to add the exclude list.
00239  *
00240  * @param path          The path pointing to the file.
00241  *
00242  * @return              0 on success, less than 0 if an error occured.
00243  */
00244 int csync_add_exclude_list(CSYNC *ctx, const char *path);
00245 
00246 /**
00247  * @brief Get the config directory.
00248  *
00249  * @param ctx          The csync context.
00250  *
00251  * @return             The path of the config directory or NULL on error.
00252  */
00253 const char *csync_get_config_dir(CSYNC *ctx);
00254 
00255 /**
00256  * @brief Change the config directory.
00257  *
00258  * @param ctx           The csync context.
00259  *
00260  * @param path          The path to the new config directory.
00261  *
00262  * @return              0 on success, less than 0 if an error occured.
00263  */
00264 int csync_set_config_dir(CSYNC *ctx, const char *path);
00265 
00266 /**
00267  * @brief Remove the complete config directory.
00268  *
00269  * @param ctx           The csync context.
00270  *
00271  * @return              0 on success, less than 0 if an error occured.
00272  */
00273 int csync_remove_config_dir(CSYNC *ctx);
00274 
00275 /**
00276  * @brief Enable the usage of the statedb. It is enabled by default.
00277  *
00278  * @param ctx           The csync context.
00279  *
00280  * @return              0 on success, less than 0 if an error occured.
00281  */
00282 int csync_enable_statedb(CSYNC *ctx);
00283 
00284 /**
00285  * @brief Disable the usage of the statedb. It is enabled by default.
00286  *
00287  * @param ctx           The csync context.
00288  *
00289  * @return              0 on success, less than 0 if an error occured.
00290  */
00291 int csync_disable_statedb(CSYNC *ctx);
00292 
00293 /**
00294  * @brief Check if the statedb usage is enabled.
00295  *
00296  * @param ctx           The csync context.
00297  *
00298  * @return              1 if it is enabled, 0 if it is disabled.
00299  */
00300 int csync_is_statedb_disabled(CSYNC *ctx);
00301 
00302 /**
00303  * @brief Get the userdata saved in the context.
00304  *
00305  * @param ctx           The csync context.
00306  *
00307  * @return              The userdata saved in the context, NULL if an error
00308  *                      occured.
00309  */
00310 void *csync_get_userdata(CSYNC *ctx);
00311 
00312 /**
00313  * @brief Save userdata to the context which is passed to the auth
00314  * callback function.
00315  *
00316  * @param ctx           The csync context.
00317  *
00318  * @param userdata      The userdata to be stored in the context.
00319  *
00320  * @return              0 on success, less than 0 if an error occured.
00321  */
00322 int csync_set_userdata(CSYNC *ctx, void *userdata);
00323 
00324 /**
00325  * @brief Get the authentication callback set.
00326  *
00327  * @param ctx           The csync context.
00328  *
00329  * @return              The authentication callback set or NULL if an error
00330  *                      occured.
00331  */
00332 csync_auth_callback csync_get_auth_callback(CSYNC *ctx);
00333 
00334 /**
00335  * @brief Set the authentication callback.
00336  *
00337  * @param ctx           The csync context.
00338  *
00339  * @param cb            The authentication callback.
00340  *
00341  * @return              0 on success, less than 0 if an error occured.
00342  */
00343 int csync_set_auth_callback(CSYNC *ctx, csync_auth_callback cb);
00344 
00345 /**
00346  * @brief Get the path of the statedb file used.
00347  *
00348  * @param ctx           The csync context.
00349  *
00350  * @return              The path to the statedb file, NULL if an error occured.
00351  */
00352 const char *csync_get_statedb_file(CSYNC *ctx);
00353 
00354 /**
00355  * @brief Enable the creation of backup copys if files are changed on both sides
00356  *
00357  * @param ctx           The csync context.
00358  *
00359  * @return              0 on success, less than 0 if an error occured.
00360  */
00361 int csync_enable_conflictcopys(CSYNC *ctx);
00362 
00363 /**
00364   * @brief Flag to tell csync that only a local run is intended. Call before csync_init
00365   *
00366   * @param local_only   Bool flag to indicate local only mode.
00367   *
00368   * @return             0 on success, less than 0 if an error occured.
00369   */
00370 int csync_set_local_only( CSYNC *ctx, bool local_only );
00371 
00372 /**
00373   * @brief Retrieve the flag to tell csync that only a local run is intended.
00374   *
00375   * @return             1: stay local only, 0: local and remote mode
00376   */
00377 bool csync_get_local_only( CSYNC *ctx );
00378 
00379 /* Used for special modes or debugging */
00380 int csync_get_status(CSYNC *ctx);
00381 
00382 /* Used for special modes or debugging */
00383 int csync_set_status(CSYNC *ctx, int status);
00384 
00385 typedef int csync_treewalk_visit_func(TREE_WALK_FILE* ,void*);
00386 
00387 /**
00388  * @brief Walk the local file tree and call a visitor function for each file.
00389  *
00390  * @param ctx           The csync context.
00391  * @param visitor       A callback function to handle the file info.
00392  * @param filter        A filter, built from or'ed csync_instructions_e
00393  *
00394  * @return              0 on success, less than 0 if an error occured.
00395  */
00396 int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
00397 
00398 /**
00399  * @brief Walk the remote file tree and call a visitor function for each file.
00400  *
00401  * @param ctx           The csync context.
00402  * @param visitor       A callback function to handle the file info.
00403  * @param filter        A filter, built from and'ed csync_instructions_e
00404  *
00405  * @return              0 on success, less than 0 if an error occured.
00406  */
00407 int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
00408 
00409 /**
00410  * @brief Get the error code from the last operation.
00411  * 
00412  * @return              An error code defined by structure CSYNC_ERROR_CODE
00413  */
00414 CSYNC_ERROR_CODE csync_get_error(CSYNC *ctx);
00415 
00416 #ifdef LOG_TO_CALLBACK
00417 
00418 typedef void (*csync_log_callback)(const char *msg);
00419 
00420 void csync_set_log_callback( csync_log_callback );
00421 
00422 void csync_log_cb(char *catName, int a_priority,
00423       const char* a_format,...);
00424 #endif
00425 
00426 
00427 #ifdef __cplusplus
00428 }
00429 #endif
00430 
00431 /**
00432  * }@
00433  */
00434 #endif /* _CSYNC_H */
00435 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */

Generated on Mon Aug 18 13:53:09 2014 for doc by  doxygen 1.5.6