s3: piddir creation fix part 2.
[ira/wip.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  * @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 occured.
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 occured.
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 occured.
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 occured.
204  */
205 sbcErr smbconf_create_share(struct smbconf_ctx *ctx, const char *servicename);
206
207 /**
208  * @brief Get a definition of a share (service) from configuration.
209  *
210  * @param[in] ctx       The smbconf context to use.
211  *
212  * @param[in] mem_ctx   A memory context to allocate the result.
213  *
214  * @param[in] servicename The service name to get the information from.
215  *
216  * @param[out] service  A pointer to store the service information about the
217  *                      share.
218  *
219  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
220  *                      error occured.
221  *
222  * @see smbconf_service
223  */
224 sbcErr smbconf_get_share(struct smbconf_ctx *ctx,
225                          TALLOC_CTX *mem_ctx,
226                          const char *servicename,
227                          struct smbconf_service **service);
228
229 /**
230  * @brief Delete a service from configuration.
231  *
232  * @param[in] ctx       The smbconf context to use.
233  *
234  * @param[in] servicename The service name to delete.
235  *
236  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
237  *                      error occured.
238  */
239 sbcErr smbconf_delete_share(struct smbconf_ctx *ctx,
240                             const char *servicename);
241
242 /**
243  * @brief Set a configuration parameter to the value provided.
244  *
245  * @param[in] ctx       The smbconf context to use.
246  *
247  * @param[in] service   The service name to set the parameter.
248  *
249  * @param[in] param     The name of the parameter to set.
250  *
251  * @param[in] valstr    The value to set.
252  *
253  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
254  *                      error occured.
255  */
256 sbcErr smbconf_set_parameter(struct smbconf_ctx *ctx,
257                              const char *service,
258                              const char *param,
259                              const char *valstr);
260
261 /**
262  * @brief Set a global configuration parameter to the value provided.
263  *
264  * This adds a paramet in the [global] service. It also creates [global] if it
265  * does't exist.
266  *
267  * @param[in] ctx       The smbconf context to use.
268  *
269  * @param[in] param     The name of the parameter to set.
270  *
271  * @param[in] val       The value to set.
272  *
273  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
274  *                      error occured.
275  */
276 sbcErr smbconf_set_global_parameter(struct smbconf_ctx *ctx,
277                                     const char *param, const char *val);
278
279 /**
280  * @brief Get the value of a configuration parameter as a string.
281  *
282  * @param[in]  ctx      The smbconf context to use.
283  *
284  * @param[in]  mem_ctx  The memory context to allocate the string on.
285  *
286  * @param[in]  service  The name of the service where to find the parameter.
287  *
288  * @param[in]  param    The parameter to get.
289  *
290  * @param[out] valstr   A pointer to store the value as a string.
291  *
292  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
293  *                      error occured.
294  */
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);
300
301 /**
302  * @brief Get the value of a global configuration parameter as a string.
303  *
304  * It also creates [global] if it does't exist.
305  *
306  * @param[in]  ctx      The smbconf context to use.
307  *
308  * @param[in]  mem_ctx  The memory context to allocate the string on.
309  *
310  * @param[in]  param    The parameter to get.
311  *
312  * @param[out] valstr   A pointer to store the value as a string.
313  *
314  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
315  *                      error occured.
316  */
317 sbcErr smbconf_get_global_parameter(struct smbconf_ctx *ctx,
318                                     TALLOC_CTX *mem_ctx,
319                                     const char *param,
320                                     char **valstr);
321
322 /**
323  * @brief Delete a parameter from the configuration.
324  *
325  * @param[in]  ctx      The smbconf context to use.
326  *
327  * @param[in] service   The service where the parameter can be found.
328  *
329  * @param[in] param     The name of the parameter to delete.
330  *
331  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
332  *                      error occured.
333  */
334 sbcErr smbconf_delete_parameter(struct smbconf_ctx *ctx,
335                                 const char *service, const char *param);
336
337 /**
338  * @brief Delete a global parameter from the configuration.
339  *
340  * It also creates [global] if it does't exist.
341  *
342  * @param[in]  ctx      The smbconf context to use.
343  *
344  * @param[in] param     The name of the parameter to delete.
345  *
346  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
347  *                      error occured.
348  */
349 sbcErr smbconf_delete_global_parameter(struct smbconf_ctx *ctx,
350                                        const char *param);
351
352 /**
353  * @brief Get the list of names of included files.
354  *
355  * @param[in]  ctx      The smbconf context to use.
356  *
357  * @param[in]  mem_ctx  The memory context to allocate the names.
358  *
359  * @param[in]  service  The service name to get the include files.
360  *
361  * @param[out] num_includes A pointer to store the number of included files.
362  *
363  * @param[out] includes A pointer to store the paths of the included files.
364  *
365  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
366  *                      error occured.
367  */
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);
372
373 /**
374  * @brief Get the list of globally included files.
375  *
376  * @param[in]  ctx      The smbconf context to use.
377  *
378  * @param[in]  mem_ctx  The memory context to allocate the names.
379  *
380  * @param[out] num_includes A pointer to store the number of included files.
381  *
382  * @param[out] includes A pointer to store the paths of the included files.
383  *
384  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
385  *                      error occured.
386  */
387 sbcErr smbconf_get_global_includes(struct smbconf_ctx *ctx,
388                                    TALLOC_CTX *mem_ctx,
389                                    uint32_t *num_includes, char ***includes);
390
391 /**
392  * @brief Set a list of config files to include on the given service.
393  *
394  * @param[in]  ctx      The smbconf context to use.
395  *
396  * @param[in]  service  The service to add includes.
397  *
398  * @param[in]  num_includes The number of includes to set.
399  *
400  * @param[in]  includes A list of paths to include.
401  *
402  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
403  *                      error occured.
404  */
405 sbcErr smbconf_set_includes(struct smbconf_ctx *ctx,
406                             const char *service,
407                             uint32_t num_includes, const char **includes);
408
409 /**
410  * @brief Set a list of config files to include globally.
411  *
412  * @param[in]  ctx      The smbconf context to use.
413  *
414  * @param[in]  num_includes The number of includes to set.
415  *
416  * @param[in]  includes A list of paths to include.
417  *
418  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
419  *                      error occured.
420  */
421 sbcErr smbconf_set_global_includes(struct smbconf_ctx *ctx,
422                                    uint32_t num_includes,
423                                    const char **includes);
424
425 /**
426  * @brief Delete include parameter on the given service.
427  *
428  * @param[in]  ctx      The smbconf context to use.
429  *
430  * @param[in]  service  The name of the service to delete the includes from.
431  *
432  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
433  *                      error occured.
434  */
435 sbcErr smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service);
436
437 /**
438  * @brief Delete include parameter from the global service.
439  *
440  * @param[in]  ctx      The smbconf context to use.
441  *
442  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
443  *                      error occured.
444  */
445 sbcErr smbconf_delete_global_includes(struct smbconf_ctx *ctx);
446
447 /**
448  * @brief Start a transaction on the configuration backend.
449  *
450  * This is to speed up writes to the registry based backend.
451  *
452  * @param[in] ctx       The smbconf context to start the transaction.
453  *
454  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
455  *                      error occured.
456  */
457 sbcErr smbconf_transaction_start(struct smbconf_ctx *ctx);
458
459 /**
460  * @brief Commit a transaction on the configuration backend.
461  *
462  * This is to speed up writes to the registry based backend.
463  *
464  * @param[in] ctx       The smbconf context to commit the transaction.
465  *
466  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
467  *                      error occured.
468  *
469  * @see smbconf_transaction_start()
470  */
471 sbcErr smbconf_transaction_commit(struct smbconf_ctx *ctx);
472
473 /**
474  * @brief Cancel a transaction on the configuration backend.
475  *
476  * @param[in] ctx       The smbconf context to cancel the transaction.
477  *
478  * @return              SBC_ERR_OK on success, a corresponding sbcErr if an
479  *                      error occured.
480  *
481  * @see smbconf_transaction_start()
482  */
483 sbcErr smbconf_transaction_cancel(struct smbconf_ctx *ctx);
484
485 /* @} ******************************************************************/
486
487 #endif /*  _LIBSMBCONF_H_  */