00001 /** @file include/dmlite/c/dmlite.h 00002 * @brief C wrapper for DMLite 00003 * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch> 00004 */ 00005 #ifndef DMLITE_DMLITE_H 00006 #define DMLITE_DMLITE_H 00007 00008 #include "dmlite/common/config.h" 00009 #include "dmlite/common/errno.h" 00010 #include "any.h" 00011 00012 #include <stdlib.h> 00013 #include <sys/stat.h> 00014 #include <utime.h> 00015 00016 #ifdef __cplusplus 00017 extern "C" { 00018 #endif 00019 00020 /** @brief Handle for the plugin manager. */ 00021 typedef struct dmlite_manager dmlite_manager; 00022 /** @brief Handle for a initialized context. */ 00023 typedef struct dmlite_context dmlite_context; 00024 00025 /** @brief Security credentials 00026 * @details It is up to the caller to allocate and free this pointers. 00027 * DMLite will keep a copy internaly. 00028 * Non used values MUST be NULL. 00029 */ 00030 typedef struct dmlite_credentials { 00031 const char* mech; 00032 const char* client_name; 00033 const char* remote_address; 00034 const char* session_id; 00035 00036 unsigned nfqans; 00037 const char** fqans; 00038 00039 dmlite_any_dict* extra; 00040 } dmlite_credentials; 00041 00042 /** @brief Used to handle user and group information 00043 */ 00044 typedef struct dmlite_security_ent { 00045 const char* name; 00046 dmlite_any_dict* extra; 00047 } dmlite_security_ent; 00048 00049 /** @brief Security context 00050 */ 00051 typedef struct dmlite_security_context { 00052 dmlite_credentials* credentials; 00053 00054 unsigned ngroups; 00055 dmlite_security_ent user; 00056 dmlite_security_ent* groups; 00057 } dmlite_security_context; 00058 00059 /** 00060 * @brief Gets the API version. 00061 */ 00062 unsigned dmlite_api_version(void); 00063 00064 /** 00065 * @brief Initializes a dmlite_manager. 00066 * @return NULL on failure. 00067 */ 00068 dmlite_manager* dmlite_manager_new(void); 00069 00070 /** 00071 * @brief Destroys the manager. 00072 * @param manager The manager to be destroyed. 00073 */ 00074 int dmlite_manager_free(dmlite_manager* manager); 00075 00076 /** 00077 * @brief Loads a library. 00078 * @param manager The plugin manager. 00079 * @param lib The .so file. Usually, (path)/plugin_name.so. 00080 * @param id The plugin ID. Usually, plugin_name. 00081 * @return 0 on success, error code otherwise. 00082 */ 00083 int dmlite_manager_load_plugin(dmlite_manager *manager, const char* lib, const char* id); 00084 00085 /** 00086 * @brief Sets a configuration parameter. 00087 * @param manager The plugin manager. 00088 * @param key The parameter to set. 00089 * @param value The value. 00090 * @return 0 on success, error code otherwise. 00091 */ 00092 int dmlite_manager_set(dmlite_manager* manager, const char* key, const char* value); 00093 00094 /** 00095 * @brief Loads a configuration file. 00096 * @param manager The plugin manager. 00097 * @param file The configuration file 00098 * @return 0 on success, error code otherwise. 00099 */ 00100 int dmlite_manager_load_configuration(dmlite_manager* manager, const char* file); 00101 00102 /** 00103 * @brief Returns the associated value with the given key. 00104 * @param manager The plugin manager. 00105 * @param key The configuration parameter. 00106 * @param buffer Where to leave the string. 00107 * @param bufsize The buffer size. 00108 */ 00109 int dmlite_manager_get(dmlite_manager* handle, const char* key, char* buffer, size_t bufsize); 00110 00111 /** 00112 * @brief Returns the last error code. 00113 * @param manager The plugin manager used in the failing function. 00114 * @return The last error code, WITHOUT the error type byte. 00115 */ 00116 int dmlite_manager_errno(dmlite_manager* manager); 00117 00118 /** 00119 * @brief Returns the type of the last error. 00120 * @param manager The plugin manager used in the failing function. 00121 * @return The last error type byte. 00122 */ 00123 int dmlite_manager_errtype(dmlite_manager* manager); 00124 00125 /** 00126 * @brief Returns the string that describes the last error. 00127 * @param manager The plugin manager used in the failing function. 00128 * @return A pointer to the error string. Do NOT free it. 00129 */ 00130 const char* dmlite_manager_error(dmlite_manager* manager); 00131 00132 /** 00133 * @brief Returns a usable context from the loaded libraries. 00134 * @param manager The plugin manager. 00135 * @return NULL on failure. The error code can be checked with dmlite_manager_error. 00136 * @note A context is NOT thread safe. 00137 */ 00138 dmlite_context* dmlite_context_new(dmlite_manager* manager); 00139 00140 /** 00141 * @brief Destroys the context. 00142 * @param context The context to free. 00143 * @return 0 on success, error code otherwise. 00144 */ 00145 int dmlite_context_free(dmlite_context* context); 00146 00147 /** 00148 * @brief Returns the error code from the last failure. 00149 * @param context The context that was used in the failed function. 00150 * @return The error code. 00151 */ 00152 int dmlite_errno(dmlite_context* context); 00153 00154 /** 00155 * @brief Returns the type of the last error. 00156 * @param context The context that was used in the failed function. 00157 * @return The error type. 00158 */ 00159 int dmlite_errtype(dmlite_context* context); 00160 00161 /** 00162 * @brief Error string from the last failed function. 00163 * @param context The context that was used in the failed function. 00164 * @return A string with the error description. Do NOT free it. 00165 */ 00166 const char* dmlite_error(dmlite_context* context); 00167 00168 /** 00169 * @brief Sets the user security credentials. 00170 * @param context The DM context. 00171 * @param cred The security credentials. 00172 * @return 0 on success, error code otherwise. 00173 */ 00174 int dmlite_setcredentials(dmlite_context* context, const dmlite_credentials* cred); 00175 00176 /** 00177 * @brief Returns the security context. There is no need to free. 00178 * @param context The DM context. 00179 * @return The security context. 00180 */ 00181 const dmlite_security_context* dmlite_get_security_context(dmlite_context* context); 00182 00183 /** 00184 * @brief Sets a configuration parameter tied to a context. 00185 * @details This can be used to pass advanced parameters to a plugin. 00186 * @param context The DM context. 00187 * @param k The configuration key. 00188 * @param v Value. 00189 * @return 0 on success, error code otherwise. 00190 */ 00191 int dmlite_set(dmlite_context* context, const char* k, const dmlite_any* v); 00192 00193 /** 00194 * @brief Sets a configuration parameter tied to a context (array version). 00195 * @param context The DM context. 00196 * @param k The configuration key. 00197 * @param n The configuration key. 00198 * @param v Array of values. 00199 * @return 0 on success, error code otherwise. 00200 */ 00201 int dmlite_set_array(dmlite_context* context, const char* k, 00202 unsigned n, dmlite_any* const* v); 00203 00204 /** 00205 * @brief Removes a configuration parameter. 00206 * @param context The DM context. 00207 * @param k The configuration key. 00208 * @return 0 on success, error code otherwise. 00209 */ 00210 int dmlite_unset(dmlite_context* context, const char* k); 00211 00212 /** 00213 * @brief Removes all configuration parameters previously set. 00214 * @param context The DM context. 00215 * @return 0 on success, error code otherwise. 00216 */ 00217 int dmlite_unset_all(dmlite_context* context); 00218 00219 #ifdef __cplusplus 00220 } 00221 #endif 00222 00223 #endif /* DMLITE_DMLITE_H */