obidmscolumndir.h 5.94 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 the OBIDMS column directories structures and functions.
10 11
 */

12

13 14 15
#ifndef OBIDMSCOLUMNGROUP_H_
#define OBIDMSCOLUMNGROUP_H_

16

17 18 19 20 21 22 23
#include <stdlib.h>
#include <stdio.h>
#include <dirent.h>

#include "obidms.h"


24
#define OBIDMS_COLUMN_MAX_NAME (1024) /**< The maximum length of an OBIDMS column name.
25 26
                                       */

27

28 29
/**
 * @brief A structure describing an OBIDMS column directory instance.
30 31
 *
 * A pointer to this structure is returned on creation
32
 * and opening of an OBIDMS column directory.
33
 */
34
typedef struct OBIDMS_column_directory {
35
	OBIDMS_p	dms;	 										 /**< A pointer to a DMS instance.
36
     	 	 	 	 	 	 	 	 	 	 	 	 		 	  */
37
	char 		column_name[OBIDMS_COLUMN_MAX_NAME+1];		     /**< The name of the column
38 39
																  *    contained in the directory.
																  */
40
	char		directory_name[OBIDMS_COLUMN_MAX_NAME+1];	     /**< The name of the directory
41 42
	                                     	 	 	 	 	 	  *    containing the column.
	                                     	 	 	 	 	 	  */
43
	DIR*		directory;										 /**< A directory entry usable to
44 45 46 47 48
										 	 	 	 	 	 	  *    refer and scan the column directory.
										 	 	 	 	 	 	  */
	int			dir_fd;											 /**< The file descriptor of the directory entry
																  *   usable to refer and scan the column directory.
																  */
49
} OBIDMS_column_directory_t, *OBIDMS_column_directory_p;
50 51


52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
/**
 * Function building the column directory name from an OBIDMS column name.
 *
 * The function builds the directory name corresponding to an OBIDMS column directory.
 * It checks also that the name is not too long.
 *
 * @warning The returned pointer has to be freed by the caller.
 *
 * @param column_name The name of the OBIDMS column.
 *
 * @returns A pointer to the OBIDMS column directory name.
 * @retval NULL if an error occurred.
 *
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_build_column_directory_name(const char* column_name);


71 72
/**
 * @brief Checks if an OBIDMS column directory exists.
73
 *
74 75
 * @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.
76
 *
77 78 79 80
 * @returns An integer value indicating the status of the column directory.
 * @retval 1 if the directory exists.
 * @retval 0 if the directory does not exist.
 * @retval -1 if an error occurred.
81
 *
82
 * @see obi_close_column_directory()
83 84 85
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
86
int obi_column_directory_exists(OBIDMS_p dms, const char* column_name);
87 88 89


/**
90
 * @brief Creates a new OBIDMS column directory instance.
91
 *
92
 * A new OBIDMS column directory is created. This function checks
93
 * if a directory with this name does not already exist
94
 * before creating the new column directory.
95
 *
96 97
 * @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.
98 99 100
 *                    The actual directory name used to store the column will be
 *                    `<column_name>.obicol`.
 *
101 102 103
 * @returns A pointer to an OBIDMS column directory structure describing the newly created
 * 		    directory.
 * @retval NULL if an error occurred.
104
 *
105
 * @see obi_close_column_directory()
106 107 108
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
109
OBIDMS_column_directory_p obi_create_column_directory(OBIDMS_p dms, const char* column_name);
110 111 112


/**
113
 * @brief Opens an existing OBIDMS column directory instance.
114
 *
115 116
 * @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.
117 118 119
 *                    The actual directory name used to store the column is
 *                    `<column_name>.obicol`.
 *
120 121
 * @returns A pointer to the OBIDMS column directory structure describing the directory.
 * @retval NULL if an error occurred.
122
 *
123
 * @see obi_close_column_directory()
124 125 126
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
127
OBIDMS_column_directory_p obi_open_column_directory(OBIDMS_p dms, const char* column_name);
128 129 130


/**
131
 * @brief Opens or creates a new OBIDMS column directory instance.
132
 *
133 134
 * If the directory already exists, this function opens it, otherwise it
 * creates a new column directory.
135
 *
136 137
 * @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.
138 139 140
 *                    The actual directory name used to store the column is
 *                    `<column_name>.obicol`.
 *
141 142
 * @returns A pointer to the OBIDMS column directory structure describing the directory.
 * @retval NULL if an error occurred.
143 144 145 146
 *
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
147
OBIDMS_column_directory_p obi_column_directory(OBIDMS_p dms, const char* column_name);
148 149 150


/**
151
 * @brief Closes an opened OBIDMS column directory instance.
152
 *
153 154
 * @param column_directory A pointer to an OBIDMS column directory as returned by
 *                         obi_create_column_directory() or obi_open_column_directory().
155
 *
156 157 158 159
 * @returns An integer value indicating the success of the operation. Even on
 * 		    error, the `OBIDMS_column_directory` structure is freed.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
160
 *
161 162
 * @see obi_create_column_directory()
 * @see obi_open_column_directory()
163 164 165
 * @since June 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
166
int obi_close_column_directory(OBIDMS_column_directory_p column_directory);
167 168 169


#endif /* OBIDMSCOLUMNDIR_H_ */