enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

more dox -> .h 

SVN revision: 58437
This commit is contained in:
Carsten Haitzler 2011-04-07 12:57:44 +00:00
parent 046360b50b
commit 11ed8ad05f
3 changed files with 206 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
legacy/eina/src/include/eina_error.h
View File

@ -176,6 +176,8 @@ typedef int Eina_Error;
* Error identifier corresponding to a lack of memory.
*/
EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY;
/**
* @brief Register a new error type.
*
@ -190,8 +192,6 @@ typedef int Eina_Error;
*
* @see eina_error_msg_static_register()
*/
EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY;
EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**

205
legacy/eina/src/include/eina_module.h
View File

@ -23,6 +23,14 @@
#include "eina_array.h"
#include "eina_error.h"
/**
* @addtogroup Eina_Module_Group Module
*
* @brief These functions provide module management.
*
* @{
*/
/**
* @addtogroup Eina_Tools_Group Tools
*
@ -86,7 +94,7 @@ typedef void (*Eina_Module_Shutdown)(void);
* declares the given function as the module initializer (__eina_module_init).
* It must be of signature #Eina_Module_Init
*/
#define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f
#define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f
/**
* @def EINA_MODULE_SHUTDOWN
@ -108,34 +116,221 @@ extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE;
*/
extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED;
/**
* @brief Return a new module.
*
* @param file The name of the file module to load.
*
* This function returns a new module. If @p file is @c NULL, the
* function returns @c NULL, otherwise, it allocates an Eina_Module,
* stores a duplicate string of @p file, sets its reference to @c 0
* and its handle to @c NULL.
*
* When the new module is not needed anymore, use eina_module_free()
* to free the allocated memory.
*
* @see eina_module_load
*/
EAPI Eina_Module *
eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Delete a module.
*
* @param m The module to delete.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function calls eina_module_unload() if @p m has been previously
* loaded and frees the allocated memory. On success this function
* returns EINA_TRUE and EINA_FALSE otherwise. If @p m is @c NULL, the
* function returns immediately.
*/
EAPI Eina_Bool
eina_module_free(Eina_Module *m) EINA_ARG_NONNULL(1);
/**
* @brief Load a module.
*
* @param m The module to load.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function load the shared file object passed in
* eina_module_new(). If it is a internal Eina module (like the
* mempools), it also initialize it. It the shared file object can not
* be loaded, the error #EINA_ERROR_WRONG_MODULE is set and
* #EINA_FALSE is returned. If it is a internal Eina module and the
* module can not be initialized, the error
* #EINA_ERROR_MODULE_INIT_FAILED is set and #EINA_FALSE is
* returned. If the module has already been loaded, it's refeence
* counter is increased by one and #EINA_TRUE is returned. If @p m is
* @c NULL, the function returns immediately #EINA_FALSE.
*
* When the symbols of the shared file objetcts are not needed
* anymore, call eina_module_unload() to unload the module.
*/
EAPI Eina_Bool
eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1);
/**
* @brief Unload a module.
*
* @param m The module to load.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function unload the module @p m that has been previously
* loaded by eina_module_load(). If the reference counter of @p m is
* strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the
* shared object file is closed and if it is a internal Eina module, it
* is shutted down just before. In that case, #EINA_TRUE is
* returned. In all case, the reference counter is decreased. If @p m
* is @c NULL, the function returns immediately #EINA_FALSE.
*/
EAPI Eina_Bool
eina_module_unload(Eina_Module *m) EINA_ARG_NONNULL(1);
/**
* @brief Retrive the data associated to a symbol.
*
* @param m The module.
* @param symbol The symbol.
* @return The data associated to the symbol, or @c NULL on failure.
*
* This function returns the data associated to @p symbol of @p m. @p
* m must have been loaded before with eina_module_load(). If @p m
* is @c NULL, or if it has not been correctly loaded before, the
* function returns immediately @c NULL.
*/
EAPI void *
eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Return the file name associated to the module.
*
* @param m The module.
* @return The file name.
*
* This function returns the file name passed in eina_module_new(). If
* @p m is @c NULL, the function returns immediately @c NULL. The
* returned value must no be freed.
*/
EAPI const char *
eina_module_file_get(const Eina_Module *m) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Return the path built from the location of a library and a
* given sub directory.
*
* @param symbol The symbol to search for.
* @param sub_dir The subdirectory to append.
* @return The built path on success, @c NULL otherwise.
*
* This function returns the path built by concatenating the path of
* the library containing the symbol @p symbol and @p sub_dir. @p sub_dir
* can be @c NULL. The returned path must be freed when not used
* anymore. If the symbol is not found, or dl_addr() is not supported,
* or allocation fails, this function returns @c NULL.
*/
EAPI char *
eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
/**
* @brief Return the path built from the value of an environment varialbe and a
* given sub directory.
*
* @param env The environment variable to expand.
* @param sub_dir The subdirectory to append.
* @return The built path on success, @c NULL otherwise.
*
* This function returns the path built by concatenating the value of
* the environment variable named @p env and @p sub_dir. @p sub_dir
* can be @c NULL. The returned path must be freed when not used
* anymore. If the symbol is not found, or @p env does not exist, or
* allocation fails, this function returns @c NULL.
*/
EAPI char *
eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
/**
* @brief Get an array of modules found on the directory path matching an arch type.
*
* @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules.
* @param arch The architecture string.
*
* This function adds to @p array the module names found in @p path
* which match the cpu architecture @p arch. If @p path or @p arch is
* @c NULL, the function returns immediately @p array. @p array can be
* @c NULL. In that case, it is created with 4 elements.
*/
EAPI Eina_Array *
eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch);
/**
* @brief Get a list of modules found on the directory path.
*
* @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules.
* @param recursive Iterate recursively on the path.
* @param cb Callback function to call on each module.
* @param data Data passed to the callback function.
*
* This function adds to @p array the list of modules found in
* @p path. If @p recursive is #EINA_TRUE, then recursive search is
* done. The callback @p cb is called on each module found, and @p data
* is passed to @p cb. If @p path is @c NULL, the function returns
* immediately @p array. If the returned value of @p cb is 0, the
* module will not be added to the list, otherwise it will be added.
* @p array can be @c NULL. In that case, it is created with 4
* elements. @p cb can be @c NULL.
*/
EAPI Eina_Array *
eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Load every module on the list of modules.
*
* @param array The array of modules to load.
*
* This function calls eina_module_load() on each element found in
* @p array. If @p array is @c NULL, this function does nothing.
*/
EAPI void
eina_module_list_load(Eina_Array *list) EINA_ARG_NONNULL(1);
/**
* @brief Unload every module on the list of modules.
*
* @param array The array of modules to unload.
*
* This function calls eina_module_unload() on each element found in
* @p array. If @p array is @c NULL, this function does nothing.
*/
EAPI void
eina_module_list_unload(Eina_Array *list) EINA_ARG_NONNULL(1);
/**
* @p Free every module on the list of modules.
*
* @param array The array of modules to free.
*
* This function calls eina_module_free() on each element found in
* @p array. If @p array is @c NULL, this function does nothing.
*/
EAPI void
eina_module_list_free(Eina_Array *list) EINA_ARG_NONNULL(1);
/**
* @brief Find an module in array.
*
* @param array The array to find the module.
* @param module The name of module to be searched.
*
* This function finds an @p module in @p array.
* If the element is found the function returns the module, else
* @c NULL is returned.
*/
EAPI Eina_Module *
eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2);
@ -147,4 +342,12 @@ EAPI Eina_Module *
* @}
*/
/**
* @}
*/
/**
* @}
*/
#endif /*EINA_MODULE_H_*/

182
legacy/eina/src/lib/eina_module.c
View File

@ -262,29 +262,6 @@ eina_module_shutdown(void)
* API *
*============================================================================*/
/**
* @addtogroup Eina_Module_Group Module
*
* @brief These functions provide module management.
*
* @{
*/
/**
* @brief Return a new module.
*
* @param file The name of the file module to load.
*
* This function returns a new module. If @p file is @c NULL, the
* function returns @c NULL, otherwise, it allocates an Eina_Module,
* stores a duplicate string of @p file, sets its reference to @c 0
* and its handle to @c NULL.
*
* When the new module is not needed anymore, use eina_module_free()
* to free the allocated memory.
*
* @see eina_module_load
*/
EAPI Eina_Module *eina_module_new(const char *file)
{
Eina_Module *m;
@ -312,17 +289,6 @@ EAPI Eina_Module *eina_module_new(const char *file)
return m;
}
/**
* @brief Delete a module.
*
* @param m The module to delete.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function calls eina_module_unload() if @p m has been previously
* loaded and frees the allocated memory. On success this function
* returns EINA_TRUE and EINA_FALSE otherwise. If @p m is @c NULL, the
* function returns immediately.
*/
EAPI Eina_Bool eina_module_free(Eina_Module *m)
{
EINA_SAFETY_ON_NULL_RETURN_VAL(m, EINA_FALSE);
@ -337,26 +303,6 @@ EAPI Eina_Bool eina_module_free(Eina_Module *m)
return EINA_TRUE;
}
/**
* @brief Load a module.
*
* @param m The module to load.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function load the shared file object passed in
* eina_module_new(). If it is a internal Eina module (like the
* mempools), it also initialize it. It the shared file object can not
* be loaded, the error #EINA_ERROR_WRONG_MODULE is set and
* #EINA_FALSE is returned. If it is a internal Eina module and the
* module can not be initialized, the error
* #EINA_ERROR_MODULE_INIT_FAILED is set and #EINA_FALSE is
* returned. If the module has already been loaded, it's refeence
* counter is increased by one and #EINA_TRUE is returned. If @p m is
* @c NULL, the function returns immediately #EINA_FALSE.
*
* When the symbols of the shared file objetcts are not needed
* anymore, call eina_module_unload() to unload the module.
*/
EAPI Eina_Bool eina_module_load(Eina_Module *m)
{
void *dl_handle;
@ -400,20 +346,6 @@ loaded:
return EINA_TRUE;
}
/**
* @brief Unload a module.
*
* @param m The module to load.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function unload the module @p m that has been previously
* loaded by eina_module_load(). If the reference counter of @p m is
* strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the
* shared object file is closed and if it is a internal Eina module, it
* is shutted down just before. In that case, #EINA_TRUE is
* returned. In all case, the reference counter is decreased. If @p m
* is @c NULL, the function returns immediately #EINA_FALSE.
*/
EAPI Eina_Bool eina_module_unload(Eina_Module *m)
{
Eina_Module_Shutdown *shut;
@ -437,18 +369,6 @@ EAPI Eina_Bool eina_module_unload(Eina_Module *m)
return EINA_FALSE;
}
/**
* @brief Retrive the data associated to a symbol.
*
* @param m The module.
* @param symbol The symbol.
* @return The data associated to the symbol, or @c NULL on failure.
*
* This function returns the data associated to @p symbol of @p m. @p
* m must have been loaded before with eina_module_load(). If @p m
* is @c NULL, or if it has not been correctly loaded before, the
* function returns immediately @c NULL.
*/
EAPI void *eina_module_symbol_get(const Eina_Module *m, const char *symbol)
{
EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL);
@ -456,36 +376,12 @@ EAPI void *eina_module_symbol_get(const Eina_Module *m, const char *symbol)
return dlsym(m->handle, symbol);
}
/**
* @brief Return the file name associated to the module.
*
* @param m The module.
* @return The file name.
*
* This function returns the file name passed in eina_module_new(). If
* @p m is @c NULL, the function returns immediately @c NULL. The
* returned value must no be freed.
*/
EAPI const char *eina_module_file_get(const Eina_Module *m)
{
EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL);
return m->file;
}
/**
* @brief Return the path built from the location of a library and a
* given sub directory.
*
* @param symbol The symbol to search for.
* @param sub_dir The subdirectory to append.
* @return The built path on success, @c NULL otherwise.
*
* This function returns the path built by concatenating the path of
* the library containing the symbol @p symbol and @p sub_dir. @p sub_dir
* can be @c NULL. The returned path must be freed when not used
* anymore. If the symbol is not found, or dl_addr() is not supported,
* or allocation fails, this function returns @c NULL.
*/
EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir)
{
#ifdef HAVE_DLADDR
@ -526,20 +422,6 @@ EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir)
return NULL;
}
/**
* @brief Return the path built from the value of an environment varialbe and a
* given sub directory.
*
* @param env The environment variable to expand.
* @param sub_dir The subdirectory to append.
* @return The built path on success, @c NULL otherwise.
*
* This function returns the path built by concatenating the value of
* the environment variable named @p env and @p sub_dir. @p sub_dir
* can be @c NULL. The returned path must be freed when not used
* anymore. If the symbol is not found, or @p env does not exist, or
* allocation fails, this function returns @c NULL.
*/
EAPI char *eina_module_environment_path_get(const char *env,
const char *sub_dir)
{
@ -574,18 +456,6 @@ EAPI char *eina_module_environment_path_get(const char *env,
return NULL;
}
/**
* @brief Get an array of modules found on the directory path matching an arch type.
*
* @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules.
* @param arch The architecture string.
*
* This function adds to @p array the module names found in @p path
* which match the cpu architecture @p arch. If @p path or @p arch is
* @c NULL, the function returns immediately @p array. @p array can be
* @c NULL. In that case, it is created with 4 elements.
*/
EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array,
const char *path,
const char *arch)
@ -604,24 +474,6 @@ EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array,
return list_get_cb_data.array;
}
/**
* @brief Get a list of modules found on the directory path.
*
* @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules.
* @param recursive Iterate recursively on the path.
* @param cb Callback function to call on each module.
* @param data Data passed to the callback function.
*
* This function adds to @p array the list of modules found in
* @p path. If @p recursive is #EINA_TRUE, then recursive search is
* done. The callback @p cb is called on each module found, and @p data
* is passed to @p cb. If @p path is @c NULL, the function returns
* immediately @p array. If the returned value of @p cb is 0, the
* module will not be added to the list, otherwise it will be added.
* @p array can be @c NULL. In that case, it is created with 4
* elements. @p cb can be @c NULL.
*/
EAPI Eina_Array *eina_module_list_get(Eina_Array *array,
const char *path,
Eina_Bool recursive,
@ -646,16 +498,6 @@ EAPI Eina_Array *eina_module_list_get(Eina_Array *array,
return list_get_cb_data.array;
}
/**
* @brief Find an module in array.
*
* @param array The array to find the module.
* @param module The name of module to be searched.
*
* This function finds an @p module in @p array.
* If the element is found the function returns the module, else
* @c NULL is returned.
*/
EAPI Eina_Module *
eina_module_find(const Eina_Array *array, const char *module)
{
@ -687,14 +529,6 @@ eina_module_find(const Eina_Array *array, const char *module)
return NULL;
}
/**
* @brief Load every module on the list of modules.
*
* @param array The array of modules to load.
*
* This function calls eina_module_load() on each element found in
* @p array. If @p array is @c NULL, this function does nothing.
*/
EAPI void eina_module_list_load(Eina_Array *array)
{
Eina_Array_Iterator iterator;
@ -707,14 +541,6 @@ EAPI void eina_module_list_load(Eina_Array *array)
eina_module_load(m);
}
/**
* @brief Unload every module on the list of modules.
*
* @param array The array of modules to unload.
*
* This function calls eina_module_unload() on each element found in
* @p array. If @p array is @c NULL, this function does nothing.
*/
EAPI void eina_module_list_unload(Eina_Array *array)
{
Eina_Array_Iterator iterator;
@ -727,14 +553,6 @@ EAPI void eina_module_list_unload(Eina_Array *array)
eina_module_unload(m);
}
/**
* @p Free every module on the list of modules.
*
* @param array The array of modules to free.
*
* This function calls eina_module_free() on each element found in
* @p array. If @p array is @c NULL, this function does nothing.
*/
EAPI void eina_module_list_free(Eina_Array *array)
{
Eina_Array_Iterator iterator;