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 
39  // These fields may come from openid-connect
40  const char *oidc_audience;
41  const char *oidc_issuer;
42  const char *oidc_scope;
43 
46 
47 /** @brief Used to handle user and group information
48  */
49 typedef struct dmlite_security_ent {
50  const char* name;
53 
54 /** @brief Security context
55  */
56 typedef struct dmlite_security_context {
58 
59  unsigned ngroups;
63 
64 /**
65  * @brief Gets the API version.
66  */
67 unsigned dmlite_api_version(void);
68 
69 /**
70  * @brief Initializes a dmlite_manager.
71  * @return NULL on failure.
72  */
74 
75 /**
76  * @brief Destroys the manager.
77  * @param manager The manager to be destroyed.
78  */
80 
81 /**
82  * @brief Loads a library.
83  * @param manager The plugin manager.
84  * @param lib The .so file. Usually, (path)/plugin_name.so.
85  * @param id The plugin ID. Usually, plugin_name.
86  * @return 0 on success, error code otherwise.
87  */
88 int dmlite_manager_load_plugin(dmlite_manager *manager, const char* lib, const char* id);
89 
90 /**
91  * @brief Sets a configuration parameter.
92  * @param manager The plugin manager.
93  * @param key The parameter to set.
94  * @param value The value.
95  * @return 0 on success, error code otherwise.
96  */
97 int dmlite_manager_set(dmlite_manager* manager, const char* key, const char* value);
98 
99 /**
100  * @brief Loads a configuration file.
101  * @param manager The plugin manager.
102  * @param file The configuration file
103  * @return 0 on success, error code otherwise.
104  */
105 int dmlite_manager_load_configuration(dmlite_manager* manager, const char* file);
106 
107 /**
108  * @brief Returns the associated value with the given key.
109  * @param manager The plugin manager.
110  * @param key The configuration parameter.
111  * @param buffer Where to leave the string.
112  * @param bufsize The buffer size.
113  */
114 int dmlite_manager_get(dmlite_manager* handle, const char* key, char* buffer, size_t bufsize);
115 
116 /**
117  * @brief Returns the last error code.
118  * @param manager The plugin manager used in the failing function.
119  * @return The last error code, WITHOUT the error type byte.
120  */
122 
123 /**
124  * @brief Returns the type of the last error.
125  * @param manager The plugin manager used in the failing function.
126  * @return The last error type byte.
127  */
129 
130 /**
131  * @brief Returns the string that describes the last error.
132  * @param manager The plugin manager used in the failing function.
133  * @return A pointer to the error string. Do NOT free it.
134  */
135 const char* dmlite_manager_error(dmlite_manager* manager);
136 
137 /**
138  * @brief Returns a usable context from the loaded libraries.
139  * @param manager The plugin manager.
140  * @return NULL on failure. The error code can be checked with dmlite_manager_error.
141  * @note A context is NOT thread safe.
142  */
144 
145 /**
146  * @brief Destroys the context.
147  * @param context The context to free.
148  * @return 0 on success, error code otherwise.
149  */
150 int dmlite_context_free(dmlite_context* context);
151 
152 /**
153  * @brief Returns the error code from the last failure.
154  * @param context The context that was used in the failed function.
155  * @return The error code.
156  */
157 int dmlite_errno(dmlite_context* context);
158 
159 /**
160  * @brief Returns the type of the last error.
161  * @param context The context that was used in the failed function.
162  * @return The error type.
163  */
164 int dmlite_errtype(dmlite_context* context);
165 
166 /**
167  * @brief Error string from the last failed function.
168  * @param context The context that was used in the failed function.
169  * @return A string with the error description. Do NOT free it.
170  */
171 const char* dmlite_error(dmlite_context* context);
172 
173 /**
174  * @brief Sets the user security credentials.
175  * @param context The DM context.
176  * @param cred The security credentials.
177  * @return 0 on success, error code otherwise.
178  */
179 int dmlite_setcredentials(dmlite_context* context, const dmlite_credentials* cred);
180 
181 /**
182  * @brief Returns the security context. There is no need to free.
183  * @param context The DM context.
184  * @return The security context.
185  */
187 
188 /**
189  * @brief Sets a configuration parameter tied to a context.
190  * @details This can be used to pass advanced parameters to a plugin.
191  * @param context The DM context.
192  * @param k The configuration key.
193  * @param v Value.
194  * @return 0 on success, error code otherwise.
195  */
196 int dmlite_set(dmlite_context* context, const char* k, const dmlite_any* v);
197 
198 /**
199  * @brief Sets a configuration parameter tied to a context (array version).
200  * @param context The DM context.
201  * @param k The configuration key.
202  * @param n The configuration key.
203  * @param v Array of values.
204  * @return 0 on success, error code otherwise.
205  */
206 int dmlite_set_array(dmlite_context* context, const char* k,
207  unsigned n, dmlite_any* const* v);
208 
209 /**
210  * @brief Removes a configuration parameter.
211  * @param context The DM context.
212  * @param k The configuration key.
213  * @return 0 on success, error code otherwise.
214  */
215 int dmlite_unset(dmlite_context* context, const char* k);
216 
217 /**
218  * @brief Removes all configuration parameters previously set.
219  * @param context The DM context.
220  * @return 0 on success, error code otherwise.
221  */
222 int dmlite_unset_all(dmlite_context* context);
223 
224 #ifdef __cplusplus
225 }
226 #endif
227 
228 #endif /* DMLITE_DMLITE_H */
dmlite_any_dict * extra
Definition: dmlite.h:44
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:51
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->value pairs.
Definition: any.h:25
struct dmlite_credentials dmlite_credentials
Security credentials.
Security context.
Definition: dmlite.h:56
const char * name
Definition: dmlite.h:50
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:61
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:57
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:49
const char * client_name
Definition: dmlite.h:32
const char * oidc_issuer
Definition: dmlite.h:41
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:60
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:59
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).
const char * oidc_scope
Definition: dmlite.h:42
const char * oidc_audience
Definition: dmlite.h:40