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  * @defgroup libsmbconf The smbconf API
  25  *
  26  * libsmbconf is a library to read or, based on the backend, modify the Samba
  27  * configuration.
  28  *
  29  * @{
  30  */
  31
  32 /**
  33  * @brief Status codes returned from smbconf functions
  34  */
  35 enum _sbcErrType {
  36         SBC_ERR_OK = 0,          /**< Successful completion **/
  37         SBC_ERR_NOT_IMPLEMENTED, /**< Function not implemented **/
  38         SBC_ERR_NOT_SUPPORTED,   /**< Function not supported **/
  39         SBC_ERR_UNKNOWN_FAILURE, /**< General failure **/
  40         SBC_ERR_NOMEM,           /**< Memory allocation error **/
  41         SBC_ERR_INVALID_PARAM,   /**< An Invalid parameter was supplied **/
  42         SBC_ERR_BADFILE,         /**< A bad file was supplied **/
  43         SBC_ERR_NO_SUCH_SERVICE, /**< There is no such service provided **/
  44         SBC_ERR_IO_FAILURE,      /**< There was an IO error **/
  45         SBC_ERR_CAN_NOT_COMPLETE,/**< Can not complete action **/
  46         SBC_ERR_NO_MORE_ITEMS,   /**< No more items left **/
  47         SBC_ERR_FILE_EXISTS,     /**< File already exists **/
  48         SBC_ERR_ACCESS_DENIED,   /**< Access has been denied **/
  49 };
  50
  51 typedef enum _sbcErrType sbcErr;
  52
  53 #define SBC_ERROR_IS_OK(x) ((x) == SBC_ERR_OK)
  54 #define SBC_ERROR_EQUAL(x,y) ((x) == (y))
  55
  56 struct smbconf_ctx;
  57
  58 /* the change sequence number */
  59 struct smbconf_csn {
  60         uint64_t csn;
  61 };
  62
  63 /** Information about a service */
  64 struct smbconf_service {
  65         char *name;          /**< The name of the share */
  66         uint32_t num_params; /**< List of length num_shares of parameter counts for each share */
  67         char **param_names;  /**< List of lists of parameter names for each share */
  68         char **param_values; /**< List of lists of parameter values for each share */
  69 };
  70
  71 /*
  72  * The smbconf API functions
  73  */
  74
  75 /**
  76  * @brief Translate an error value into a string
  77  *
  78  * @param error
  79  *
  80  * @return a pointer to a static string
  81  **/
  82 const char *sbcErrorString(sbcErr error);
  83
  84 /**
  85  * @brief Check if the backend requires messaging to be set up.
  86  *
  87  * Tell whether the backend requires messaging to be set up
  88  * for the backend to work correctly.
  89  *
  90  * @param[in] ctx       The smbconf context to check.
  91  *
  92  * @return              True if needed, false if not.
  93  */
  94 bool smbconf_backend_requires_messaging(struct smbconf_ctx *ctx);
  95
  96 /**
  97  * @brief Tell whether the source is writeable.
  98  *
  99  * @param[in] ctx       The smbconf context to check.
 100  *
 101  * @return              True if it is writeable, false if not.
 102  */
 103 bool smbconf_is_writeable(struct smbconf_ctx *ctx);
 104
 105 /**
 106  * @brief Close the configuration.
 107  *
 108  * @param[in] ctx       The smbconf context to close.
 109  */
 110 void smbconf_shutdown(struct smbconf_ctx *ctx);
 111
 112 /**
 113  * @brief Detect changes in the configuration.
 114  *
 115  * Get the change sequence number of the given service/parameter. Service and
 116  * parameter strings may be NULL.
 117  *
 118  * The given change sequence number (csn) struct is filled with the current
 119  * csn. smbconf_changed() can also be used for initial retrieval of the csn.
 120  *
 121  * @param[in] ctx       The smbconf context to check for changes.
 122  *
 123  * @param[inout] csn    The smbconf csn to be filled.
 124  *
 125  * @param[in] service   The service name to check or NULL.
 126  *
 127  * @param[in] param     The param to check or NULL.
 128  *
 129  * @return              True if it has been changed, false if not.
 130  */
 131 bool smbconf_changed(struct smbconf_ctx *ctx, struct smbconf_csn *csn,
 132                      const char *service, const char *param);
 133
 134 /**
 135  * @brief Drop the whole configuration (restarting empty).
 136  *
 137  * @param[in] ctx       The smbconf context to drop the config.
 138  *
 139  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 140  *                      error occurred.
 141  */
 142 sbcErr smbconf_drop(struct smbconf_ctx *ctx);
 143
 144 /**
 145  * @brief Get the whole configuration as lists of strings with counts.
 146  *
 147  * @param[in] ctx       The smbconf context to get the lists from.
 148  *
 149  * @param[in] mem_ctx   The memory context to use.
 150  *
 151  * @param[in] num_shares A pointer to store the number of shares.
 152  *
 153  * @param[out] services  A pointer to store the services.
 154  *
 155  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 156  *                      error occurred.
 157  *
 158  * @see smbconf_service
 159  */
 160 sbcErr smbconf_get_config(struct smbconf_ctx *ctx,
 161                           TALLOC_CTX *mem_ctx,
 162                           uint32_t *num_shares,
 163                           struct smbconf_service ***services);
 164
 165 /**
 166  * @brief Get the list of share names defined in the configuration.
 167  *
 168  * @param[in] ctx       The smbconf context to use.
 169  *
 170  * @param[in] mem_ctx   The memory context to use.
 171  *
 172  * @param[in] num_shares A pointer to store the number of shares.
 173  *
 174  * @param[in] share_names A pointer to store the share names.
 175  *
 176  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 177  *                      error occurred.
 178  */
 179 sbcErr smbconf_get_share_names(struct smbconf_ctx *ctx,
 180                                TALLOC_CTX *mem_ctx,
 181                                uint32_t *num_shares,
 182                                char ***share_names);
 183
 184 /**
 185  * @brief Check if a share/service of a given name exists.
 186  *
 187  * @param[in] ctx       The smbconf context to use.
 188  *
 189  * @param[in] servicename The service name to check if it exists.
 190  *
 191  * @return              True if it exists, false if not.
 192  */
 193 bool smbconf_share_exists(struct smbconf_ctx *ctx, const char *servicename);
 194
 195 /**
 196  * @brief Add a service if it does not already exist.
 197  *
 198  * @param[in] ctx       The smbconf context to use.
 199  *
 200  * @param[in] servicename The name of the service to add.
 201  *
 202  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 203  *                      error occurred.
 204  */
 205 sbcErr smbconf_create_share(struct smbconf_ctx *ctx, const char *servicename);
 206
 207 /**
 208  * @brief create and set the definition for a new service.
 209  *
 210  * @param[in] ctx       The smbconf context to use.
 211  *
 212  * @param[in] service   The definition for the added service.
 213  *
 214  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 215  *                      error occurred.
 216  */
 217 sbcErr smbconf_create_set_share(struct smbconf_ctx *ctx,
 218                                 struct smbconf_service *service);
 219
 220 /**
 221  * @brief Get a definition of a share (service) from configuration.
 222  *
 223  * @param[in] ctx       The smbconf context to use.
 224  *
 225  * @param[in] mem_ctx   A memory context to allocate the result.
 226  *
 227  * @param[in] servicename The service name to get the information from.
 228  *
 229  * @param[out] service  A pointer to store the service information about the
 230  *                      share.
 231  *
 232  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 233  *                      error occurred.
 234  *
 235  * @see smbconf_service
 236  */
 237 sbcErr smbconf_get_share(struct smbconf_ctx *ctx,
 238                          TALLOC_CTX *mem_ctx,
 239                          const char *servicename,
 240                          struct smbconf_service **service);
 241
 242 /**
 243  * @brief Delete a service from configuration.
 244  *
 245  * @param[in] ctx       The smbconf context to use.
 246  *
 247  * @param[in] servicename The service name to delete.
 248  *
 249  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 250  *                      error occurred.
 251  */
 252 sbcErr smbconf_delete_share(struct smbconf_ctx *ctx,
 253                             const char *servicename);
 254
 255 /**
 256  * @brief Set a configuration parameter to the value provided.
 257  *
 258  * @param[in] ctx       The smbconf context to use.
 259  *
 260  * @param[in] service   The service name to set the parameter.
 261  *
 262  * @param[in] param     The name of the parameter to set.
 263  *
 264  * @param[in] valstr    The value to set.
 265  *
 266  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 267  *                      error occurred.
 268  */
 269 sbcErr smbconf_set_parameter(struct smbconf_ctx *ctx,
 270                              const char *service,
 271                              const char *param,
 272                              const char *valstr);
 273
 274 /**
 275  * @brief Set a global configuration parameter to the value provided.
 276  *
 277  * This adds a paramet in the [global] service. It also creates [global] if it
 278  * doesn't exist.
 279  *
 280  * @param[in] ctx       The smbconf context to use.
 281  *
 282  * @param[in] param     The name of the parameter to set.
 283  *
 284  * @param[in] val       The value to set.
 285  *
 286  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 287  *                      error occurred.
 288  */
 289 sbcErr smbconf_set_global_parameter(struct smbconf_ctx *ctx,
 290                                     const char *param, const char *val);
 291
 292 /**
 293  * @brief Get the value of a configuration parameter as a string.
 294  *
 295  * @param[in]  ctx      The smbconf context to use.
 296  *
 297  * @param[in]  mem_ctx  The memory context to allocate the string on.
 298  *
 299  * @param[in]  service  The name of the service where to find the parameter.
 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 occurred.
 307  */
 308 sbcErr smbconf_get_parameter(struct smbconf_ctx *ctx,
 309                              TALLOC_CTX *mem_ctx,
 310                              const char *service,
 311                              const char *param,
 312                              char **valstr);
 313
 314 /**
 315  * @brief Get the value of a global configuration parameter as a string.
 316  *
 317  * It also creates [global] if it doesn't exist.
 318  *
 319  * @param[in]  ctx      The smbconf context to use.
 320  *
 321  * @param[in]  mem_ctx  The memory context to allocate the string on.
 322  *
 323  * @param[in]  param    The parameter to get.
 324  *
 325  * @param[out] valstr   A pointer to store the value as a string.
 326  *
 327  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 328  *                      error occurred.
 329  */
 330 sbcErr smbconf_get_global_parameter(struct smbconf_ctx *ctx,
 331                                     TALLOC_CTX *mem_ctx,
 332                                     const char *param,
 333                                     char **valstr);
 334
 335 /**
 336  * @brief Delete a parameter from the configuration.
 337  *
 338  * @param[in]  ctx      The smbconf context to use.
 339  *
 340  * @param[in] service   The service where the parameter can be found.
 341  *
 342  * @param[in] param     The name of the parameter to delete.
 343  *
 344  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 345  *                      error occurred.
 346  */
 347 sbcErr smbconf_delete_parameter(struct smbconf_ctx *ctx,
 348                                 const char *service, const char *param);
 349
 350 /**
 351  * @brief Delete a global parameter from the configuration.
 352  *
 353  * It also creates [global] if it doesn't exist.
 354  *
 355  * @param[in]  ctx      The smbconf context to use.
 356  *
 357  * @param[in] param     The name of the parameter to delete.
 358  *
 359  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 360  *                      error occurred.
 361  */
 362 sbcErr smbconf_delete_global_parameter(struct smbconf_ctx *ctx,
 363                                        const char *param);
 364
 365 /**
 366  * @brief Get the list of names of included files.
 367  *
 368  * @param[in]  ctx      The smbconf context to use.
 369  *
 370  * @param[in]  mem_ctx  The memory context to allocate the names.
 371  *
 372  * @param[in]  service  The service name to get the include files.
 373  *
 374  * @param[out] num_includes A pointer to store the number of included files.
 375  *
 376  * @param[out] includes A pointer to store the paths of the included files.
 377  *
 378  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 379  *                      error occurred.
 380  */
 381 sbcErr smbconf_get_includes(struct smbconf_ctx *ctx,
 382                             TALLOC_CTX *mem_ctx,
 383                             const char *service,
 384                             uint32_t *num_includes, char ***includes);
 385
 386 /**
 387  * @brief Get the list of globally included files.
 388  *
 389  * @param[in]  ctx      The smbconf context to use.
 390  *
 391  * @param[in]  mem_ctx  The memory context to allocate the names.
 392  *
 393  * @param[out] num_includes A pointer to store the number of included files.
 394  *
 395  * @param[out] includes A pointer to store the paths of the included files.
 396  *
 397  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 398  *                      error occurred.
 399  */
 400 sbcErr smbconf_get_global_includes(struct smbconf_ctx *ctx,
 401                                    TALLOC_CTX *mem_ctx,
 402                                    uint32_t *num_includes, char ***includes);
 403
 404 /**
 405  * @brief Set a list of config files to include on the given service.
 406  *
 407  * @param[in]  ctx      The smbconf context to use.
 408  *
 409  * @param[in]  service  The service to add includes.
 410  *
 411  * @param[in]  num_includes The number of includes to set.
 412  *
 413  * @param[in]  includes A list of paths to include.
 414  *
 415  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 416  *                      error occurred.
 417  */
 418 sbcErr smbconf_set_includes(struct smbconf_ctx *ctx,
 419                             const char *service,
 420                             uint32_t num_includes, const char **includes);
 421
 422 /**
 423  * @brief Set a list of config files to include globally.
 424  *
 425  * @param[in]  ctx      The smbconf context to use.
 426  *
 427  * @param[in]  num_includes The number of includes to set.
 428  *
 429  * @param[in]  includes A list of paths to include.
 430  *
 431  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 432  *                      error occurred.
 433  */
 434 sbcErr smbconf_set_global_includes(struct smbconf_ctx *ctx,
 435                                    uint32_t num_includes,
 436                                    const char **includes);
 437
 438 /**
 439  * @brief Delete include parameter on the given service.
 440  *
 441  * @param[in]  ctx      The smbconf context to use.
 442  *
 443  * @param[in]  service  The name of the service to delete the includes from.
 444  *
 445  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 446  *                      error occurred.
 447  */
 448 sbcErr smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service);
 449
 450 /**
 451  * @brief Delete include parameter from the global service.
 452  *
 453  * @param[in]  ctx      The smbconf context to use.
 454  *
 455  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 456  *                      error occurred.
 457  */
 458 sbcErr smbconf_delete_global_includes(struct smbconf_ctx *ctx);
 459
 460 /**
 461  * @brief Start a transaction on the configuration backend.
 462  *
 463  * Transactions are exposed in order to make it possible
 464  * to create atomic compound writing commands.
 465  *
 466  * @param[in] ctx       The smbconf context to start the transaction.
 467  *
 468  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 469  *                      error occurred.
 470  */
 471 sbcErr smbconf_transaction_start(struct smbconf_ctx *ctx);
 472
 473 /**
 474  * @brief Commit a transaction on the configuration backend.
 475  *
 476  * Transactions are exposed in order to make it possible
 477  * to create atomic compound writing commands.
 478  *
 479  * @param[in] ctx       The smbconf context to commit the transaction.
 480  *
 481  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 482  *                      error occurred.
 483  *
 484  * @see smbconf_transaction_start()
 485  */
 486 sbcErr smbconf_transaction_commit(struct smbconf_ctx *ctx);
 487
 488 /**
 489  * @brief Cancel a transaction on the configuration backend.
 490  *
 491  * Transactions are exposed in order to make it possible
 492  * to create atomic compound writing commands.
 493  *
 494  * @param[in] ctx       The smbconf context to cancel the transaction.
 495  *
 496  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
 497  *                      error occurred.
 498  *
 499  * @see smbconf_transaction_start()
 500  */
 501 sbcErr smbconf_transaction_cancel(struct smbconf_ctx *ctx);
 502
 503 /* @} ******************************************************************/
 504
 505 #endif /*  _LIBSMBCONF_H_  */