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 <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 */

Generated on 3 Mar 2013 for dmlite by  doxygen 1.4.7