dmlite  0.6
dmlite.h
Go to the documentation of this file.
1 /** @file include/dmlite/c/dmlite.h
2  * @brief C wrapper for DMLite
3  * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
4  */
5 #ifndef DMLITE_DMLITE_H
6 #define DMLITE_DMLITE_H
7 
8 #include "dmlite/common/config.h"
9 #include "dmlite/common/errno.h"
10 #include "any.h"
11 
12 #include <stdlib.h>
13 #include <sys/stat.h>
14 #include <utime.h>
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 /** @brief Handle for the plugin manager. */
22 /** @brief Handle for a initialized context. */
24 
25 /** @brief Security credentials
26  * @details It is up to the caller to allocate and free this pointers.
27  * DMLite will keep a copy internaly.
28  * Non used values MUST be NULL.
29  */
30 typedef struct dmlite_credentials {
31  const char* mech;
32  const char* client_name;
33  const char* remote_address;
34  const char* session_id;
35 
36  unsigned nfqans;
37  const char** fqans;
38 
41 
42 /** @brief Used to handle user and group information
43  */
44 typedef struct dmlite_security_ent {
45  const char* name;
48 
49 /** @brief Security context
50  */
51 typedef struct dmlite_security_context {
53 
54  unsigned ngroups;
58 
59 /**
60  * @brief Gets the API version.
61  */
62 unsigned dmlite_api_version(void);
63 
64 /**
65  * @brief Initializes a dmlite_manager.
66  * @return NULL on failure.
67  */
69 
70 /**
71  * @brief Destroys the manager.
72  * @param manager The manager to be destroyed.
73  */
75 
76 /**
77  * @brief Loads a library.
78  * @param manager The plugin manager.
79  * @param lib The .so file. Usually, (path)/plugin_name.so.
80  * @param id The plugin ID. Usually, plugin_name.
81  * @return 0 on success, error code otherwise.
82  */
83 int dmlite_manager_load_plugin(dmlite_manager *manager, const char* lib, const char* id);
84 
85 /**
86  * @brief Sets a configuration parameter.
87  * @param manager The plugin manager.
88  * @param key The parameter to set.
89  * @param value The value.
90  * @return 0 on success, error code otherwise.
91  */
92 int dmlite_manager_set(dmlite_manager* manager, const char* key, const char* value);
93 
94 /**
95  * @brief Loads a configuration file.
96  * @param manager The plugin manager.
97  * @param file The configuration file
98  * @return 0 on success, error code otherwise.
99  */
100 int dmlite_manager_load_configuration(dmlite_manager* manager, const char* file);
101 
102 /**
103  * @brief Returns the associated value with the given key.
104  * @param manager The plugin manager.
105  * @param key The configuration parameter.
106  * @param buffer Where to leave the string.
107  * @param bufsize The buffer size.
108  */
109 int dmlite_manager_get(dmlite_manager* handle, const char* key, char* buffer, size_t bufsize);
110 
111 /**
112  * @brief Returns the last error code.
113  * @param manager The plugin manager used in the failing function.
114  * @return The last error code, WITHOUT the error type byte.
115  */
117 
118 /**
119  * @brief Returns the type of the last error.
120  * @param manager The plugin manager used in the failing function.
121  * @return The last error type byte.
122  */
124 
125 /**
126  * @brief Returns the string that describes the last error.
127  * @param manager The plugin manager used in the failing function.
128  * @return A pointer to the error string. Do NOT free it.
129  */
130 const char* dmlite_manager_error(dmlite_manager* manager);
131 
132 /**
133  * @brief Returns a usable context from the loaded libraries.
134  * @param manager The plugin manager.
135  * @return NULL on failure. The error code can be checked with dmlite_manager_error.
136  * @note A context is NOT thread safe.
137  */
139 
140 /**
141  * @brief Destroys the context.
142  * @param context The context to free.
143  * @return 0 on success, error code otherwise.
144  */
145 int dmlite_context_free(dmlite_context* context);
146 
147 /**
148  * @brief Returns the error code from the last failure.
149  * @param context The context that was used in the failed function.
150  * @return The error code.
151  */
152 int dmlite_errno(dmlite_context* context);
153 
154 /**
155  * @brief Returns the type of the last error.
156  * @param context The context that was used in the failed function.
157  * @return The error type.
158  */
159 int dmlite_errtype(dmlite_context* context);
160 
161 /**
162  * @brief Error string from the last failed function.
163  * @param context The context that was used in the failed function.
164  * @return A string with the error description. Do NOT free it.
165  */
166 const char* dmlite_error(dmlite_context* context);
167 
168 /**
169  * @brief Sets the user security credentials.
170  * @param context The DM context.
171  * @param cred The security credentials.
172  * @return 0 on success, error code otherwise.
173  */
174 int dmlite_setcredentials(dmlite_context* context, const dmlite_credentials* cred);
175 
176 /**
177  * @brief Returns the security context. There is no need to free.
178  * @param context The DM context.
179  * @return The security context.
180  */
182 
183 /**
184  * @brief Sets a configuration parameter tied to a context.
185  * @details This can be used to pass advanced parameters to a plugin.
186  * @param context The DM context.
187  * @param k The configuration key.
188  * @param v Value.
189  * @return 0 on success, error code otherwise.
190  */
191 int dmlite_set(dmlite_context* context, const char* k, const dmlite_any* v);
192 
193 /**
194  * @brief Sets a configuration parameter tied to a context (array version).
195  * @param context The DM context.
196  * @param k The configuration key.
197  * @param n The configuration key.
198  * @param v Array of values.
199  * @return 0 on success, error code otherwise.
200  */
201 int dmlite_set_array(dmlite_context* context, const char* k,
202  unsigned n, dmlite_any* const* v);
203 
204 /**
205  * @brief Removes a configuration parameter.
206  * @param context The DM context.
207  * @param k The configuration key.
208  * @return 0 on success, error code otherwise.
209  */
210 int dmlite_unset(dmlite_context* context, const char* k);
211 
212 /**
213  * @brief Removes all configuration parameters previously set.
214  * @param context The DM context.
215  * @return 0 on success, error code otherwise.
216  */
217 int dmlite_unset_all(dmlite_context* context);
218 
219 #ifdef __cplusplus
220 }
221 #endif
222 
223 #endif /* DMLITE_DMLITE_H */
dmlite_any_dict * extra
Definition: dmlite.h:39
unsigned nfqans
Definition: dmlite.h:36
int dmlite_unset_all(dmlite_context *context)
Removes all configuration parameters previously set.
const char ** fqans
Definition: dmlite.h:37
int dmlite_manager_set(dmlite_manager *manager, const char *key, const char *value)
Sets a configuration parameter.
Security credentials.
Definition: dmlite.h:30
dmlite_any_dict * extra
Definition: dmlite.h:46
int dmlite_unset(dmlite_context *context, const char *k)
Removes a configuration parameter.
int dmlite_manager_free(dmlite_manager *manager)
Destroys the manager.
Error codes.
struct dmlite_any_dict dmlite_any_dict
Handles key-&gt;value pairs.
Definition: any.h:25
struct dmlite_credentials dmlite_credentials
Security credentials.
Security context.
Definition: dmlite.h:51
const char * name
Definition: dmlite.h:45
const dmlite_security_context * dmlite_get_security_context(dmlite_context *context)
Returns the security context. There is no need to free.
const char * remote_address
Definition: dmlite.h:33
int dmlite_manager_errno(dmlite_manager *manager)
Returns the last error code.
dmlite_security_ent * groups
Definition: dmlite.h:56
Header generated by CMake with the build configuration used.
int dmlite_manager_load_plugin(dmlite_manager *manager, const char *lib, const char *id)
Loads a library.
dmlite_context * dmlite_context_new(dmlite_manager *manager)
Returns a usable context from the loaded libraries.
const char * session_id
Definition: dmlite.h:34
dmlite_credentials * credentials
Definition: dmlite.h:52
unsigned dmlite_api_version(void)
Gets the API version.
struct dmlite_security_ent dmlite_security_ent
Used to handle user and group information.
const char * mech
Definition: dmlite.h:31
Opaque handler to pass different types of values to the API.
struct dmlite_context dmlite_context
Handle for a initialized context.
Definition: dmlite.h:23
dmlite_manager * dmlite_manager_new(void)
Initializes a dmlite_manager.
int dmlite_setcredentials(dmlite_context *context, const dmlite_credentials *cred)
Sets the user security credentials.
Used to handle user and group information.
Definition: dmlite.h:44
const char * client_name
Definition: dmlite.h:32
const char * dmlite_error(dmlite_context *context)
Error string from the last failed function.
const char * dmlite_manager_error(dmlite_manager *manager)
Returns the string that describes the last error.
int dmlite_manager_get(dmlite_manager *handle, const char *key, char *buffer, size_t bufsize)
Returns the associated value with the given key.
dmlite_security_ent user
Definition: dmlite.h:55
int dmlite_set(dmlite_context *context, const char *k, const dmlite_any *v)
Sets a configuration parameter tied to a context.
int dmlite_manager_load_configuration(dmlite_manager *manager, const char *file)
Loads a configuration file.
int dmlite_context_free(dmlite_context *context)
Destroys the context.
int dmlite_errno(dmlite_context *context)
Returns the error code from the last failure.
int dmlite_manager_errtype(dmlite_manager *manager)
Returns the type of the last error.
unsigned ngroups
Definition: dmlite.h:54
struct dmlite_any dmlite_any
Used to pass configuration values.
Definition: any.h:20
struct dmlite_security_context dmlite_security_context
Security context.
int dmlite_errtype(dmlite_context *context)
Returns the type of the last error.
struct dmlite_manager dmlite_manager
Handle for the plugin manager.
Definition: dmlite.h:21
int dmlite_set_array(dmlite_context *context, const char *k, unsigned n, dmlite_any *const *v)
Sets a configuration parameter tied to a context (array version).