dmlite  0.4
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 <stdlib.h>
9 #include <sys/stat.h>
10 #include <utime.h>
11 #include "any.h"
12 #include "../common/errno.h"
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 /** @brief Handle for the plugin manager. */
20 /** @brief Handle for a initialized context. */
22 
23 /** @brief Security credentials
24  * @details It is up to the caller to allocate and free this pointers.
25  * DMLite will keep a copy internaly.
26  * Non used values MUST be NULL.
27  */
28 typedef struct dmlite_credentials {
29  const char* mech;
30  const char* client_name;
31  const char* remote_address;
32  const char* session_id;
33 
34  unsigned nfqans;
35  const char** fqans;
36 
39 
40 /**
41  * @brief Gets the API version.
42  */
43 unsigned dmlite_api_version(void);
44 
45 /**
46  * @brief Initializes a dmlite_manager.
47  * @return NULL on failure.
48  */
50 
51 /**
52  * @brief Destroys the manager.
53  * @param manager The manager to be destroyed.
54  */
56 
57 /**
58  * @brief Loads a library.
59  * @param manager The plugin manager.
60  * @param lib The .so file. Usually, (path)/plugin_name.so.
61  * @param id The plugin ID. Usually, plugin_name.
62  * @return 0 on success, error code otherwise.
63  */
64 int dmlite_manager_load_plugin(dmlite_manager *manager, const char* lib, const char* id);
65 
66 /**
67  * @brief Sets a configuration parameter.
68  * @param manager The plugin manager.
69  * @param key The parameter to set.
70  * @param value The value.
71  * @return 0 on success, error code otherwise.
72  */
73 int dmlite_manager_set(dmlite_manager* manager, const char* key, const char* value);
74 
75 /**
76  * @brief Loads a configuration file.
77  * @param manager The plugin manager.
78  * @param file The configuration file
79  * @return 0 on success, error code otherwise.
80  */
81 int dmlite_manager_load_configuration(dmlite_manager* manager, const char* file);
82 
83 /**
84  * @brief Returns the last error code.
85  * @param manager The plugin manager used in the failing function.
86  * @return The last error code.
87  */
89 
90 /**
91  * @brief Returns the string that describes the last error.
92  * @param manager The plugin manager used in the failing function.
93  * @return A pointer to the error string. Do NOT free it.
94  */
95 const char* dmlite_manager_error(dmlite_manager* manager);
96 
97 /**
98  * @brief Returns a usable context from the loaded libraries.
99  * @param manager The plugin manager.
100  * @return NULL on failure. The error code can be checked with dmlite_manager_error.
101  * @note A context is NOT thread safe.
102  */
104 
105 /**
106  * @brief Destroys the context.
107  * @param context The context to free.
108  * @return 0 on success, error code otherwise.
109  */
110 int dmlite_context_free(dmlite_context* context);
111 
112 /**
113  * @brief Returns the error code from the last failure.
114  * @param context The context that was used in the failed function.
115  * @return The error code.
116  */
117 int dmlite_errno(dmlite_context* context);
118 
119 /**
120  * @brief Error string from the last failed function.
121  * @param context The context that was used in the failed function.
122  * @return A string with the error description. Do NOT free it.
123  */
124 const char* dmlite_error(dmlite_context* context);
125 
126 /**
127  * @brief Sets the user security credentials.
128  * @param context The DM context.
129  * @param cred The security credentials.
130  * @return 0 on success, error code otherwise.
131  */
133 
134 /**
135  * @brief Sets a configuration parameter tied to a context.
136  * @details This can be used to pass advanced parameters to a plugin.
137  * @param context The DM context.
138  * @param k The configuration key.
139  * @param v Value.
140  * @return 0 on success, error code otherwise.
141  */
142 int dmlite_set(dmlite_context* context, const char* k, const dmlite_any* v);
143 
144 #ifdef __cplusplus
145 }
146 #endif
147 
148 #endif /* DMLITE_DMLITE_H */