obitools/obitools3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 66 Wiki Activity

Doxygen documentation corrected and completed.

Browse Source
This commit is contained in:
Celine Mercier
2015-09-30 12:03:46 +02:00
parent 45af8396b8
commit 4b7f2d268b
25 changed files with 670 additions and 689 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
src/obidms.h
View File

@ -1,13 +1,19 @@
/*
* obidms.h
*
* Created on: 23 mai 2015
* Author: coissac
/********************************************************************
* OBIDMS header file *
********************************************************************/
/**
* @file obidmscolumn.h
* @author Eric Coissac (eric.coissac@metabarcoding.org)
* @date 23 May 2015
* @brief Header file for the OBIDMS functions and structures.
*/
#ifndef OBIDMS_H_
#define OBIDMS_H_
#include <stdlib.h>
#include <sys/stat.h>
#include <errno.h>
@ -17,38 +23,37 @@
#include "obierrno.h"
#define OBIDMS_MAX_NAME (2048) /**< The maximum length of an OBIDMS name
*/
/** @brief A structure describing an OBIDMS instance
/**
* @brief A structure describing an OBIDMS instance
*
* A pointer to this structure is returned on creation
* and opening of an OBITools Data Management System (DMS)
*/
typedef struct OBIDMS {
char directory_name[OBIDMS_MAX_NAME+1]; /**< The name of the directory
* containing the DMS
* containing the DMS.
*/
DIR* directory; /**< A directory entry usable to
* refer and scan the database directory
* refer and scan the database directory.
*/
} OBIDMS_t, *OBIDMS_p;
/*@
* @brief Checks if an OBIDMS exists
/**
* @brief Checks if an OBIDMS exists.
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<dms_name>.obidms`.
* @param dms_name A pointer to a C string containing the name of the database.
*
* @return an integer value indicating the status of the database
* @retvalue 1 the database exist
* @retvalue 0 the database does not exist
* @retvalue -1 an error occurred
* @returns An integer value indicating the status of the database
* @retval 1 if the database exists.
* @retval 0 if the database does not exist.
* @retval -1 if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
@ -62,79 +67,62 @@ int obi_dms_exists(const char* dms_name);
* if a directory with this name does not already exist
* before creating the new database.
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<name>.obidms`
* @param dms_name A pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<dms_name>.obidms`.
*
* @return a pointer to an OBIDMS structure describing the newly created DMS
* @retval NULL on error and the `obi_errno` variable is set.
*
* ###Error values
* - OBIDMS_EXIST_ERROR : a database with the same name already exists.
* - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit.
* - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation.
* @returns A pointer to an OBIDMS structure describing the newly created DMS.
* @retval NULL if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
OBIDMS_p obi_create_dms(const char *dms_name);
OBIDMS_p obi_create_dms(const char* dms_name);
/**
* @brief Opens an existing OBITools Data Management instance (OBIDMS).
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<name>.obidms`
* @param dms_name A pointer to a C string containing the name of the database.
*
* @return a pointer to an OBIDMS structure describing the newly created DMS
* @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.
* @returns A pointer to an OBIDMS structure describing the opened DMS.
* @retval NULL if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
OBIDMS_p obi_open_dms(const char *dms_name);
OBIDMS_p obi_open_dms(const char* dms_name);
/**
* @brief Creates a new OBIDMS instance.
* @brief Creates or opens a new OBIDMS instance.
*
* If the database already exists, this function opens it, otherwise it
* creates a new database.
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS is
* `<name>.obidms`
* @param dms_name A pointer to a C string containing the name of the database.
*
* @return a pointer to an OBIDMS structure describing the newly created DMS
* @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.
* @returns A pointer to an OBIDMS structure describing the OBIDMS.
* @retval NULL if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
OBIDMS_p obi_dms(const char *dms_name);
OBIDMS_p obi_dms(const char* dms_name);
/**
* @brief Closes an opened OBITools Data Management instance (OBIDMS).
*
* @param dms a pointer as returned by obi_create_dms() or obi_open_dms()
* @param dms A pointer as returned by obi_create_dms() or obi_open_dms().
*
* @return an integer value indicating the success of the operation. Even on
* error, the `OBIDMS` structure is freed
* @retvalue 0 on success
* @retvalue -1 on failure and the `obi_errno` variable is set.
* @returns An integer value indicating the success of the operation. Even on
* error, the `OBIDMS` structure is freed.
* @retval 0 on success.
* @retval -1 if an error occurred?-.
*
* @see obi_create_dms()
* @see obi_open_dms()