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 <stdlib.h> 00009 #include <sys/stat.h> 00010 #include <utime.h> 00011 #include "any.h" 00012 #include "../common/errno.h" 00013 00014 #ifdef __cplusplus 00015 extern "C" { 00016 #endif 00017 00018 /** @brief Handle for the plugin manager. */ 00019 typedef struct dmlite_manager dmlite_manager; 00020 /** @brief Handle for a initialized context. */ 00021 typedef struct dmlite_context dmlite_context; 00022 00023 /** @brief Security credentials 00024 * @details It is up to the caller to allocate and free this pointers. 00025 * DMLite will keep a copy internaly. 00026 * Non used values MUST be NULL. 00027 */ 00028 typedef struct dmlite_credentials { 00029 const char* mech; 00030 const char* client_name; 00031 const char* remote_address; 00032 const char* session_id; 00033 00034 unsigned nfqans; 00035 const char** fqans; 00036 00037 dmlite_any_dict* extra; 00038 } dmlite_credentials; 00039 00040 /** 00041 * @brief Gets the API version. 00042 */ 00043 unsigned dmlite_api_version(void); 00044 00045 /** 00046 * @brief Initializes a dmlite_manager. 00047 * @return NULL on failure. 00048 */ 00049 dmlite_manager* dmlite_manager_new(void); 00050 00051 /** 00052 * @brief Destroys the manager. 00053 * @param manager The manager to be destroyed. 00054 */ 00055 int dmlite_manager_free(dmlite_manager* manager); 00056 00057 /** 00058 * @brief Loads a library. 00059 * @param manager The plugin manager. 00060 * @param lib The .so file. Usually, (path)/plugin_name.so. 00061 * @param id The plugin ID. Usually, plugin_name. 00062 * @return 0 on success, error code otherwise. 00063 */ 00064 int dmlite_manager_load_plugin(dmlite_manager *manager, const char* lib, const char* id); 00065 00066 /** 00067 * @brief Sets a configuration parameter. 00068 * @param manager The plugin manager. 00069 * @param key The parameter to set. 00070 * @param value The value. 00071 * @return 0 on success, error code otherwise. 00072 */ 00073 int dmlite_manager_set(dmlite_manager* manager, const char* key, const char* value); 00074 00075 /** 00076 * @brief Loads a configuration file. 00077 * @param manager The plugin manager. 00078 * @param file The configuration file 00079 * @return 0 on success, error code otherwise. 00080 */ 00081 int dmlite_manager_load_configuration(dmlite_manager* manager, const char* file); 00082 00083 /** 00084 * @brief Returns the last error code. 00085 * @param manager The plugin manager used in the failing function. 00086 * @return The last error code. 00087 */ 00088 int dmlite_manager_errno(dmlite_manager* manager); 00089 00090 /** 00091 * @brief Returns the string that describes the last error. 00092 * @param manager The plugin manager used in the failing function. 00093 * @return A pointer to the error string. Do NOT free it. 00094 */ 00095 const char* dmlite_manager_error(dmlite_manager* manager); 00096 00097 /** 00098 * @brief Returns a usable context from the loaded libraries. 00099 * @param manager The plugin manager. 00100 * @return NULL on failure. The error code can be checked with dmlite_manager_error. 00101 * @note A context is NOT thread safe. 00102 */ 00103 dmlite_context* dmlite_context_new(dmlite_manager* manager); 00104 00105 /** 00106 * @brief Destroys the context. 00107 * @param context The context to free. 00108 * @return 0 on success, error code otherwise. 00109 */ 00110 int dmlite_context_free(dmlite_context* context); 00111 00112 /** 00113 * @brief Returns the error code from the last failure. 00114 * @param context The context that was used in the failed function. 00115 * @return The error code. 00116 */ 00117 int dmlite_errno(dmlite_context* context); 00118 00119 /** 00120 * @brief Error string from the last failed function. 00121 * @param context The context that was used in the failed function. 00122 * @return A string with the error description. Do NOT free it. 00123 */ 00124 const char* dmlite_error(dmlite_context* context); 00125 00126 /** 00127 * @brief Sets the user security credentials. 00128 * @param context The DM context. 00129 * @param cred The security credentials. 00130 * @return 0 on success, error code otherwise. 00131 */ 00132 int dmlite_setcredentials(dmlite_context* context, dmlite_credentials* cred); 00133 00134 /** 00135 * @brief Sets a configuration parameter tied to a context. 00136 * @details This can be used to pass advanced parameters to a plugin. 00137 * @param context The DM context. 00138 * @param k The configuration key. 00139 * @param v Value. 00140 * @return 0 on success, error code otherwise. 00141 */ 00142 int dmlite_set(dmlite_context* context, const char* k, const dmlite_any* v); 00143 00144 #ifdef __cplusplus 00145 } 00146 #endif 00147 00148 #endif /* DMLITE_DMLITE_H */