169 lines
5.5 KiB
C
169 lines
5.5 KiB
C
/*
|
|
* obidms.h
|
|
*
|
|
* Created on: 23 mai 2015
|
|
* Author: coissac
|
|
*/
|
|
|
|
#ifndef OBIDMS_H_
|
|
#define OBIDMS_H_
|
|
|
|
#include <stdlib.h>
|
|
#include <sys/stat.h>
|
|
#include <errno.h>
|
|
#include <dirent.h>
|
|
#include <string.h>
|
|
#include <stdio.h>
|
|
|
|
#include <obierrno.h>
|
|
|
|
#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
|
|
* `<name>.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
|
|
* `<name>.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
|
|
* `<name>.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
|
|
* `<name>.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_ */
|