00001 /* 00002 * libcsync -- a library to sync a directory with another 00003 * 00004 * Copyright (c) 2006-2008 by Andreas Schneider <mail@cynapses.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 50 00054 #define LIBCSYNC_VERSION_MICRO 8 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 ".csync" 00067 #define CSYNC_CONF_FILE "csync.conf" 00068 #define CSYNC_LOG_FILE "csync_log.conf" 00069 #define CSYNC_EXCLUDE_FILE "csync_exclude.conf" 00070 #define CSYNC_LOCK_FILE "lock" 00071 00072 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len, 00073 int echo, int verify, void *userdata); 00074 00075 enum csync_error_codes_e { 00076 CSYNC_ERR_NONE = 0, 00077 CSYNC_ERR_LOG, 00078 CSYNC_ERR_LOCK, 00079 CSYNC_ERR_STATEDB_LOAD, 00080 CSYNC_ERR_MODULE, 00081 CSYNC_ERR_TIMESKEW, 00082 CSYNC_ERR_FILESYSTEM, 00083 CSYNC_ERR_TREE, 00084 CSYNC_ERR_MEM, 00085 CSYNC_ERR_PARAM, 00086 CSYNC_ERR_RECONCILE, 00087 CSYNC_ERR_PROPAGATE, 00088 CSYNC_ERR_ACCESS_FAILED, 00089 CSYNC_ERR_REMOTE_CREATE, 00090 CSYNC_ERR_REMOTE_STAT, 00091 CSYNC_ERR_LOCAL_CREATE, 00092 CSYNC_ERR_LOCAL_STAT, 00093 CSYNC_ERR_PROXY, 00094 CSYNC_ERR_UNSPEC 00095 }; 00096 typedef enum csync_error_codes_e CSYNC_ERROR_CODE; 00097 00098 /** 00099 * Instruction enum. In the file traversal structure, it describes 00100 * the csync state of a file. 00101 */ 00102 enum csync_instructions_e { 00103 CSYNC_INSTRUCTION_NONE = 0x00000000, 00104 CSYNC_INSTRUCTION_EVAL = 0x00000001, 00105 CSYNC_INSTRUCTION_REMOVE = 0x00000002, 00106 CSYNC_INSTRUCTION_RENAME = 0x00000004, 00107 CSYNC_INSTRUCTION_NEW = 0x00000008, 00108 CSYNC_INSTRUCTION_CONFLICT = 0x00000010, 00109 CSYNC_INSTRUCTION_IGNORE = 0x00000020, 00110 CSYNC_INSTRUCTION_SYNC = 0x00000040, 00111 CSYNC_INSTRUCTION_STAT_ERROR = 0x00000080, 00112 CSYNC_INSTRUCTION_ERROR = 0x00000100, 00113 /* instructions for the propagator */ 00114 CSYNC_INSTRUCTION_DELETED = 0x00000200, 00115 CSYNC_INSTRUCTION_UPDATED = 0x00000400 00116 }; 00117 00118 /** 00119 * CSync File Traversal structure. 00120 * 00121 * This structure is passed to the visitor function for every file 00122 * which is seen. 00123 * Note: The file size is missing here because type off_t is depending 00124 * on the large file support in your build. Make sure to check 00125 * that cmake and the callback app are compiled with the same 00126 * setting for it, such as: 00127 * -D_LARGEFILE64_SOURCE or -D_LARGEFILE_SOURCE 00128 * 00129 */ 00130 struct csync_tree_walk_file_s { 00131 const char *path; 00132 /* off_t size; */ 00133 time_t modtime; 00134 #ifdef _WIN32 00135 uint32_t uid; 00136 uint32_t gid; 00137 #else 00138 uid_t uid; 00139 gid_t gid; 00140 #endif 00141 mode_t mode; 00142 int type; 00143 enum csync_instructions_e instruction; 00144 }; 00145 typedef struct csync_tree_walk_file_s TREE_WALK_FILE; 00146 00147 /** 00148 * csync handle 00149 */ 00150 typedef struct csync_s CSYNC; 00151 00152 /** 00153 * @brief Allocate a csync context. 00154 * 00155 * @param csync The context variable to allocate. 00156 * 00157 * @return 0 on success, less than 0 if an error occured. 00158 */ 00159 int csync_create(CSYNC **csync, const char *local, const char *remote); 00160 00161 /** 00162 * @brief Initialize the file synchronizer. 00163 * 00164 * This function loads the configuration, the statedb and locks the client. 00165 * 00166 * @param ctx The context to initialize. 00167 * 00168 * @return 0 on success, less than 0 if an error occured. 00169 */ 00170 int csync_init(CSYNC *ctx); 00171 00172 /** 00173 * @brief Update detection 00174 * 00175 * @param ctx The context to run the update detection on. 00176 * 00177 * @return 0 on success, less than 0 if an error occured. 00178 */ 00179 int csync_update(CSYNC *ctx); 00180 00181 /** 00182 * @brief Reconciliation 00183 * 00184 * @param ctx The context to run the reconciliation on. 00185 * 00186 * @return 0 on success, less than 0 if an error occured. 00187 */ 00188 int csync_reconcile(CSYNC *ctx); 00189 00190 /** 00191 * @brief Propagation 00192 * 00193 * @param ctx The context to run the propagation on. 00194 * 00195 * @return 0 on success, less than 0 if an error occured. 00196 */ 00197 int csync_propagate(CSYNC *ctx); 00198 00199 /** 00200 * @brief Destroy the csync context 00201 * 00202 * Writes the statedb, unlocks csync and frees the memory. 00203 * 00204 * @param ctx The context to destroy. 00205 * 00206 * @return 0 on success, less than 0 if an error occured. 00207 */ 00208 int csync_destroy(CSYNC *ctx); 00209 00210 /** 00211 * @brief Check if csync is the required version or get the version 00212 * string. 00213 * 00214 * @param req_version The version required. 00215 * 00216 * @return If the version of csync is newer than the version 00217 * required it will return a version string. 00218 * NULL if the version is older. 00219 * 00220 * Example: 00221 * 00222 * @code 00223 * if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) { 00224 * fprintf(stderr, "libcsync version is too old!\n"); 00225 * exit(1); 00226 * } 00227 * 00228 * if (debug) { 00229 * printf("csync %s\n", csync_version(0)); 00230 * } 00231 * @endcode 00232 */ 00233 const char *csync_version(int req_version); 00234 00235 /** 00236 * @brief Add an additional exclude list. 00237 * 00238 * @param ctx The context to add the exclude list. 00239 * 00240 * @param path The path pointing to the file. 00241 * 00242 * @return 0 on success, less than 0 if an error occured. 00243 */ 00244 int csync_add_exclude_list(CSYNC *ctx, const char *path); 00245 00246 /** 00247 * @brief Get the config directory. 00248 * 00249 * @param ctx The csync context. 00250 * 00251 * @return The path of the config directory or NULL on error. 00252 */ 00253 const char *csync_get_config_dir(CSYNC *ctx); 00254 00255 /** 00256 * @brief Change the config directory. 00257 * 00258 * @param ctx The csync context. 00259 * 00260 * @param path The path to the new config directory. 00261 * 00262 * @return 0 on success, less than 0 if an error occured. 00263 */ 00264 int csync_set_config_dir(CSYNC *ctx, const char *path); 00265 00266 /** 00267 * @brief Remove the complete config directory. 00268 * 00269 * @param ctx The csync context. 00270 * 00271 * @return 0 on success, less than 0 if an error occured. 00272 */ 00273 int csync_remove_config_dir(CSYNC *ctx); 00274 00275 /** 00276 * @brief Enable the usage of the statedb. It is enabled by default. 00277 * 00278 * @param ctx The csync context. 00279 * 00280 * @return 0 on success, less than 0 if an error occured. 00281 */ 00282 int csync_enable_statedb(CSYNC *ctx); 00283 00284 /** 00285 * @brief Disable the usage of the statedb. It is enabled by default. 00286 * 00287 * @param ctx The csync context. 00288 * 00289 * @return 0 on success, less than 0 if an error occured. 00290 */ 00291 int csync_disable_statedb(CSYNC *ctx); 00292 00293 /** 00294 * @brief Check if the statedb usage is enabled. 00295 * 00296 * @param ctx The csync context. 00297 * 00298 * @return 1 if it is enabled, 0 if it is disabled. 00299 */ 00300 int csync_is_statedb_disabled(CSYNC *ctx); 00301 00302 /** 00303 * @brief Get the userdata saved in the context. 00304 * 00305 * @param ctx The csync context. 00306 * 00307 * @return The userdata saved in the context, NULL if an error 00308 * occured. 00309 */ 00310 void *csync_get_userdata(CSYNC *ctx); 00311 00312 /** 00313 * @brief Save userdata to the context which is passed to the auth 00314 * callback function. 00315 * 00316 * @param ctx The csync context. 00317 * 00318 * @param userdata The userdata to be stored in the context. 00319 * 00320 * @return 0 on success, less than 0 if an error occured. 00321 */ 00322 int csync_set_userdata(CSYNC *ctx, void *userdata); 00323 00324 /** 00325 * @brief Get the authentication callback set. 00326 * 00327 * @param ctx The csync context. 00328 * 00329 * @return The authentication callback set or NULL if an error 00330 * occured. 00331 */ 00332 csync_auth_callback csync_get_auth_callback(CSYNC *ctx); 00333 00334 /** 00335 * @brief Set the authentication callback. 00336 * 00337 * @param ctx The csync context. 00338 * 00339 * @param cb The authentication callback. 00340 * 00341 * @return 0 on success, less than 0 if an error occured. 00342 */ 00343 int csync_set_auth_callback(CSYNC *ctx, csync_auth_callback cb); 00344 00345 /** 00346 * @brief Get the path of the statedb file used. 00347 * 00348 * @param ctx The csync context. 00349 * 00350 * @return The path to the statedb file, NULL if an error occured. 00351 */ 00352 const char *csync_get_statedb_file(CSYNC *ctx); 00353 00354 /** 00355 * @brief Enable the creation of backup copys if files are changed on both sides 00356 * 00357 * @param ctx The csync context. 00358 * 00359 * @return 0 on success, less than 0 if an error occured. 00360 */ 00361 int csync_enable_conflictcopys(CSYNC *ctx); 00362 00363 /** 00364 * @brief Flag to tell csync that only a local run is intended. Call before csync_init 00365 * 00366 * @param local_only Bool flag to indicate local only mode. 00367 * 00368 * @return 0 on success, less than 0 if an error occured. 00369 */ 00370 int csync_set_local_only( CSYNC *ctx, bool local_only ); 00371 00372 /** 00373 * @brief Retrieve the flag to tell csync that only a local run is intended. 00374 * 00375 * @return 1: stay local only, 0: local and remote mode 00376 */ 00377 bool csync_get_local_only( CSYNC *ctx ); 00378 00379 /* Used for special modes or debugging */ 00380 int csync_get_status(CSYNC *ctx); 00381 00382 /* Used for special modes or debugging */ 00383 int csync_set_status(CSYNC *ctx, int status); 00384 00385 typedef int csync_treewalk_visit_func(TREE_WALK_FILE* ,void*); 00386 00387 /** 00388 * @brief Walk the local file tree and call a visitor function for each file. 00389 * 00390 * @param ctx The csync context. 00391 * @param visitor A callback function to handle the file info. 00392 * @param filter A filter, built from or'ed csync_instructions_e 00393 * 00394 * @return 0 on success, less than 0 if an error occured. 00395 */ 00396 int csync_walk_local_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter); 00397 00398 /** 00399 * @brief Walk the remote file tree and call a visitor function for each file. 00400 * 00401 * @param ctx The csync context. 00402 * @param visitor A callback function to handle the file info. 00403 * @param filter A filter, built from and'ed csync_instructions_e 00404 * 00405 * @return 0 on success, less than 0 if an error occured. 00406 */ 00407 int csync_walk_remote_tree(CSYNC *ctx, csync_treewalk_visit_func *visitor, int filter); 00408 00409 /** 00410 * @brief Get the error code from the last operation. 00411 * 00412 * @return An error code defined by structure CSYNC_ERROR_CODE 00413 */ 00414 CSYNC_ERROR_CODE csync_get_error(CSYNC *ctx); 00415 00416 #ifdef LOG_TO_CALLBACK 00417 00418 typedef void (*csync_log_callback)(const char *msg); 00419 00420 void csync_set_log_callback( csync_log_callback ); 00421 00422 void csync_log_cb(char *catName, int a_priority, 00423 const char* a_format,...); 00424 #endif 00425 00426 00427 #ifdef __cplusplus 00428 } 00429 #endif 00430 00431 /** 00432 * }@ 00433 */ 00434 #endif /* _CSYNC_H */ 00435 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */