obitools3/src/obidmscolumndir.h

/****************************************************************************
 * OBIDMS column directories header file                                    *
 ****************************************************************************/

/**
 * @file obidmscolumndir.h
 * @author Celine Mercier
 * @date 18 June 2015
 * @brief Header file for OBIDMS column directories.
 */

#ifndef OBIDMSCOLUMNGROUP_H_
#define OBIDMSCOLUMNGROUP_H_

#include <stdlib.h>
#include <stdio.h>
#include <dirent.h>

#include "obidms.h"

#define OBIDMS_MAX_COLNAME (128) /**< The maximum length of an OBIDMS column name
                                  */

#define OBIDMS_COLUMN_DIR_MAX_NAME (2048) 	/**< The maximum length of an OBIDMS column directory name
                                		 */

/** @brief A structure describing an OBIDMS column directory instance
 *
 * A pointer to this structure is returned on creation
 * and opening of an OBIDMS column directory.
 */

typedef struct OBIDMS_column_directory {
	OBIDMS_p	dms;	 										/**< A pointer to a DMS instance.
     	 	 	 	 	 	 	 	 	 	 	 	 		 	 */
	char 		column_name[OBIDMS_MAX_COLNAME+1];				/**< The name of the column
																 *   contained in the directory.
																 */
	char		directory_name[OBIDMS_COLUMN_DIR_MAX_NAME+1];	/**< The name of the directory
	                                     	 	 	 	 	 	 *   containing the column.
	                                     	 	 	 	 	 	 */
	DIR*		directory;										/**< A directory entry usable to
										 	 	 	 	 	 	 *   refer and scan the database directory.
										 	 	 	 	 	 	 */
} OBIDMS_column_directory_t, *OBIDMS_column_directory_p;


/*@
 * @brief Checks if an OBIDMS column directory exists
 *
 * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms()
 * @param column_name a pointer to a C string containing the name of the column.
 *                    The actual directory name used to store the column is
 *                    `<column_name>.obicol`.
 *
 * @return an integer value indicating the status of the column directory
 * @retvalue 1 the directory exist
 * @retvalue 0 the directory does not exist
 * @retvalue -1 an error occurred
 *
 * @see obi_close_column_directory()
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_directory_exists(OBIDMS_p dms, const char* column_name);


/**
 * @brief Creates a new OBIDMS column directory instance.
 *
 * A new OBIDMS column directory is created. This function checks
 * if a directory with this name does not already exist
 * before creating the new column directory.
 *
 * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms()
 * @param column_name a pointer to a C string containing the name of the column.
 *                    The actual directory name used to store the column will be
 *                    `<column_name>.obicol`.
 *
 * @return a pointer to an OBIDMS column directory structure describing the newly created
 * 		   directory
 * @retval NULL on error and the `obi_errno` variable is set.
 *
 * ###Error values
 * 		- OBIDMS_COL_DIR_EXIST_ERROR     : xxxxx a database with the same name already exists.
 *
 * @see obi_close_column_directory()
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
OBIDMS_column_directory_p obi_create_column_directory(OBIDMS_p dms, const char* column_name);


/**
 * @brief Opens an existing OBIDMS column directory instance.
 *
 * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms()
 * @param column_name a pointer to a C string containing the name of the column.
 *                    The actual directory name used to store the column is
 *                    `<column_name>.obicol`.
 *
 * @return a pointer to the OBIDMS column directory structure describing the directory
 * @retval NULL on error and the `obi_errno`variable is set.
 *
 * ###Error values
 * 		- OBIDMS_COL_DIR_ERROR     : xxxxx a database with the same name already exists.
 *
 * @see obi_close_column_directory()
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
OBIDMS_column_directory_p obi_open_column_directory(OBIDMS_p dms, const char* column_name);


/**
 * @brief Opens or creates a new OBIDMS column directory instance.
 *
 * If the directory already exists, this function opens it, otherwise it
 * creates a new column directory.
 *
 * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms()
 * @param column_name a pointer to a C string containing the name of the column.
 *                    The actual directory name used to store the column is
 *                    `<column_name>.obicol`.
 *
 * @return a pointer to the OBIDMS column directory structure describing the directory
 * @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.
 *
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
OBIDMS_column_directory_p obi_column_directory(OBIDMS_p dms, const char* column_name);


/**
 * @brief Closes an opened OBIDMS column directory instance.
 *
 * @param column_directory a pointer to an OBIDMS column directory as returned by
 * obi_create_column_directory() or obi_open_column_directory()
 *
 * @return an integer value indicating the success of the operation. Even on
 * 		   error, the `OBIDMS_column_directory` structure is freed
 * @retvalue 0 on success
 * @retvalue -1 on failure and the `obi_errno` variable is set.
 *
 * @see obi_create_column_directory()
 * @see obi_open_column_directory()
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_close_column_directory(OBIDMS_column_directory_p column_directory);


#endif /* OBIDMSCOLUMNDIR_H_ */