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-2012 by Andreas Schneider <asn@cryptomilk.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  70
00054 #define LIBCSYNC_VERSION_MICRO  6
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 ".ocsync"
00067 #define CSYNC_CONF_FILE "ocsync.conf"
00068 #define CSYNC_EXCLUDE_FILE "ocsync_exclude.conf"
00069 #define CSYNC_LOCK_FILE "lock"
00070 
00071 enum csync_error_codes_e {
00072   CSYNC_ERR_NONE          = 0,
00073   CSYNC_ERR_LOG,
00074   CSYNC_ERR_LOCK,
00075   CSYNC_ERR_STATEDB_LOAD,
00076   CSYNC_ERR_MODULE,
00077   CSYNC_ERR_TIMESKEW,
00078   CSYNC_ERR_FILESYSTEM,
00079   CSYNC_ERR_TREE,
00080   CSYNC_ERR_MEM,
00081   CSYNC_ERR_PARAM,
00082   CSYNC_ERR_UPDATE,
00083   CSYNC_ERR_RECONCILE,
00084   CSYNC_ERR_PROPAGATE,
00085   CSYNC_ERR_ACCESS_FAILED,
00086   CSYNC_ERR_REMOTE_CREATE,
00087   CSYNC_ERR_REMOTE_STAT,
00088   CSYNC_ERR_LOCAL_CREATE,
00089   CSYNC_ERR_LOCAL_STAT,
00090   CSYNC_ERR_PROXY,
00091   CSYNC_ERR_LOOKUP,
00092   CSYNC_ERR_AUTH_SERVER,
00093   CSYNC_ERR_AUTH_PROXY,
00094   CSYNC_ERR_CONNECT,
00095   CSYNC_ERR_TIMEOUT,
00096   CSYNC_ERR_HTTP,
00097   CSYNC_ERR_PERM,
00098   CSYNC_ERR_NOT_FOUND,
00099   CSYNC_ERR_EXISTS,
00100   CSYNC_ERR_NOSPC,
00101   CSYNC_ERR_QUOTA,
00102   CSYNC_ERR_SERVICE_UNAVAILABLE,
00103   CSYNC_ERR_FILE_TOO_BIG,
00104 
00105   CSYNC_ERR_UNSPEC
00106 };
00107 typedef enum csync_error_codes_e CSYNC_ERROR_CODE;
00108 
00109 /**
00110   * Instruction enum. In the file traversal structure, it describes
00111   * the csync state of a file.
00112   */
00113 enum csync_instructions_e {
00114   CSYNC_INSTRUCTION_NONE       = 0x00000000,
00115   CSYNC_INSTRUCTION_EVAL       = 0x00000001,
00116   CSYNC_INSTRUCTION_REMOVE     = 0x00000002,
00117   CSYNC_INSTRUCTION_RENAME     = 0x00000004,
00118   CSYNC_INSTRUCTION_NEW        = 0x00000008,
00119   CSYNC_INSTRUCTION_CONFLICT   = 0x00000010,
00120   CSYNC_INSTRUCTION_IGNORE     = 0x00000020,
00121   CSYNC_INSTRUCTION_SYNC       = 0x00000040,
00122   CSYNC_INSTRUCTION_STAT_ERROR = 0x00000080,
00123   CSYNC_INSTRUCTION_ERROR      = 0x00000100,
00124   /* instructions for the propagator */
00125   CSYNC_INSTRUCTION_DELETED    = 0x00000200,
00126   CSYNC_INSTRUCTION_UPDATED    = 0x00000400
00127 };
00128 
00129 enum csync_ftw_type_e {
00130     CSYNC_FTW_TYPE_FILE,
00131     CSYNC_FTW_TYPE_SLINK,
00132     CSYNC_FTW_TYPE_DIR,
00133     CSYNC_FTW_TYPE_SKIP
00134 };
00135 
00136 
00137 /**
00138  * CSync File Traversal structure.
00139  *
00140  * This structure is passed to the visitor function for every file
00141  * which is seen.
00142  * Note: The file size is missing here because type off_t is depending
00143  *       on the large file support in your build. Make sure to check
00144  *       that cmake and the callback app are compiled with the same
00145  *       setting for it, such as:
00146  *       -D_LARGEFILE64_SOURCE or -D_LARGEFILE_SOURCE
00147  *
00148  */
00149 struct csync_tree_walk_file_s {
00150     const char *path;
00151     /* off_t       size; */
00152     time_t      modtime;
00153 #ifdef _WIN32
00154     uint32_t    uid;
00155     uint32_t    gid;
00156 #else
00157     uid_t       uid;
00158     gid_t       gid;
00159 #endif
00160     mode_t      mode;
00161     enum csync_ftw_type_e     type;
00162     enum csync_instructions_e instruction;
00163 
00164     const char *rename_path;
00165 };
00166 typedef struct csync_tree_walk_file_s TREE_WALK_FILE;
00167 
00168 /**
00169  * csync handle
00170  */
00171 typedef struct csync_s CSYNC;
00172 
00173 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
00174     int echo, int verify, void *userdata);
00175 
00176 typedef void (*csync_log_callback) (CSYNC *ctx,
00177                                     int verbosity,
00178                                     const char *function,
00179                                     const char *buffer,
00180                                     void *userdata);
00181 
00182 /**
00183  * @brief Allocate a csync context.
00184  *
00185  * @param csync  The context variable to allocate.
00186  *
00187  * @return  0 on success, less than 0 if an error occured.
00188  */
00189 int csync_create(CSYNC **csync, const char *local, const char *remote);
00190 
00191 /**
00192  * @brief Initialize the file synchronizer.
00193  *
00194  * This function loads the configuration, the statedb and locks the client.
00195  *
00196  * @param ctx  The context to initialize.
00197  *
00198  * @return  0 on success, less than 0 if an error occured.
00199  */
00200 int csync_init(CSYNC *ctx);
00201 
00202 /**
00203  * @brief Update detection
00204  *
00205  * @param ctx  The context to run the update detection on.
00206  *
00207  * @return  0 on success, less than 0 if an error occured.
00208  */
00209 int csync_update(CSYNC *ctx);
00210 
00211 /**
00212  * @brief Reconciliation
00213  *
00214  * @param ctx  The context to run the reconciliation on.
00215  *
00216  * @return  0 on success, less than 0 if an error occured.
00217  */
00218 int csync_reconcile(CSYNC *ctx);
00219 
00220 /**
00221  * @brief Propagation
00222  *
00223  * @param ctx  The context to run the propagation on.
00224  *
00225  * @return  0 on success, less than 0 if an error occured.
00226  */
00227 int csync_propagate(CSYNC *ctx);
00228 
00229 /**
00230  * @brief Destroy the csync context
00231  *
00232  * Writes the statedb, unlocks csync and frees the memory.
00233  *
00234  * @param ctx  The context to destroy.
00235  *
00236  * @return  0 on success, less than 0 if an error occured.
00237  */
00238 int csync_destroy(CSYNC *ctx);
00239 
00240 /**
00241  * @brief Check if csync is the required version or get the version
00242  * string.
00243  *
00244  * @param req_version   The version required.
00245  *
00246  * @return              If the version of csync is newer than the version
00247  *                      required it will return a version string.
00248  *                      NULL if the version is older.
00249  *
00250  * Example:
00251  *
00252  * @code
00253  *  if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) {
00254  *    fprintf(stderr, "libcsync version is too old!\n");
00255  *    exit(1);
00256  *  }
00257  *
00258  *  if (debug) {
00259  *    printf("csync %s\n", csync_version(0));
00260  *  }
00261  * @endcode
00262  */
00263 const char *csync_version(int req_version);
00264 
00265 /**
00266  * @brief Add an additional exclude list.
00267  *
00268  * @param ctx           The context to add the exclude list.
00269  *
00270  * @param path          The path pointing to the file.
00271  *
00272  * @return              0 on success, less than 0 if an error occured.
00273  */
00274 int csync_add_exclude_list(CSYNC *ctx, const char *path);
00275 
00276 /**
00277  * @brief Get the config directory.
00278  *
00279  * @param ctx          The csync context.
00280  *
00281  * @return             The path of the config directory or NULL on error.
00282  */
00283 const char *csync_get_config_dir(CSYNC *ctx);
00284 
00285 /**
00286  * @brief Change the config directory.
00287  *
00288  * @param ctx           The csync context.
00289  *
00290  * @param path          The path to the new config directory.
00291  *
00292  * @return              0 on success, less than 0 if an error occured.
00293  */
00294 int csync_set_config_dir(CSYNC *ctx, const char *path);
00295 
00296 /**
00297  * @brief Remove the complete config directory.
00298  *
00299  * @param ctx           The csync context.
00300  *
00301  * @return              0 on success, less than 0 if an error occured.
00302  */
00303 int csync_remove_config_dir(CSYNC *ctx);
00304 
00305 /**
00306  * @brief Enable the usage of the statedb. It is enabled by default.
00307  *
00308  * @param ctx           The csync context.
00309  *
00310  * @return              0 on success, less than 0 if an error occured.
00311  */
00312 int csync_enable_statedb(CSYNC *ctx);
00313 
00314 /**
00315  * @brief Disable the usage of the statedb. It is enabled by default.
00316  *
00317  * @param ctx           The csync context.
00318  *
00319  * @return              0 on success, less than 0 if an error occured.
00320  */
00321 int csync_disable_statedb(CSYNC *ctx);
00322 
00323 /**
00324  * @brief Check if the statedb usage is enabled.
00325  *
00326  * @param ctx           The csync context.
00327  *
00328  * @return              1 if it is enabled, 0 if it is disabled.
00329  */
00330 int csync_is_statedb_disabled(CSYNC *ctx);
00331 
00332 /**
00333  * @brief Get the userdata saved in the context.
00334  *
00335  * @param ctx           The csync context.
00336  *
00337  * @return              The userdata saved in the context, NULL if an error
00338  *                      occured.
00339  */
00340 void *csync_get_userdata(CSYNC *ctx);
00341 
00342 /**
00343  * @brief Save userdata to the context which is passed to the auth
00344  * callback function.
00345  *
00346  * @param ctx           The csync context.
00347  *
00348  * @param userdata      The userdata to be stored in the context.
00349  *
00350  * @return              0 on success, less than 0 if an error occured.
00351  */
00352 int csync_set_userdata(CSYNC *ctx, void *userdata);
00353 
00354 /**
00355  * @brief Get the authentication callback set.
00356  *
00357  * @param ctx           The csync context.
00358  *
00359  * @return              The authentication callback set or NULL if an error
00360  *                      occured.
00361  */
00362 csync_auth_callback csync_get_auth_callback(CSYNC *ctx);
00363 
00364 /**
00365  * @brief Set the authentication callback.
00366  *
00367  * @param ctx           The csync context.
00368  *
00369  * @param cb            The authentication callback.
00370  *
00371  * @return              0 on success, less than 0 if an error occured.
00372  */
00373 int csync_set_auth_callback(CSYNC *ctx, csync_auth_callback cb);
00374 
00375 /**
00376  * @brief Set the log verbosity.
00377  *
00378  * @param ctx           The csync context.
00379  *
00380  * @param[in]  verbosity  The log verbosity.
00381  *
00382  * @return 0 on success, < 0 if an error occured.
00383  */
00384 int csync_set_log_verbosity(CSYNC *ctx, int verbosity);
00385 
00386 /**
00387  * @brief Get the log verbosity
00388  *
00389  * @param[in]  ctx    The csync context to ask for the log verbosity.
00390  *
00391  * @return            The log verbosity, -1 on error.
00392  */
00393 int csync_get_log_verbosity(CSYNC *ctx);
00394 
00395 /**
00396  * @brief Get the logging callback set.
00397  *
00398  * @param ctx           The csync context.
00399  *
00400  * @return              The logging callback set or NULL if an error
00401  *                      occured.
00402  */
00403 csync_log_callback csync_get_log_callback(CSYNC *ctx);
00404 
00405 /**
00406  * @brief Set the logging callback.
00407  *
00408  * @param ctx           The csync context.
00409  *
00410  * @param cb            The logging callback.
00411  *
00412  * @return              0 on success, less than 0 if an error occured.
00413  */
00414 int csync_set_log_callback(CSYNC *ctx, csync_log_callback cb);
00415 
00416 /**
00417  * @brief Get the path of the statedb file used.
00418  *
00419  * @param ctx           The csync context.
00420  *
00421  * @return              The path to the statedb file, NULL if an error occured.
00422  */
00423 const char *csync_get_statedb_file(CSYNC *ctx);
00424 
00425 /**
00426  * @brief Enable the creation of backup copys if files are changed on both sides
00427  *
00428  * @param ctx           The csync context.
00429  *
00430  * @return              0 on success, less than 0 if an error occured.
00431  */
00432 int csync_enable_conflictcopys(CSYNC *ctx);
00433 
00434 /**
00435   * @brief Flag to tell csync that only a local run is intended. Call before csync_init
00436   *
00437   * @param local_only   Bool flag to indicate local only mode.
00438   *
00439   * @return             0 on success, less than 0 if an error occured.
00440   */
00441 int csync_set_local_only( CSYNC *ctx, bool local_only );
00442 
00443 /**
00444   * @brief Retrieve the flag to tell csync that only a local run is intended.
00445   *
00446   * @return             1: stay local only, 0: local and remote mode
00447   */
00448 bool csync_get_local_only( CSYNC *ctx );
00449 
00450 /* Used for special modes or debugging */
00451 int csync_get_status(CSYNC *ctx);
00452 
00453 /* Used for special modes or debugging */
00454 int csync_set_status(CSYNC *ctx, int status);
00455 
00456 typedef int csync_treewalk_visit_func(TREE_WALK_FILE* ,void*);
00457 
00458 /**
00459  * @brief Walk the local file tree and call a visitor function for each file.
00460  *
00461  * @param ctx           The csync context.
00462  * @param visitor       A callback function to handle the file info.
00463  * @param filter        A filter, built from or'ed csync_instructions_e
00464  *
00465  * @return              0 on success, less than 0 if an error occured.
00466  */
00467 int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
00468 
00469 /**
00470  * @brief Walk the remote file tree and call a visitor function for each file.
00471  *
00472  * @param ctx           The csync context.
00473  * @param visitor       A callback function to handle the file info.
00474  * @param filter        A filter, built from and'ed csync_instructions_e
00475  *
00476  * @return              0 on success, less than 0 if an error occured.
00477  */
00478 int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter);
00479 
00480 /**
00481  * @brief Set iconv source codec for filenames.
00482  *
00483  * @param from          Source codec.
00484  *
00485  * @return              0 on success, or an iconv error number.
00486  */
00487 int csync_set_iconv_codec(const char *from);
00488 
00489 /**
00490  * @brief Get the error code from the last operation.
00491  * 
00492  * @return              An error code defined by structure CSYNC_ERROR_CODE
00493  */
00494 CSYNC_ERROR_CODE csync_get_error(CSYNC *ctx);
00495 
00496 /**
00497  * @brief csync_get_error_string - return a string with error information
00498  * @param ctx
00499  * @return A pointer to an error string or NULL.
00500  */
00501 const char *csync_get_error_string(CSYNC *ctx);
00502 
00503 /**
00504  * @brief Set a property to module
00505  *
00506  * @param ctx           The csync context.
00507  *
00508  * @param key           The property key
00509  *
00510  * @param value         An opaque pointer to the data.
00511  *
00512  * @return              0 on success, less than 0 if an error occured.
00513  */
00514 int csync_set_module_property(CSYNC *ctx, const char *key, void *value);
00515 
00516 enum csync_notify_type_e { CSYNC_NOTIFY_START_DOWNLOAD, CSYNC_NOTIFY_START_UPLOAD,
00517                            CSYNC_NOTIFY_PROGRESS, CSYNC_NOTIFY_FINISHED_DOWNLOAD,
00518                            CSYNC_NOTIFY_FINISHED_UPLOAD, CSYNC_NOTIFY_ERROR };
00519 
00520 typedef void (*csync_progress_callback) (const char *remote_url, enum csync_notify_type_e kind,
00521                                         long long o1, long long o2, void *userdata);
00522 /**
00523  * @brief Set a progress callback
00524  *
00525  * @param ctx           The csync context.
00526  *
00527  * @param cb            The callback
00528  */
00529 int csync_set_progress_callback(CSYNC *ctx, csync_progress_callback cb);
00530 
00531 
00532 
00533 #ifdef __cplusplus
00534 }
00535 #endif
00536 
00537 /**
00538  * }@
00539  */
00540 #endif /* _CSYNC_H */
00541 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */

Generated on Sat May 4 16:58:54 2013 for doc by  doxygen 1.5.6