c3cd2b34ed9070f064e267e0d6d5fd50d9a00527
[gd/samba-autobuild/.git] / 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
416 /**
417  * @brief Delete include parameter on the given service.
418  *
419  * @param[in]  ctx      The smbconf context to use.
420  *
421  * @param[in]  service  The name of the service to delete the includes from.
422  *
423  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
424  *                      error occured.
425  */
426 sbcErr smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service);
427
428 /**
429  * @brief Delete include parameter from the global service.
430  *
431  * @param[in]  ctx      The smbconf context to use.
432  *
433  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
434  *                      error occured.
435  */
436 sbcErr smbconf_delete_global_includes(struct smbconf_ctx *ctx);
437
438 /**
439  * @brief Start a transaction on the configuration backend.
440  *
441  * This is to speed up writes to the registry based backend.
442  *
443  * @param[in] ctx       The smbconf context to start the transaction.
444  *
445  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
446  *                      error occured.
447  */
448 sbcErr smbconf_transaction_start(struct smbconf_ctx *ctx);
449
450 sbcErr smbconf_transaction_commit(struct smbconf_ctx *ctx);
451 sbcErr smbconf_transaction_cancel(struct smbconf_ctx *ctx);
452
453 #endif /*  _LIBSMBCONF_H_  */