include/dmlite/c/dmlite.h

Go to the documentation of this file.
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 */

Generated on 28 Apr 2014 for dmlite by  doxygen 1.4.7