159 lines
5.7 KiB
C
159 lines
5.7 KiB
C
|
/****************************************************************************
|
||
|
|
* OBIDMS column directories header file *
|
||
|
|
****************************************************************************/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @file obidmscolumngroup.h
|
||
|
|
* @author Celine Mercier
|
||
|
|
* @date 18 June 2015
|
||
|
|
* @brief Header file for OBIDMS column groups.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#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 group instance
|
||
|
|
*
|
||
|
|
* A pointer to this structure is returned on creation
|
||
|
|
* and opening of an OBIDMS column group.
|
||
|
|
*/
|
||
|
|
|
||
|
|
typedef struct OBIDMS_column_group {
|
||
|
|
OBIDMS_p dms; /**< A pointer to a DMS instance.
|
||
|
|
*/
|
||
|
|
char column_name[OBIDMS_MAX_COLNAME+1]; /**< The name of the column group
|
||
|
|
* contained in the directory.
|
||
|
|
*/
|
||
|
|
char directory_name[OBIDMS_COLUMN_DIR_MAX_NAME+1]; /**< The name of the directory
|
||
|
|
* containing the column group.
|
||
|
|
*/
|
||
|
|
DIR* directory; /**< A directory entry usable to
|
||
|
|
* refer and scan the database directory.
|
||
|
|
*/
|
||
|
|
} OBIDMS_column_group_t, *OBIDMS_column_group_p;
|
||
|
|
|
||
|
|
|
||
|
|
/*@
|
||
|
|
* @brief Checks if an OBIDMS column group 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 group
|
||
|
|
* @retvalue 1 the group exist
|
||
|
|
* @retvalue 0 the group does not exist
|
||
|
|
* @retvalue -1 an error occurred
|
||
|
|
*
|
||
|
|
* @see obi_close_column_group()
|
||
|
|
* @since June 2015
|
||
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
||
|
|
*/
|
||
|
|
int obi_column_group_exists(OBIDMS_p dms, const char* column_name);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Creates a new OBIDMS column group instance.
|
||
|
|
*
|
||
|
|
* A new OBIDMS column group is created. This function checks
|
||
|
|
* if a directory with this name does not already exist
|
||
|
|
* before creating the new column group.
|
||
|
|
*
|
||
|
|
* @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 group structure describing the newly created
|
||
|
|
* group
|
||
|
|
* @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_group()
|
||
|
|
* @since June 2015
|
||
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
||
|
|
*/
|
||
|
|
OBIDMS_column_group_p obi_create_column_group(OBIDMS_p dms, const char* column_name);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Opens an existing OBIDMS column group 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 group structure describing the group
|
||
|
|
* @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_group()
|
||
|
|
* @since June 2015
|
||
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
||
|
|
*/
|
||
|
|
OBIDMS_column_group_p obi_open_column_group(OBIDMS_p dms, const char* column_name);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Opens or creates a new OBIDMS column group instance.
|
||
|
|
*
|
||
|
|
* If the group already exists, this function opens it, otherwise it
|
||
|
|
* creates a new column group.
|
||
|
|
*
|
||
|
|
* @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 group structure describing the group
|
||
|
|
* @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_group_p obi_column_group(OBIDMS_p dms, const char* column_name);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Closes an opened OBIDMS column group instance.
|
||
|
|
*
|
||
|
|
* @param column_group a pointer to an OBIDMS column group as returned by
|
||
|
|
* obi_create_column_group() or obi_open_column_group()
|
||
|
|
*
|
||
|
|
* @return an integer value indicating the success of the operation. Even on
|
||
|
|
* error, the `OBIDMS_column_group` structure is freed
|
||
|
|
* @retvalue 0 on success
|
||
|
|
* @retvalue -1 on failure and the `obi_errno` variable is set.
|
||
|
|
*
|
||
|
|
* @see obi_create_column_group()
|
||
|
|
* @see obi_open_column_group()
|
||
|
|
* @since June 2015
|
||
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
||
|
|
*/
|
||
|
|
int obi_close_column_group(OBIDMS_column_group_p column_group);
|
||
|
|
|
||
|
|
|
||
|
|
#endif /* OBIDMSCOLUMNDIR_H_ */
|