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

Generated on Mon Oct 21 19:24:18 2013 for doc by  doxygen 1.5.6