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"
10#include "any.h"
11
12#include <stdlib.h>
13#include <sys/stat.h>
14#include <utime.h>
15
16#ifdef __cplusplus
17extern "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 */
30typedef 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 */
49typedef struct dmlite_security_ent {
50 const char* name;
53
54/** @brief Security context
55 */
58
59 unsigned ngroups;
63
64/**
65 * @brief Gets the API version.
66 */
67unsigned 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 */
88int 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 */
97int 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 */
105int 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 */
114int 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 */
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 */
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 */
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 */
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 */
171const 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 */
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 */
196int 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 */
206int 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 */
215int 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 */
223
224#ifdef __cplusplus
225}
226#endif
227
228#endif /* DMLITE_DMLITE_H */
Opaque handler to pass different types of values to the API.
struct dmlite_any dmlite_any
Used to pass configuration values.
Definition any.h:20
struct dmlite_any_dict dmlite_any_dict
Handles key->value pairs.
Definition any.h:25
int dmlite_manager_load_configuration(dmlite_manager *manager, const char *file)
Loads a configuration file.
int dmlite_manager_free(dmlite_manager *manager)
Destroys the manager.
int dmlite_manager_set(dmlite_manager *manager, const char *key, const char *value)
Sets a configuration parameter.
int dmlite_setcredentials(dmlite_context *context, const dmlite_credentials *cred)
Sets the user security credentials.
int dmlite_unset(dmlite_context *context, const char *k)
Removes a configuration parameter.
dmlite_manager * dmlite_manager_new(void)
Initializes a dmlite_manager.
int dmlite_context_free(dmlite_context *context)
Destroys the context.
const char * dmlite_manager_error(dmlite_manager *manager)
Returns the string that describes the last error.
int dmlite_manager_errtype(dmlite_manager *manager)
Returns the type of the last error.
struct dmlite_context dmlite_context
Handle for a initialized context.
Definition dmlite.h:23
struct dmlite_manager dmlite_manager
Handle for the plugin manager.
Definition dmlite.h:21
unsigned dmlite_api_version(void)
Gets the API version.
int dmlite_set(dmlite_context *context, const char *k, const dmlite_any *v)
Sets a configuration parameter tied to a context.
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 * dmlite_error(dmlite_context *context)
Error string from the last failed function.
int dmlite_errtype(dmlite_context *context)
Returns the type of the last error.
int dmlite_unset_all(dmlite_context *context)
Removes all configuration parameters previously set.
const dmlite_security_context * dmlite_get_security_context(dmlite_context *context)
Returns the security context. There is no need to free.
int dmlite_manager_get(dmlite_manager *handle, const char *key, char *buffer, size_t bufsize)
Returns the associated value with the given key.
int dmlite_manager_errno(dmlite_manager *manager)
Returns the last error code.
dmlite_context * dmlite_context_new(dmlite_manager *manager)
Returns a usable context from the loaded libraries.
int dmlite_manager_load_plugin(dmlite_manager *manager, const char *lib, const char *id)
Loads a library.
int dmlite_errno(dmlite_context *context)
Returns the error code from the last failure.
Error codes.
Security credentials.
Definition dmlite.h:30
unsigned nfqans
Definition dmlite.h:36
const char * oidc_scope
Definition dmlite.h:42
dmlite_any_dict * extra
Definition dmlite.h:44
const char * mech
Definition dmlite.h:31
const char * remote_address
Definition dmlite.h:33
const char * session_id
Definition dmlite.h:34
const char ** fqans
Definition dmlite.h:37
const char * client_name
Definition dmlite.h:32
const char * oidc_issuer
Definition dmlite.h:41
const char * oidc_audience
Definition dmlite.h:40
Security context.
Definition dmlite.h:56
unsigned ngroups
Definition dmlite.h:59
dmlite_security_ent * groups
Definition dmlite.h:61
dmlite_credentials * credentials
Definition dmlite.h:57
dmlite_security_ent user
Definition dmlite.h:60
Used to handle user and group information.
Definition dmlite.h:49
const char * name
Definition dmlite.h:50
dmlite_any_dict * extra
Definition dmlite.h:51