/* * obidms.h * * Created on: 23 mai 2015 * Author: coissac */ #ifndef OBIDMS_H_ #define OBIDMS_H_ #include #include #include #include #include #include #include #define OBIDMS_MAX_NAME (2048) /**< The maximum length of an OBIDMS name */ /** @brief A structure decribing an OBIDMS instance * * A pointer to this structure is returned on creation * and opening of an OBITools Data Management System (DMS) */ typedef struct OBIDMS { char dirname[OBIDMS_MAX_NAME+1]; /**< The name of the directory * containing the DMS */ DIR *directory; /**< A directory entry usable to * refer and scan the database directory */ } OBIDMS_t, *OBIDMS_p; /** * @defgroup OBIDMSErrors OBIDMS related error codes * * Error codes set in errno following an error related * to the manipulation of an OBIDMS. * * @{ */ #define OBIDMS_EXIST_ERROR (1) /**< Try to create an OBIDMS with a name * that corresponds to an existing OBIDMS */ #define OBIDMS_NOT_EXIST_ERROR (2) /**< Try to open a non-existing OBIDMS */ #define OBIDMS_LONG_NAME_ERROR (3) /**< The specified OBIDMS name is too long */ #define OBIDMS_MEMORY_ERROR (4) /**< A memory error occurred during allocation */ #define OBIDMS_UNKNOWN_ERROR (5) /**< Not determined error */ #define OBIDMS_ACCESS_ERROR (6) /**< Permission error for accessing to the database */ #define OBIDMS_BAD_ENDIAN_ERROR (7) /**< The opened data structure does not corresponds * to the endianess of the platform. */ /**@}*/ /*@ * @brief Check if a OBIDMS exist * * @param name a pointer to a C string containing the name of the database * the actual directory name used to store the DMS will be * `.obidms` * * @return an integer value indicating the status of the database * @retvalue 1 the database exist * @retvalue 0 the database does not exist * @retvalue -1 an error occurs * * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ int obi_dms_exists(const char* name); /** * @brief Create a new OBITools Data Management instance (OBIDMS). * * A `DMS` is implemented as a directory. This function takes care * to check if a directory with this name does not already exist * before creating the new database * * @param name a pointer to a C string containing the name of the database * the actual directory name used to store the DMS will be * `.obidms` * * @return a pointer to an OBIDMS structure describing the newly created DMS * @retval NULL on error and the `obi_errno` variable is set. * * ###Error values * - OBIDMS_EXIST_ERROR : a database with the same name already exists. * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. * - OBIDMS_MEMORY_ERROR : something wrong occurs during memory allocation. * * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ OBIDMS_p obi_create_dms(const char *name); /** * @brief Open an existing OBITools Data Management instance (OBIDMS). * * @param name a pointer to a C string containing the name of the database * the actual directory name used to store the DMS will be * `.obidms` * * @return a pointer to an OBIDMS structure describing the newly created DMS * @retval NULL on error and the `obi_errno`variable is set. * * ###Error values * - OBIDMS_EXIST_ERROR : a database with the same name already exists. * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. * - OBIDMS_MEMORY_ERROR : something wrong occurs during memory allocation. * * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ OBIDMS_p obi_open_dms(const char *name); /** * @brief Create a new OBIDMS instance. * * If the database already exist this function open it, otherwise it * creates a new databse. * * @param name a pointer to a C string containing the name of the database * the actual directory name used to store the DMS is * `.obidms` * * @return a pointer to an OBIDMS structure describing the newly created DMS * @retval NULL on error and the `obi_errno`variable is set. * * ###Error values * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. * - OBIDMS_MEMORY_ERROR : something wrong occurs during memory allocation. * * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ OBIDMS_p obi_dms(const char *name); /** * @brief Close an opened OBITools Data Management instance (OBIDMS). * * @param dms a pointer as returned by obi_create_dms() or obi_open_dms() * * @return an integer value indicating the success of the operation. Even on * error, the `OBIDMS` structure is freed * @retvalue 0 on success * @retvalue -1 on failure and the `obi_errno` variable is set. * * @see obi_create_dms() * @see obi_open_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ int obi_close_dms(OBIDMS_p dms); #endif /* OBIDMS_H_ */