obitools3/src/obidms.h

/********************************************************************
 * OBIDMS header file                                               *
 ********************************************************************/

/**
 * @file obidmscolumn.h
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 * @date 23 May 2015
 * @brief Header file for the OBIDMS functions and structures.
 */


#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 <stdbool.h>

#include "obierrno.h"


#define OBIDMS_MAX_NAME (2048) 	   /**< The maximum length of an OBIDMS name.
                                	*/
#define ARRAYS_DIR_NAME "arrays"   /**< The name of the arrays directory.
                                	*/


/**
 * @brief A structure describing 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	directory_name[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.
										 	 	 */
	int     dir_fd;								/**< The file descriptor of the directory entry
												 *   usable to refer and scan the database directory.
												 */
	DIR*	array_directory;					/**< A directory entry usable to
										 	 	 *   refer and scan the array directory.
										 	 	 */
	int		array_dir_fd;						/**< The file descriptor of the directory entry
												 *   usable to refer and scan the array directory.
												 */
	bool	little_endian;						/**< Endianness of the database.
												 */
} OBIDMS_t, *OBIDMS_p;


/**
 * @brief Checks if an OBIDMS exists.
 *
 * @param dms_name A pointer to a C string containing the name of the database.
 *
 * @returns An integer value indicating the status of the database
 * @retval 1 if the database exists.
 * @retval 0 if the database does not exist.
 * @retval -1 if an error occurred.
 *
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */
int obi_dms_exists(const char* dms_name);


/**
 * @brief Creates a new OBITools Data Management instance (OBIDMS).
 *
 * A `DMS` is implemented as a directory. This function checks
 * if a directory with this name does not already exist
 * before creating the new database.
 *
 * A directory to store obiarrays is also created.
 *
 * @param dms_name A pointer to a C string containing the name of the database.
 *                 The actual directory name used to store the DMS will be
 *                 `<dms_name>.obidms`.
 *
 * @returns A pointer to an OBIDMS structure describing the newly created DMS.
 * @retval NULL if an error occurred.
 *
 * @see obi_close_dms()
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */
OBIDMS_p obi_create_dms(const char* dms_name);


/**
 * @brief Opens an existing OBITools Data Management instance (OBIDMS).
 *
 * @param dms_name A pointer to a C string containing the name of the database.
 *
 * @returns A pointer to an OBIDMS structure describing the opened DMS.
 * @retval NULL if an error occurred.
 *
 * @see obi_close_dms()
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */
OBIDMS_p obi_open_dms(const char* dms_name);


/**
 * @brief Creates or opens a new OBIDMS instance.
 *
 * If the database already exists, this function opens it, otherwise it
 * creates a new database.
 *
 * @param dms_name A pointer to a C string containing the name of the database.
 *
 * @returns A pointer to an OBIDMS structure describing the OBIDMS.
 * @retval NULL if an error occurred.
 *
 * @see obi_close_dms()
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */
OBIDMS_p obi_dms(const char* dms_name);


/**
 * @brief Closes an opened OBITools Data Management instance (OBIDMS).
 *
 * @param dms A pointer as returned by obi_create_dms() or obi_open_dms().
 *
 * @returns An integer value indicating the success of the operation. Even on
 * 		    error, the `OBIDMS` structure is freed.
 * @retval 0 on success.
 * @retval -1 if an error occurred?-.
 *
 * @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_ */