libsmbconf: Document smbconf_set_global_parameter().
[samba.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 sbcErr smbconf_get_parameter(struct smbconf_ctx *ctx,
271                              TALLOC_CTX *mem_ctx,
272                              const char *service,
273                              const char *param,
274                              char **valstr);
275 sbcErr smbconf_get_global_parameter(struct smbconf_ctx *ctx,
276                                     TALLOC_CTX *mem_ctx,
277                                     const char *param,
278                                     char **valstr);
279 sbcErr smbconf_delete_parameter(struct smbconf_ctx *ctx,
280                                 const char *service, const char *param);
281 sbcErr smbconf_delete_global_parameter(struct smbconf_ctx *ctx,
282                                        const char *param);
283 sbcErr smbconf_get_includes(struct smbconf_ctx *ctx,
284                             TALLOC_CTX *mem_ctx,
285                             const char *service,
286                             uint32_t *num_includes, char ***includes);
287 sbcErr smbconf_get_global_includes(struct smbconf_ctx *ctx,
288                                    TALLOC_CTX *mem_ctx,
289                                    uint32_t *num_includes, char ***includes);
290 sbcErr smbconf_set_includes(struct smbconf_ctx *ctx,
291                             const char *service,
292                             uint32_t num_includes, const char **includes);
293 sbcErr smbconf_set_global_includes(struct smbconf_ctx *ctx,
294                                    uint32_t num_includes,
295                                    const char **includes);
296 sbcErr smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service);
297 sbcErr smbconf_delete_global_includes(struct smbconf_ctx *ctx);
298
299 sbcErr smbconf_transaction_start(struct smbconf_ctx *ctx);
300 sbcErr smbconf_transaction_commit(struct smbconf_ctx *ctx);
301 sbcErr smbconf_transaction_cancel(struct smbconf_ctx *ctx);
302
303 #endif /*  _LIBSMBCONF_H_  */