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-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 #ifdef __cplusplus
00035 extern "C" {
00036 #endif
00037 
00038 #define CSYNC_STRINGIFY(s) CSYNC_TOSTRING(s)
00039 #define CSYNC_TOSTRING(s) #s
00040 
00041 /* csync version macros */
00042 #define CSYNC_VERSION_INT(a, b, c) ((a) << 16 | (b) << 8 | (c))
00043 #define CSYNC_VERSION_DOT(a, b, c) a ##.## b ##.## c
00044 #define CSYNC_VERSION(a, b, c) CSYNC_VERSION_DOT(a, b, c)
00045 
00046 /* csync version */
00047 #define LIBCSYNC_VERSION_MAJOR  0
00048 #define LIBCSYNC_VERSION_MINOR  44
00049 #define LIBCSYNC_VERSION_MICRO  0
00050 
00051 #define LIBCSYNC_VERSION_INT CSYNC_VERSION_INT(LIBCSYNC_VERSION_MAJOR, \
00052                                            LIBCSYNC_VERSION_MINOR, \
00053                                            LIBCSYNC_VERSION_MICRO)
00054 #define LIBCSYNC_VERSION     CSYNC_VERSION(LIBCSYNC_VERSION_MAJOR, \
00055                                            LIBCSYNC_VERSION_MINOR, \
00056                                            LIBCSYNC_VERSION_MICRO)
00057 
00058 /*
00059  * csync file declarations
00060  */
00061 #define CSYNC_CONF_DIR ".csync"
00062 #define CSYNC_CONF_FILE "csync.conf"
00063 #define CSYNC_LOG_FILE "csync_log.conf"
00064 #define CSYNC_EXCLUDE_FILE "csync_exclude.conf"
00065 #define CSYNC_LOCK_FILE "lock"
00066 
00067 typedef int (*csync_auth_callback) (const char *prompt, char *buf, size_t len,
00068     int echo, int verify, void *userdata);
00069 
00070 /**
00071  * csync handle
00072  */
00073 typedef struct csync_s CSYNC;
00074 
00075 /**
00076  * @brief Allocate a csync context.
00077  *
00078  * @param csync  The context variable to allocate.
00079  *
00080  * @return  0 on success, less than 0 if an error occured.
00081  */
00082 int csync_create(CSYNC **csync, const char *local, const char *remote);
00083 
00084 /**
00085  * @brief Initialize the file synchronizer.
00086  *
00087  * This function loads the configuration, the statedb and locks the client.
00088  *
00089  * @param ctx  The context to initialize.
00090  *
00091  * @return  0 on success, less than 0 if an error occured.
00092  */
00093 int csync_init(CSYNC *ctx);
00094 
00095 /**
00096  * @brief Update detection
00097  *
00098  * @param ctx  The context to run the update detection on.
00099  *
00100  * @return  0 on success, less than 0 if an error occured.
00101  */
00102 int csync_update(CSYNC *ctx);
00103 
00104 /**
00105  * @brief Reconciliation
00106  *
00107  * @param ctx  The context to run the reconciliation on.
00108  *
00109  * @return  0 on success, less than 0 if an error occured.
00110  */
00111 int csync_reconcile(CSYNC *ctx);
00112 
00113 /**
00114  * @brief Propagation
00115  *
00116  * @param ctx  The context to run the propagation on.
00117  *
00118  * @return  0 on success, less than 0 if an error occured.
00119  */
00120 int csync_propagate(CSYNC *ctx);
00121 
00122 /**
00123  * @brief Destroy the csync context
00124  *
00125  * Writes the statedb, unlocks csync and frees the memory.
00126  *
00127  * @param ctx  The context to destroy.
00128  *
00129  * @return  0 on success, less than 0 if an error occured.
00130  */
00131 int csync_destroy(CSYNC *ctx);
00132 
00133 /**
00134  * @brief Check if csync is the required version or get the version
00135  * string.
00136  *
00137  * @param req_version   The version required.
00138  *
00139  * @return              If the version of csync is newer than the version
00140  *                      required it will return a version string.
00141  *                      NULL if the version is older.
00142  *
00143  * Example:
00144  *
00145  * @code
00146  *  if (csync_version(CSYNC_VERSION_INT(0,42,1)) == NULL) {
00147  *    fprintf(stderr, "libcsync version is too old!\n");
00148  *    exit(1);
00149  *  }
00150  *
00151  *  if (debug) {
00152  *    printf("csync %s\n", csync_version(0));
00153  *  }
00154  * @endcode
00155  */
00156 const char *csync_version(int req_version);
00157 
00158 /**
00159  * @brief Add an additional exclude list.
00160  *
00161  * @param ctx           The context to add the exclude list.
00162  *
00163  * @param path          The path pointing to the file.
00164  *
00165  * @return              0 on success, less than 0 if an error occured.
00166  */
00167 int csync_add_exclude_list(CSYNC *ctx, const char *path);
00168 
00169 /**
00170  * @brief Get the config directory.
00171  *
00172  * @param ctx          The csync context.
00173  *
00174  * @return             The path of the config directory or NULL on error.
00175  */
00176 const char *csync_get_config_dir(CSYNC *ctx);
00177 
00178 /**
00179  * @brief Change the config directory.
00180  *
00181  * @param ctx           The csync context.
00182  *
00183  * @param path          The path to the new config directory.
00184  *
00185  * @return              0 on success, less than 0 if an error occured.
00186  */
00187 int csync_set_config_dir(CSYNC *ctx, const char *path);
00188 
00189 /**
00190  * @brief Remove the complete config directory.
00191  *
00192  * @param ctx           The csync context.
00193  *
00194  * @return              0 on success, less than 0 if an error occured.
00195  */
00196 int csync_remove_config_dir(CSYNC *ctx);
00197 
00198 /**
00199  * @brief Enable the usage of the statedb. It is enabled by default.
00200  *
00201  * @param ctx           The csync context.
00202  *
00203  * @return              0 on success, less than 0 if an error occured.
00204  */
00205 int csync_enable_statedb(CSYNC *ctx);
00206 
00207 /**
00208  * @brief Disable the usage of the statedb. It is enabled by default.
00209  *
00210  * @param ctx           The csync context.
00211  *
00212  * @return              0 on success, less than 0 if an error occured.
00213  */
00214 int csync_disable_statedb(CSYNC *ctx);
00215 
00216 /**
00217  * @brief Check if the statedb usage is enabled.
00218  *
00219  * @param ctx           The csync context.
00220  *
00221  * @return              1 if it is enabled, 0 if it is disabled.
00222  */
00223 int csync_is_statedb_disabled(CSYNC *ctx);
00224 
00225 /**
00226  * @brief Get the userdata saved in the context.
00227  *
00228  * @param ctx           The csync context.
00229  *
00230  * @return              The userdata saved in the context, NULL if an error
00231  *                      occured.
00232  */
00233 void *csync_get_userdata(CSYNC *ctx);
00234 
00235 /**
00236  * @brief Save userdata to the context which is passed to the auth
00237  * callback function.
00238  *
00239  * @param ctx           The csync context.
00240  *
00241  * @param userdata      The userdata to be stored in the context.
00242  *
00243  * @return              0 on success, less than 0 if an error occured.
00244  */
00245 int csync_set_userdata(CSYNC *ctx, void *userdata);
00246 
00247 /**
00248  * @brief Get the authentication callback set.
00249  *
00250  * @param ctx           The csync context.
00251  *
00252  * @return              The authentication callback set or NULL if an error
00253  *                      occured.
00254  */
00255 csync_auth_callback csync_get_auth_callback(CSYNC *ctx);
00256 
00257 /**
00258  * @brief Set the authentication callback.
00259  *
00260  * @param ctx           The csync context.
00261  *
00262  * @param cb            The authentication callback.
00263  *
00264  * @return              0 on success, less than 0 if an error occured.
00265  */
00266 int csync_set_auth_callback(CSYNC *ctx, csync_auth_callback cb);
00267 
00268 /**
00269  * @brief Get the path of the statedb file used.
00270  *
00271  * @param ctx           The csync context.
00272  *
00273  * @return              The path to the statedb file, NULL if an error occured.
00274  */
00275 const char *csync_get_statedb_file(CSYNC *ctx);
00276 
00277 /* Used for special modes or debugging */
00278 int csync_get_status(CSYNC *ctx);
00279 
00280 /* Used for special modes or debugging */
00281 int csync_set_status(CSYNC *ctx, int status);
00282 
00283 #ifdef __cplusplus
00284 }
00285 #endif
00286 
00287 /**
00288  * }@
00289  */
00290 #endif /* _CSYNC_H */
00291 /* vim: set ft=c.doxygen ts=8 sw=2 et cindent: */
Generated on Mon Jul 5 22:58:35 2010 for doc by  doxygen 1.6.3