lib/smbconf/smbconf.h

   1 /*
   2  *  Unix SMB/CIFS implementation.
   3  *  libsmbconf - Samba configuration library
   4  *  Copyright (C) Michael Adam 2008
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 3 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef __LIBSMBCONF_H__
  21 #define __LIBSMBCONF_H__
  22
  23 /**
  24  * @brief Status codes returned from smbconf functions
  25  */
  26 enum _sbcErrType {
  27         SBC_ERR_OK = 0,          /**< Successful completion **/
  28         SBC_ERR_NOT_IMPLEMENTED, /**< Function not implemented **/
  29         SBC_ERR_NOT_SUPPORTED,   /**< Function not supported **/
  30         SBC_ERR_UNKNOWN_FAILURE, /**< General failure **/
  31         SBC_ERR_NOMEM,           /**< Memory allocation error **/
  32         SBC_ERR_INVALID_PARAM,   /**< An Invalid parameter was supplied **/
  33         SBC_ERR_BADFILE,         /**< A bad file was supplied **/
  34         SBC_ERR_NO_SUCH_SERVICE, /**< There is no such service provided **/
  35         SBC_ERR_IO_FAILURE,      /**< There was an IO error **/
  36         SBC_ERR_CAN_NOT_COMPLETE,/**< Can not complete action **/
  37         SBC_ERR_NO_MORE_ITEMS,   /**< No more items left **/
  38         SBC_ERR_FILE_EXISTS,     /**< File already exists **/
  39         SBC_ERR_ACCESS_DENIED,   /**< Access has been denied **/
  40 };
  41
  42 typedef enum _sbcErrType sbcErr;
  43
  44 #define SBC_ERROR_IS_OK(x) ((x) == SBC_ERR_OK)
  45 #define SBC_ERROR_EQUAL(x,y) ((x) == (y))
  46
  47 struct smbconf_ctx;
  48
  49 /* the change sequence number */
  50 struct smbconf_csn {
  51         uint64_t csn;
  52 };
  53
  54 /** Information about a service */
  55 struct smbconf_service {
  56         char *name;          /**< The name of the share */
  57         uint32_t num_params; /**< List of length num_shares of parameter counts for each share */
  58         char **param_names;  /**< List of lists of parameter names for each share */
  59         char **param_values; /**< List of lists of parameter values for each share */
  60 };
  61
  62 /*
  63  * The smbconf API functions
  64  */
  65
  66 /**
  67  * @brief Translate an error value into a string
  68  *
  69  * @param error
  70  *
  71  * @return a pointer to a static string
  72  **/
  73 const char *sbcErrorString(sbcErr error);
  74
  75 /**
  76  * @brief Check if the backend requires messaging to be set up.
  77  *
  78  * Tell whether the backend requires messaging to be set up
  79  * for the backend to work correctly.
  80  *
  81  * @param[in] ctx       The smbconf context to check.
  82  *
  83  * @return              True if needed, false if not.
  84  */
  85 bool smbconf_backend_requires_messaging(struct smbconf_ctx *ctx);
  86
  87 /**
  88  * @brief Tell whether the source is writeable.
  89  *
  90  * @param[in] ctx       The smbconf context to check.
  91  *
  92  * @return              True if it is writeable, false if not.
  93  */
  94 bool smbconf_is_writeable(struct smbconf_ctx *ctx);
  95
  96 /**
  97  * @brief Close the configuration.
  98  *
  99  * @param[in] ctx       The smbconf context to close.
 100  */
 101 void smbconf_shutdown(struct smbconf_ctx *ctx);
 102
 103 /**
 104  * @brief Detect changes in the configuration.
 105  *
 106  * Get the change sequence number of the given service/parameter. Service and
 107  * parameter strings may be NULL.
 108  *
 109  * The given change sequence number (csn) struct is filled with the current
 110  * csn. smbconf_changed() can also be used for initial retrieval of the csn.
 111  *
 112  * @param[in] ctx       The smbconf context to check for changes.
 113  *
 114  * @param[inout] csn    The smbconf csn to be filled.
 115  *
 116  * @param[in] service   The service name to check or NULL.
 117  *
 118  * @param[in] param     The param to check or NULL.
 119  *
 120  * @return              True if it has been changed, false if not.
 121  */
 122 bool smbconf_changed(struct smbconf_ctx *ctx, struct smbconf_csn *csn,
 123                      const char *service, const char *param);
 124
 125 /**
 126  * @brief Drop the whole configuration (restarting empty).
 127  *
 128  * @param[in] ctx       The smbconf context to drop the config.
 129  *
 130  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 131  *                      error occured.
 132  */
 133 sbcErr smbconf_drop(struct smbconf_ctx *ctx);
 134
 135 /**
 136  * @brief Get the whole configuration as lists of strings with counts.
 137  *
 138  * @param[in] ctx       The smbconf context to get the lists from.
 139  *
 140  * @param[in] mem_ctx   The memory context to use.
 141  *
 142  * @param[in] num_shares A pointer to store the number of shares.
 143  *
 144  * @param[out] services  A pointer to store the services.
 145  *
 146  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 147  *                      error occured.
 148  *
 149  * @see smbconf_service
 150  */
 151 sbcErr smbconf_get_config(struct smbconf_ctx *ctx,
 152                           TALLOC_CTX *mem_ctx,
 153                           uint32_t *num_shares,
 154                           struct smbconf_service ***services);
 155
 156 /**
 157  * @brief Get the list of share names defined in the configuration.
 158  *
 159  * @param[in] ctx       The smbconf context to use.
 160  *
 161  * @param[in] mem_ctx   The memory context to use.
 162  *
 163  * @param[in] num_shares A pointer to store the number of shares.
 164  *
 165  * @param[in] share_names A pointer to store the share names.
 166  *
 167  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 168  *                      error occured.
 169  */
 170 sbcErr smbconf_get_share_names(struct smbconf_ctx *ctx,
 171                                TALLOC_CTX *mem_ctx,
 172                                uint32_t *num_shares,
 173                                char ***share_names);
 174
 175 /**
 176  * @brief Check if a share/service of a given name exists.
 177  *
 178  * @param[in] ctx       The smbconf context to use.
 179  *
 180  * @param[in] servicename The service name to check if it exists.
 181  *
 182  * @return              True if it exists, false if not.
 183  */
 184 bool smbconf_share_exists(struct smbconf_ctx *ctx, const char *servicename);
 185
 186 /**
 187  * @brief Add a service if it does not already exist.
 188  *
 189  * @param[in] ctx       The smbconf context to use.
 190  *
 191  * @param[in] servicename The name of the service to add.
 192  *
 193  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 194  *                      error occured.
 195  */
 196 sbcErr smbconf_create_share(struct smbconf_ctx *ctx, const char *servicename);
 197
 198 /**
 199  * @brief Get a definition of a share (service) from configuration.
 200  *
 201  * @param[in] ctx       The smbconf context to use.
 202  *
 203  * @param[in] mem_ctx   A memory context to allocate the result.
 204  *
 205  * @param[in] servicename The service name to get the information from.
 206  *
 207  * @param[out] service  A pointer to store the service information about the
 208  *                      share.
 209  *
 210  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 211  *                      error occured.
 212  *
 213  * @see smbconf_service
 214  */
 215 sbcErr smbconf_get_share(struct smbconf_ctx *ctx,
 216                          TALLOC_CTX *mem_ctx,
 217                          const char *servicename,
 218                          struct smbconf_service **service);
 219
 220 /**
 221  * @brief Delete a service from configuration.
 222  *
 223  * @param[in] ctx       The smbconf context to use.
 224  *
 225  * @param[in] servicename The service name to delete.
 226  *
 227  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 228  *                      error occured.
 229  */
 230 sbcErr smbconf_delete_share(struct smbconf_ctx *ctx,
 231                             const char *servicename);
 232
 233 /**
 234  * @brief Set a configuration parameter to the value provided.
 235  *
 236  * @param[in] ctx       The smbconf context to use.
 237  *
 238  * @param[in] service   The service name to set the parameter.
 239  *
 240  * @param[in] param     The name of the parameter to set.
 241  *
 242  * @param[in] valstr    The value to set.
 243  *
 244  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 245  *                      error occured.
 246  */
 247 sbcErr smbconf_set_parameter(struct smbconf_ctx *ctx,
 248                              const char *service,
 249                              const char *param,
 250                              const char *valstr);
 251
 252 /**
 253  * @brief Set a global configuration parameter to the value provided.
 254  *
 255  * This adds a paramet in the [global] service. It also creates [global] if it
 256  * does't exist.
 257  *
 258  * @param[in] ctx       The smbconf context to use.
 259  *
 260  * @param[in] param     The name of the parameter to set.
 261  *
 262  * @param[in] val       The value to set.
 263  *
 264  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 265  *                      error occured.
 266  */
 267 sbcErr smbconf_set_global_parameter(struct smbconf_ctx *ctx,
 268                                     const char *param, const char *val);
 269
 270 /**
 271  * @brief Get the value of a configuration parameter as a string.
 272  *
 273  * @param[in]  ctx      The smbconf context to use.
 274  *
 275  * @param[in]  mem_ctx  The memory context to allocate the string on.
 276  *
 277  * @param[in]  service  The name of the service where to find the parameter.
 278  *
 279  * @param[in]  param    The parameter to get.
 280  *
 281  * @param[out] valstr   A pointer to store the value as a string.
 282  *
 283  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 284  *                      error occured.
 285  */
 286 sbcErr smbconf_get_parameter(struct smbconf_ctx *ctx,
 287                              TALLOC_CTX *mem_ctx,
 288                              const char *service,
 289                              const char *param,
 290                              char **valstr);
 291
 292 /**
 293  * @brief Get the value of a global configuration parameter as a string.
 294  *
 295  * It also creates [global] if it does't exist.
 296  *
 297  * @param[in]  ctx      The smbconf context to use.
 298  *
 299  * @param[in]  mem_ctx  The memory context to allocate the string on.
 300  *
 301  * @param[in]  param    The parameter to get.
 302  *
 303  * @param[out] valstr   A pointer to store the value as a string.
 304  *
 305  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 306  *                      error occured.
 307  */
 308 sbcErr smbconf_get_global_parameter(struct smbconf_ctx *ctx,
 309                                     TALLOC_CTX *mem_ctx,
 310                                     const char *param,
 311                                     char **valstr);
 312
 313 /**
 314  * @brief Delete a parameter from the configuration.
 315  *
 316  * @param[in]  ctx      The smbconf context to use.
 317  *
 318  * @param[in] service   The service where the parameter can be found.
 319  *
 320  * @param[in] param     The name of the parameter to delete.
 321  *
 322  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 323  *                      error occured.
 324  */
 325 sbcErr smbconf_delete_parameter(struct smbconf_ctx *ctx,
 326                                 const char *service, const char *param);
 327
 328 /**
 329  * @brief Delete a global parameter from the configuration.
 330  *
 331  * It also creates [global] if it does't exist.
 332  *
 333  * @param[in]  ctx      The smbconf context to use.
 334  *
 335  * @param[in] param     The name of the parameter to delete.
 336  *
 337  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 338  *                      error occured.
 339  */
 340 sbcErr smbconf_delete_global_parameter(struct smbconf_ctx *ctx,
 341                                        const char *param);
 342
 343 /**
 344  * @brief Get the list of names of included files.
 345  *
 346  * @param[in]  ctx      The smbconf context to use.
 347  *
 348  * @param[in]  mem_ctx  The memory context to allocate the names.
 349  *
 350  * @param[in]  service  The service name to get the include files.
 351  *
 352  * @param[out] num_includes A pointer to store the number of included files.
 353  *
 354  * @param[out] includes A pointer to store the paths of the included files.
 355  *
 356  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 357  *                      error occured.
 358  */
 359 sbcErr smbconf_get_includes(struct smbconf_ctx *ctx,
 360                             TALLOC_CTX *mem_ctx,
 361                             const char *service,
 362                             uint32_t *num_includes, char ***includes);
 363
 364 /**
 365  * @brief Get the list of globally included files.
 366  *
 367  * @param[in]  ctx      The smbconf context to use.
 368  *
 369  * @param[in]  mem_ctx  The memory context to allocate the names.
 370  *
 371  * @param[out] num_includes A pointer to store the number of included files.
 372  *
 373  * @param[out] includes A pointer to store the paths of the included files.
 374  *
 375  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 376  *                      error occured.
 377  */
 378 sbcErr smbconf_get_global_includes(struct smbconf_ctx *ctx,
 379                                    TALLOC_CTX *mem_ctx,
 380                                    uint32_t *num_includes, char ***includes);
 381
 382 /**
 383  * @brief Set a list of config files to include on the given service.
 384  *
 385  * @param[in]  ctx      The smbconf context to use.
 386  *
 387  * @param[in]  service  The service to add includes.
 388  *
 389  * @param[in]  num_includes The number of includes to set.
 390  *
 391  * @param[in]  includes A list of paths to include.
 392  *
 393  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 394  *                      error occured.
 395  */
 396 sbcErr smbconf_set_includes(struct smbconf_ctx *ctx,
 397                             const char *service,
 398                             uint32_t num_includes, const char **includes);
 399
 400 /**
 401  * @brief Set a list of config files to include globally.
 402  *
 403  * @param[in]  ctx      The smbconf context to use.
 404  *
 405  * @param[in]  num_includes The number of includes to set.
 406  *
 407  * @param[in]  includes A list of paths to include.
 408  *
 409  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 410  *                      error occured.
 411  */
 412 sbcErr smbconf_set_global_includes(struct smbconf_ctx *ctx,
 413                                    uint32_t num_includes,
 414                                    const char **includes);
 415 sbcErr smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service);
 416 sbcErr smbconf_delete_global_includes(struct smbconf_ctx *ctx);
 417
 418 sbcErr smbconf_transaction_start(struct smbconf_ctx *ctx);
 419 sbcErr smbconf_transaction_commit(struct smbconf_ctx *ctx);
 420 sbcErr smbconf_transaction_cancel(struct smbconf_ctx *ctx);
 421
 422 #endif /*  _LIBSMBCONF_H_  */