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