doc

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