Improve configure.in so it can be used outside the Samba source tree.
[Samba/gebeck_regimport.git] / lib / smbconf / smbconf.h
blob7f62b06af45bd809a2cf7a7cbba48645fa569382
1 /*
2 * Unix SMB/CIFS implementation.
3 * libsmbconf - Samba configuration library
4 * Copyright (C) Michael Adam 2008
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.
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.
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/>.
20 #ifndef __LIBSMBCONF_H__
21 #define __LIBSMBCONF_H__
23 /**
24 * @defgroup libsmbconf The smbconf API
26 * libsmbconf is a library to read or, based on the backend, modify the Samba
27 * configuration.
29 * @{
32 /**
33 * @brief Status codes returned from smbconf functions
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 **/
51 typedef enum _sbcErrType sbcErr;
53 #define SBC_ERROR_IS_OK(x) ((x) == SBC_ERR_OK)
54 #define SBC_ERROR_EQUAL(x,y) ((x) == (y))
56 struct smbconf_ctx;
58 /* the change sequence number */
59 struct smbconf_csn {
60 uint64_t csn;
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 */
72 * The smbconf API functions
75 /**
76 * @brief Translate an error value into a string
78 * @param error
80 * @return a pointer to a static string
81 **/
82 const char *sbcErrorString(sbcErr error);
84 /**
85 * @brief Check if the backend requires messaging to be set up.
87 * Tell whether the backend requires messaging to be set up
88 * for the backend to work correctly.
90 * @param[in] ctx The smbconf context to check.
92 * @return True if needed, false if not.
94 bool smbconf_backend_requires_messaging(struct smbconf_ctx *ctx);
96 /**
97 * @brief Tell whether the source is writeable.
99 * @param[in] ctx The smbconf context to check.
101 * @return True if it is writeable, false if not.
103 bool smbconf_is_writeable(struct smbconf_ctx *ctx);
106 * @brief Close the configuration.
108 * @param[in] ctx The smbconf context to close.
110 void smbconf_shutdown(struct smbconf_ctx *ctx);
113 * @brief Detect changes in the configuration.
115 * Get the change sequence number of the given service/parameter. Service and
116 * parameter strings may be NULL.
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.
121 * @param[in] ctx The smbconf context to check for changes.
123 * @param[inout] csn The smbconf csn to be filled.
125 * @param[in] service The service name to check or NULL.
127 * @param[in] param The param to check or NULL.
129 * @return True if it has been changed, false if not.
131 bool smbconf_changed(struct smbconf_ctx *ctx, struct smbconf_csn *csn,
132 const char *service, const char *param);
135 * @brief Drop the whole configuration (restarting empty).
137 * @param[in] ctx The smbconf context to drop the config.
139 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
140 * error occured.
142 sbcErr smbconf_drop(struct smbconf_ctx *ctx);
145 * @brief Get the whole configuration as lists of strings with counts.
147 * @param[in] ctx The smbconf context to get the lists from.
149 * @param[in] mem_ctx The memory context to use.
151 * @param[in] num_shares A pointer to store the number of shares.
153 * @param[out] services A pointer to store the services.
155 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
156 * error occured.
158 * @see smbconf_service
160 sbcErr smbconf_get_config(struct smbconf_ctx *ctx,
161 TALLOC_CTX *mem_ctx,
162 uint32_t *num_shares,
163 struct smbconf_service ***services);
166 * @brief Get the list of share names defined in the configuration.
168 * @param[in] ctx The smbconf context to use.
170 * @param[in] mem_ctx The memory context to use.
172 * @param[in] num_shares A pointer to store the number of shares.
174 * @param[in] share_names A pointer to store the share names.
176 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
177 * error occured.
179 sbcErr smbconf_get_share_names(struct smbconf_ctx *ctx,
180 TALLOC_CTX *mem_ctx,
181 uint32_t *num_shares,
182 char ***share_names);
185 * @brief Check if a share/service of a given name exists.
187 * @param[in] ctx The smbconf context to use.
189 * @param[in] servicename The service name to check if it exists.
191 * @return True if it exists, false if not.
193 bool smbconf_share_exists(struct smbconf_ctx *ctx, const char *servicename);
196 * @brief Add a service if it does not already exist.
198 * @param[in] ctx The smbconf context to use.
200 * @param[in] servicename The name of the service to add.
202 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
203 * error occured.
205 sbcErr smbconf_create_share(struct smbconf_ctx *ctx, const char *servicename);
208 * @brief Get a definition of a share (service) from configuration.
210 * @param[in] ctx The smbconf context to use.
212 * @param[in] mem_ctx A memory context to allocate the result.
214 * @param[in] servicename The service name to get the information from.
216 * @param[out] service A pointer to store the service information about the
217 * share.
219 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
220 * error occured.
222 * @see smbconf_service
224 sbcErr smbconf_get_share(struct smbconf_ctx *ctx,
225 TALLOC_CTX *mem_ctx,
226 const char *servicename,
227 struct smbconf_service **service);
230 * @brief Delete a service from configuration.
232 * @param[in] ctx The smbconf context to use.
234 * @param[in] servicename The service name to delete.
236 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
237 * error occured.
239 sbcErr smbconf_delete_share(struct smbconf_ctx *ctx,
240 const char *servicename);
243 * @brief Set a configuration parameter to the value provided.
245 * @param[in] ctx The smbconf context to use.
247 * @param[in] service The service name to set the parameter.
249 * @param[in] param The name of the parameter to set.
251 * @param[in] valstr The value to set.
253 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
254 * error occured.
256 sbcErr smbconf_set_parameter(struct smbconf_ctx *ctx,
257 const char *service,
258 const char *param,
259 const char *valstr);
262 * @brief Set a global configuration parameter to the value provided.
264 * This adds a paramet in the [global] service. It also creates [global] if it
265 * does't exist.
267 * @param[in] ctx The smbconf context to use.
269 * @param[in] param The name of the parameter to set.
271 * @param[in] val The value to set.
273 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
274 * error occured.
276 sbcErr smbconf_set_global_parameter(struct smbconf_ctx *ctx,
277 const char *param, const char *val);
280 * @brief Get the value of a configuration parameter as a string.
282 * @param[in] ctx The smbconf context to use.
284 * @param[in] mem_ctx The memory context to allocate the string on.
286 * @param[in] service The name of the service where to find the parameter.
288 * @param[in] param The parameter to get.
290 * @param[out] valstr A pointer to store the value as a string.
292 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
293 * error occured.
295 sbcErr smbconf_get_parameter(struct smbconf_ctx *ctx,
296 TALLOC_CTX *mem_ctx,
297 const char *service,
298 const char *param,
299 char **valstr);
302 * @brief Get the value of a global configuration parameter as a string.
304 * It also creates [global] if it does't exist.
306 * @param[in] ctx The smbconf context to use.
308 * @param[in] mem_ctx The memory context to allocate the string on.
310 * @param[in] param The parameter to get.
312 * @param[out] valstr A pointer to store the value as a string.
314 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
315 * error occured.
317 sbcErr smbconf_get_global_parameter(struct smbconf_ctx *ctx,
318 TALLOC_CTX *mem_ctx,
319 const char *param,
320 char **valstr);
323 * @brief Delete a parameter from the configuration.
325 * @param[in] ctx The smbconf context to use.
327 * @param[in] service The service where the parameter can be found.
329 * @param[in] param The name of the parameter to delete.
331 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
332 * error occured.
334 sbcErr smbconf_delete_parameter(struct smbconf_ctx *ctx,
335 const char *service, const char *param);
338 * @brief Delete a global parameter from the configuration.
340 * It also creates [global] if it does't exist.
342 * @param[in] ctx The smbconf context to use.
344 * @param[in] param The name of the parameter to delete.
346 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
347 * error occured.
349 sbcErr smbconf_delete_global_parameter(struct smbconf_ctx *ctx,
350 const char *param);
353 * @brief Get the list of names of included files.
355 * @param[in] ctx The smbconf context to use.
357 * @param[in] mem_ctx The memory context to allocate the names.
359 * @param[in] service The service name to get the include files.
361 * @param[out] num_includes A pointer to store the number of included files.
363 * @param[out] includes A pointer to store the paths of the included files.
365 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
366 * error occured.
368 sbcErr smbconf_get_includes(struct smbconf_ctx *ctx,
369 TALLOC_CTX *mem_ctx,
370 const char *service,
371 uint32_t *num_includes, char ***includes);
374 * @brief Get the list of globally included files.
376 * @param[in] ctx The smbconf context to use.
378 * @param[in] mem_ctx The memory context to allocate the names.
380 * @param[out] num_includes A pointer to store the number of included files.
382 * @param[out] includes A pointer to store the paths of the included files.
384 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
385 * error occured.
387 sbcErr smbconf_get_global_includes(struct smbconf_ctx *ctx,
388 TALLOC_CTX *mem_ctx,
389 uint32_t *num_includes, char ***includes);
392 * @brief Set a list of config files to include on the given service.
394 * @param[in] ctx The smbconf context to use.
396 * @param[in] service The service to add includes.
398 * @param[in] num_includes The number of includes to set.
400 * @param[in] includes A list of paths to include.
402 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
403 * error occured.
405 sbcErr smbconf_set_includes(struct smbconf_ctx *ctx,
406 const char *service,
407 uint32_t num_includes, const char **includes);
410 * @brief Set a list of config files to include globally.
412 * @param[in] ctx The smbconf context to use.
414 * @param[in] num_includes The number of includes to set.
416 * @param[in] includes A list of paths to include.
418 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
419 * error occured.
421 sbcErr smbconf_set_global_includes(struct smbconf_ctx *ctx,
422 uint32_t num_includes,
423 const char **includes);
426 * @brief Delete include parameter on the given service.
428 * @param[in] ctx The smbconf context to use.
430 * @param[in] service The name of the service to delete the includes from.
432 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
433 * error occured.
435 sbcErr smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service);
438 * @brief Delete include parameter from the global service.
440 * @param[in] ctx The smbconf context to use.
442 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
443 * error occured.
445 sbcErr smbconf_delete_global_includes(struct smbconf_ctx *ctx);
448 * @brief Start a transaction on the configuration backend.
450 * This is to speed up writes to the registry based backend.
452 * @param[in] ctx The smbconf context to start the transaction.
454 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
455 * error occured.
457 sbcErr smbconf_transaction_start(struct smbconf_ctx *ctx);
460 * @brief Commit a transaction on the configuration backend.
462 * This is to speed up writes to the registry based backend.
464 * @param[in] ctx The smbconf context to commit the transaction.
466 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
467 * error occured.
469 * @see smbconf_transaction_start()
471 sbcErr smbconf_transaction_commit(struct smbconf_ctx *ctx);
474 * @brief Cancel a transaction on the configuration backend.
476 * @param[in] ctx The smbconf context to cancel the transaction.
478 * @return SBC_ERR_OK on success, a corresponding sbcErr if an
479 * error occured.
481 * @see smbconf_transaction_start()
483 sbcErr smbconf_transaction_cancel(struct smbconf_ctx *ctx);
485 /* @} ******************************************************************/
487 #endif /* _LIBSMBCONF_H_ */