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 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
										 	 	 */
} 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.
 *             The actual directory name used to store the DMS will be
 *             `<dms_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 occurred
 *
 * @see obi_close_dms()
 * @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.
 *
 * @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
 *             `<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 occurred during memory allocation.
 *
 * @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.
 *             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_LONG_NAME_ERROR : the database name exceeds the limit.
 * 		- OBIDMS_MEMORY_ERROR    : something wrong occurred during memory allocation.
 *
 * @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 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.
 *             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 occurred during memory allocation.
 *
 * @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()
 *
 * @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_ */