diff options
Diffstat (limited to 'lib/smbconf/smbconf.h')
| -rw-r--r-- | lib/smbconf/smbconf.h | 438 |
1 files changed, 412 insertions, 26 deletions
diff --git a/lib/smbconf/smbconf.h b/lib/smbconf/smbconf.h index 517302ac88..7f62b06af4 100644 --- a/lib/smbconf/smbconf.h +++ b/lib/smbconf/smbconf.h @@ -20,6 +20,39 @@ #ifndef __LIBSMBCONF_H__ #define __LIBSMBCONF_H__ +/** + * @defgroup libsmbconf The smbconf API + * + * libsmbconf is a library to read or, based on the backend, modify the Samba + * configuration. + * + * @{ + */ + +/** + * @brief Status codes returned from smbconf functions + */ +enum _sbcErrType { + SBC_ERR_OK = 0, /**< Successful completion **/ + SBC_ERR_NOT_IMPLEMENTED, /**< Function not implemented **/ + SBC_ERR_NOT_SUPPORTED, /**< Function not supported **/ + SBC_ERR_UNKNOWN_FAILURE, /**< General failure **/ + SBC_ERR_NOMEM, /**< Memory allocation error **/ + SBC_ERR_INVALID_PARAM, /**< An Invalid parameter was supplied **/ + SBC_ERR_BADFILE, /**< A bad file was supplied **/ + SBC_ERR_NO_SUCH_SERVICE, /**< There is no such service provided **/ + SBC_ERR_IO_FAILURE, /**< There was an IO error **/ + SBC_ERR_CAN_NOT_COMPLETE,/**< Can not complete action **/ + SBC_ERR_NO_MORE_ITEMS, /**< No more items left **/ + SBC_ERR_FILE_EXISTS, /**< File already exists **/ + SBC_ERR_ACCESS_DENIED, /**< Access has been denied **/ +}; + +typedef enum _sbcErrType sbcErr; + +#define SBC_ERROR_IS_OK(x) ((x) == SBC_ERR_OK) +#define SBC_ERROR_EQUAL(x,y) ((x) == (y)) + struct smbconf_ctx; /* the change sequence number */ @@ -27,75 +60,428 @@ struct smbconf_csn { uint64_t csn; }; +/** Information about a service */ struct smbconf_service { - char *name; - uint32_t num_params; - char **param_names; - char **param_values; + char *name; /**< The name of the share */ + uint32_t num_params; /**< List of length num_shares of parameter counts for each share */ + char **param_names; /**< List of lists of parameter names for each share */ + char **param_values; /**< List of lists of parameter values for each share */ }; /* - * the smbconf API functions + * The smbconf API functions + */ + +/** + * @brief Translate an error value into a string + * + * @param error + * + * @return a pointer to a static string + **/ +const char *sbcErrorString(sbcErr error); + +/** + * @brief Check if the backend requires messaging to be set up. + * + * Tell whether the backend requires messaging to be set up + * for the backend to work correctly. + * + * @param[in] ctx The smbconf context to check. + * + * @return True if needed, false if not. */ bool smbconf_backend_requires_messaging(struct smbconf_ctx *ctx); + +/** + * @brief Tell whether the source is writeable. + * + * @param[in] ctx The smbconf context to check. + * + * @return True if it is writeable, false if not. + */ bool smbconf_is_writeable(struct smbconf_ctx *ctx); + +/** + * @brief Close the configuration. + * + * @param[in] ctx The smbconf context to close. + */ void smbconf_shutdown(struct smbconf_ctx *ctx); + +/** + * @brief Detect changes in the configuration. + * + * Get the change sequence number of the given service/parameter. Service and + * parameter strings may be NULL. + * + * The given change sequence number (csn) struct is filled with the current + * csn. smbconf_changed() can also be used for initial retrieval of the csn. + * + * @param[in] ctx The smbconf context to check for changes. + * + * @param[inout] csn The smbconf csn to be filled. + * + * @param[in] service The service name to check or NULL. + * + * @param[in] param The param to check or NULL. + * + * @return True if it has been changed, false if not. + */ bool smbconf_changed(struct smbconf_ctx *ctx, struct smbconf_csn *csn, const char *service, const char *param); -WERROR smbconf_drop(struct smbconf_ctx *ctx); -WERROR smbconf_get_config(struct smbconf_ctx *ctx, + +/** + * @brief Drop the whole configuration (restarting empty). + * + * @param[in] ctx The smbconf context to drop the config. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_drop(struct smbconf_ctx *ctx); + +/** + * @brief Get the whole configuration as lists of strings with counts. + * + * @param[in] ctx The smbconf context to get the lists from. + * + * @param[in] mem_ctx The memory context to use. + * + * @param[in] num_shares A pointer to store the number of shares. + * + * @param[out] services A pointer to store the services. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + * + * @see smbconf_service + */ +sbcErr smbconf_get_config(struct smbconf_ctx *ctx, TALLOC_CTX *mem_ctx, uint32_t *num_shares, struct smbconf_service ***services); -WERROR smbconf_get_share_names(struct smbconf_ctx *ctx, + +/** + * @brief Get the list of share names defined in the configuration. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] mem_ctx The memory context to use. + * + * @param[in] num_shares A pointer to store the number of shares. + * + * @param[in] share_names A pointer to store the share names. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_get_share_names(struct smbconf_ctx *ctx, TALLOC_CTX *mem_ctx, uint32_t *num_shares, char ***share_names); + +/** + * @brief Check if a share/service of a given name exists. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] servicename The service name to check if it exists. + * + * @return True if it exists, false if not. + */ bool smbconf_share_exists(struct smbconf_ctx *ctx, const char *servicename); -WERROR smbconf_create_share(struct smbconf_ctx *ctx, const char *servicename); -WERROR smbconf_get_share(struct smbconf_ctx *ctx, + +/** + * @brief Add a service if it does not already exist. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] servicename The name of the service to add. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_create_share(struct smbconf_ctx *ctx, const char *servicename); + +/** + * @brief Get a definition of a share (service) from configuration. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] mem_ctx A memory context to allocate the result. + * + * @param[in] servicename The service name to get the information from. + * + * @param[out] service A pointer to store the service information about the + * share. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + * + * @see smbconf_service + */ +sbcErr smbconf_get_share(struct smbconf_ctx *ctx, TALLOC_CTX *mem_ctx, const char *servicename, struct smbconf_service **service); -WERROR smbconf_delete_share(struct smbconf_ctx *ctx, + +/** + * @brief Delete a service from configuration. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] servicename The service name to delete. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_delete_share(struct smbconf_ctx *ctx, const char *servicename); -WERROR smbconf_set_parameter(struct smbconf_ctx *ctx, + +/** + * @brief Set a configuration parameter to the value provided. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] service The service name to set the parameter. + * + * @param[in] param The name of the parameter to set. + * + * @param[in] valstr The value to set. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_set_parameter(struct smbconf_ctx *ctx, const char *service, const char *param, const char *valstr); -WERROR smbconf_set_global_parameter(struct smbconf_ctx *ctx, + +/** + * @brief Set a global configuration parameter to the value provided. + * + * This adds a paramet in the [global] service. It also creates [global] if it + * does't exist. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] param The name of the parameter to set. + * + * @param[in] val The value to set. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_set_global_parameter(struct smbconf_ctx *ctx, const char *param, const char *val); -WERROR smbconf_get_parameter(struct smbconf_ctx *ctx, + +/** + * @brief Get the value of a configuration parameter as a string. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] mem_ctx The memory context to allocate the string on. + * + * @param[in] service The name of the service where to find the parameter. + * + * @param[in] param The parameter to get. + * + * @param[out] valstr A pointer to store the value as a string. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_get_parameter(struct smbconf_ctx *ctx, TALLOC_CTX *mem_ctx, const char *service, const char *param, char **valstr); -WERROR smbconf_get_global_parameter(struct smbconf_ctx *ctx, + +/** + * @brief Get the value of a global configuration parameter as a string. + * + * It also creates [global] if it does't exist. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] mem_ctx The memory context to allocate the string on. + * + * @param[in] param The parameter to get. + * + * @param[out] valstr A pointer to store the value as a string. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_get_global_parameter(struct smbconf_ctx *ctx, TALLOC_CTX *mem_ctx, const char *param, char **valstr); -WERROR smbconf_delete_parameter(struct smbconf_ctx *ctx, + +/** + * @brief Delete a parameter from the configuration. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] service The service where the parameter can be found. + * + * @param[in] param The name of the parameter to delete. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_delete_parameter(struct smbconf_ctx *ctx, const char *service, const char *param); -WERROR smbconf_delete_global_parameter(struct smbconf_ctx *ctx, + +/** + * @brief Delete a global parameter from the configuration. + * + * It also creates [global] if it does't exist. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] param The name of the parameter to delete. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_delete_global_parameter(struct smbconf_ctx *ctx, const char *param); -WERROR smbconf_get_includes(struct smbconf_ctx *ctx, + +/** + * @brief Get the list of names of included files. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] mem_ctx The memory context to allocate the names. + * + * @param[in] service The service name to get the include files. + * + * @param[out] num_includes A pointer to store the number of included files. + * + * @param[out] includes A pointer to store the paths of the included files. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_get_includes(struct smbconf_ctx *ctx, TALLOC_CTX *mem_ctx, const char *service, uint32_t *num_includes, char ***includes); -WERROR smbconf_get_global_includes(struct smbconf_ctx *ctx, + +/** + * @brief Get the list of globally included files. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] mem_ctx The memory context to allocate the names. + * + * @param[out] num_includes A pointer to store the number of included files. + * + * @param[out] includes A pointer to store the paths of the included files. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_get_global_includes(struct smbconf_ctx *ctx, TALLOC_CTX *mem_ctx, uint32_t *num_includes, char ***includes); -WERROR smbconf_set_includes(struct smbconf_ctx *ctx, + +/** + * @brief Set a list of config files to include on the given service. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] service The service to add includes. + * + * @param[in] num_includes The number of includes to set. + * + * @param[in] includes A list of paths to include. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_set_includes(struct smbconf_ctx *ctx, const char *service, uint32_t num_includes, const char **includes); -WERROR smbconf_set_global_includes(struct smbconf_ctx *ctx, + +/** + * @brief Set a list of config files to include globally. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] num_includes The number of includes to set. + * + * @param[in] includes A list of paths to include. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_set_global_includes(struct smbconf_ctx *ctx, uint32_t num_includes, const char **includes); -WERROR smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service); -WERROR smbconf_delete_global_includes(struct smbconf_ctx *ctx); -WERROR smbconf_transaction_start(struct smbconf_ctx *ctx); -WERROR smbconf_transaction_commit(struct smbconf_ctx *ctx); -WERROR smbconf_transaction_cancel(struct smbconf_ctx *ctx); +/** + * @brief Delete include parameter on the given service. + * + * @param[in] ctx The smbconf context to use. + * + * @param[in] service The name of the service to delete the includes from. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_delete_includes(struct smbconf_ctx *ctx, const char *service); + +/** + * @brief Delete include parameter from the global service. + * + * @param[in] ctx The smbconf context to use. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_delete_global_includes(struct smbconf_ctx *ctx); + +/** + * @brief Start a transaction on the configuration backend. + * + * This is to speed up writes to the registry based backend. + * + * @param[in] ctx The smbconf context to start the transaction. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + */ +sbcErr smbconf_transaction_start(struct smbconf_ctx *ctx); + +/** + * @brief Commit a transaction on the configuration backend. + * + * This is to speed up writes to the registry based backend. + * + * @param[in] ctx The smbconf context to commit the transaction. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + * + * @see smbconf_transaction_start() + */ +sbcErr smbconf_transaction_commit(struct smbconf_ctx *ctx); + +/** + * @brief Cancel a transaction on the configuration backend. + * + * @param[in] ctx The smbconf context to cancel the transaction. + * + * @return SBC_ERR_OK on success, a corresponding sbcErr if an + * error occured. + * + * @see smbconf_transaction_start() + */ +sbcErr smbconf_transaction_cancel(struct smbconf_ctx *ctx); + +/* @} ******************************************************************/ #endif /* _LIBSMBCONF_H_ */ |