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