obitools3/src/obidmscolumn.h

/****************************************************************************
 * OBIDMSColumn header file                                                    *
 ****************************************************************************/

/**
 * @file obidmscolumn.h
 * @author Celine Mercier
 * @date 12 May 2015
 * @brief Header file for the shared elements of all the OBIColumn structures.
 */

#ifndef OBIDMSCOLUMN_H_
#define OBIDMSCOLUMN_H_

#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdbool.h>
#include <time.h>

#include <obidms.h>
#include <obitypes.h>
#include <obierrno.h>
#include <obilittlebigman.h>

/**
 * @brief Value separator in OBIDMSColumn files.
 */
static const char SEPARATOR = '\n';


/**
 * @brief Header size in OBIDMSColumn files.
 */
static const int HEADER_SIZE = 4096;


/**
 * @brief Number of bytes to map
 */
static const int BUFFER_SIZE = 4;

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

typedef int32_t obiversion_t; 	/**< Used to store the column version number
                                 */

/**
 * @brief OBIColumnHeader structure.
 */

typedef struct OBIDMSColumnHeader {
	bool			little_endian;		    /**< endianess of the column:
													- `true`  on little endian platform
													- `false` on big endian platform

												@see obi_is_little_end()
	 	 	 	 	 	 	 	 	 	 	 */
	int				header_size;		    /**< size of the header in bytes */
	size_t			line_count;				/**< number of lines of data */
	size_t			line_used;				/**< number of lines of data used*/
	OBIType_t		data_type;				/**< type of the data */
	time_t			creation_date;			/**< date of creation of the file */
	obiversion_t	version;				/**< version of the OBIColumn */
	char            name[OBIDMS_MAX_COLNAME]; /**< The column name as a NULL
	                                           *   terminated string.
	                                           */
	char 			comments[1];				/**< comments stored as a classical
												 zero end C string. T
												 The size of the comment is just limited
												 by the header size
	 	 	 	 	 	 	 	 	 	 	 */
} OBIDMSColumnHeader_t, *OBIDMSColumnHeader_p;

/**
 * @brief Structure describing a Column of the OBITools DMS
 *
 * A data structure of this type is returned by the functions
 * creating, opening or cloning an OBIDMSColumn.
 */
typedef struct OBIDMSColumn {
	OBIDMS_p                dms   ; /**< A pointer to a DMS instance
	                                 */
	OBIDMSColumnHeader_p	header; /**< A pointer to the header of the column
	                                 */
	void*                   data;   /**< A `void` pointer to the beginning of the
	                                 *   data.
	                                 *
	                                 *   @attention never use this member directly
	                                 *              outside of the code of the
	                                 *              low level functions
	                                 *              of the OBITools DMS
	                                 */
	bool					writable;/**< Indicates if the column is writable or not.
	                                  *       - `true` the column is writable
	                                  *       - `false` the column is read-only
	                                  *
	                                  * A column is writable only by its creator
	                                  * until he closes it.
	                                  */
} OBIDMSColumn_t, *OBIDMSColumn_p;

/**
 * @brief Return the header size in bytes of a column on this platform.
 *
 * Header size is defined as a multiple of the memory page size.
 * Up to now the header size is defined as one time the page size
 *
 * @return a `size_t` value corresponding to the header size in bytes
 *
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */
size_t obi_get_platform_header_size();



/**
 * @brief Create a column.
 *
 * @param dms a pointer as returned by obi_create_dms() or obi_open_dms()
 * @param name the name of the new column
 * @param type the OBIType code used to create the column
 * @param nbelement the number of element to be stored
 *
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */

OBIDMSColumn_p obi_create_column(OBIDMS_p dms,
								 char* name,
								 OBIType_t type,
								 size_t nbelement);


/**
 * @brief Return the latest column version in the `dms` database
 *
 * @param dms a pointer as returned by obi_create_dms() or obi_open_dms()
 * @param name the name of the column
 *
 * @return the bigger version number used for this column
 * @return -1 if the column does not exist
 */
obiversion_t obi_latest_version(OBIDMS_p dms,char *name);

char* obi_map_read_only(int file, int start, int size);

void obi_unmap(int size);


#endif /* OBIDMSCOLUMN_H_ */