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: */