obidmscolumndir.h 5.83 KB
Newer Older
1 2 3 4 5
/****************************************************************************
 * OBIDMS column directories header file                                    *
 ****************************************************************************/

/**
6
 * @file obidmscolumndir.h
7 8
 * @author Celine Mercier
 * @date 18 June 2015
9
 * @brief Header file for OBIDMS column directories.
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
 */

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

27
/** @brief A structure describing an OBIDMS column directory instance
28 29
 *
 * A pointer to this structure is returned on creation
30
 * and opening of an OBIDMS column directory.
31 32
 */

33
typedef struct OBIDMS_column_directory {
34 35
	OBIDMS_p	dms;	 										/**< A pointer to a DMS instance.
     	 	 	 	 	 	 	 	 	 	 	 	 		 	 */
36
	char 		column_name[OBIDMS_MAX_COLNAME+1];				/**< The name of the column
37 38 39
																 *   contained in the directory.
																 */
	char		directory_name[OBIDMS_COLUMN_DIR_MAX_NAME+1];	/**< The name of the directory
40
	                                     	 	 	 	 	 	 *   containing the column.
41 42 43 44
	                                     	 	 	 	 	 	 */
	DIR*		directory;										/**< A directory entry usable to
										 	 	 	 	 	 	 *   refer and scan the database directory.
										 	 	 	 	 	 	 */
45
} OBIDMS_column_directory_t, *OBIDMS_column_directory_p;
46 47 48


/*@
49
 * @brief Checks if an OBIDMS column directory exists
50 51 52 53 54 55
 *
 * @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`.
 *
56 57 58
 * @return an integer value indicating the status of the column directory
 * @retvalue 1 the directory exist
 * @retvalue 0 the directory does not exist
59 60
 * @retvalue -1 an error occurred
 *
61
 * @see obi_close_column_directory()
62 63 64
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
65
int obi_column_directory_exists(OBIDMS_p dms, const char* column_name);
66 67 68


/**
69
 * @brief Creates a new OBIDMS column directory instance.
70
 *
71
 * A new OBIDMS column directory is created. This function checks
72
 * if a directory with this name does not already exist
73
 * before creating the new column directory.
74 75 76 77 78 79
 *
 * @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`.
 *
80 81
 * @return a pointer to an OBIDMS column directory structure describing the newly created
 * 		   directory
82 83 84 85 86
 * @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.
 *
87
 * @see obi_close_column_directory()
88 89 90
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
91
OBIDMS_column_directory_p obi_create_column_directory(OBIDMS_p dms, const char* column_name);
92 93 94


/**
95
 * @brief Opens an existing OBIDMS column directory instance.
96 97 98 99 100 101
 *
 * @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`.
 *
102
 * @return a pointer to the OBIDMS column directory structure describing the directory
103 104 105 106 107
 * @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.
 *
108
 * @see obi_close_column_directory()
109 110 111
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
112
OBIDMS_column_directory_p obi_open_column_directory(OBIDMS_p dms, const char* column_name);
113 114 115


/**
116
 * @brief Opens or creates a new OBIDMS column directory instance.
117
 *
118 119
 * If the directory already exists, this function opens it, otherwise it
 * creates a new column directory.
120 121 122 123 124 125
 *
 * @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`.
 *
126
 * @return a pointer to the OBIDMS column directory structure describing the directory
127 128 129 130 131 132 133 134 135
 * @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)
 */
136
OBIDMS_column_directory_p obi_column_directory(OBIDMS_p dms, const char* column_name);
137 138 139


/**
140
 * @brief Closes an opened OBIDMS column directory instance.
141
 *
142 143
 * @param column_directory a pointer to an OBIDMS column directory as returned by
 * obi_create_column_directory() or obi_open_column_directory()
144 145
 *
 * @return an integer value indicating the success of the operation. Even on
146
 * 		   error, the `OBIDMS_column_directory` structure is freed
147 148 149
 * @retvalue 0 on success
 * @retvalue -1 on failure and the `obi_errno` variable is set.
 *
150 151
 * @see obi_create_column_directory()
 * @see obi_open_column_directory()
152 153 154
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
155
int obi_close_column_directory(OBIDMS_column_directory_p column_directory);
156 157 158


#endif /* OBIDMSCOLUMNDIR_H_ */