obitools3/src/obidms.h

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