Archivo Tipo 2 Documentado para Doxygen.

diff --git a/emufs/tipo2.c b/emufs/tipo2.c
index bf59bf0febc34250a5a5d0a8ca2f5904280be860..2380249a4125a33b157221cdd23d32228c873f18 100644 (file)
--- a/emufs/tipo2.c
+++ b/emufs/tipo2.c
@@ -26,10 +26,16 @@
  *
  */
 
  *
  */
 

-/***************************************************************/
-/* Implementación del Tipo Archivo 2: Registros Variables, Sin */
-/* Bloques at all.                                             */
-/***************************************************************/
+/** \file
+ * Archivo con registros de longitud variable, sin bloques.
+ *
+ * <b>Implementacion del Archivo Tipo 2</b>
+ *
+ * La organizacion interna de un archivo de tipo 2, presenta registros de longitud variable,
+ * los cuales son grabados secuencialmente, o bien en gaps (espacios libres) que se presenten en
+ * el archivo de datos, pero no se encuentran contenidos por bloques.
+ *
+ */

 
 #include "tipo2.h"
 #include "idx.h"
 
 #include "tipo2.h"
 #include "idx.h"


@@ -46,17 +52,8 @@ int emufs_tipo2_inicializar(EMUFS* efs)
        return 0;
 }
 
        return 0;
 }
 

-/**********************************************************************/
-/* void *emufs_tipo2_leer_registro(EMUFS* efs, EMUFS_REG_ID reg_id,   */
-/*                     EMUFS_REG_SIZE* reg_size, int *err)                        */
-/* Objetivo: Lee un registro de un archivo del Tipo 2.                */
-/* Parametros: EMUFS *efs // Struct con handlers + info del openfile. */
-/*             EMUFS_REG_ID reg_id // Id del registro a cargar        */
-/*             EMUFS_REG_SIZE *reg_size // Size del reg en cuestion   */
-/*             int *err // Indicador de errores                       */
-/**********************************************************************/
-void *emufs_tipo2_leer_registro(EMUFS* efs, EMUFS_REG_ID reg_id,
-                       EMUFS_REG_SIZE* reg_size, int *err)
+/* Lee y devuelve un registro de un archivo del Tipo 2. */
+void *emufs_tipo2_leer_registro(EMUFS* efs, EMUFS_REG_ID id_reg, EMUFS_REG_SIZE* reg_size, int *err)

 {
        FILE* f_data;
        char *registro; /* registro a leer */
 {
        FILE* f_data;
        char *registro; /* registro a leer */


@@ -67,7 +64,7 @@ void *emufs_tipo2_leer_registro(EMUFS* efs, EMUFS_REG_ID reg_id,
        strcat(name_f,".dat");
 
        /* Obtenemos la posicion del registro en el .dat */
        strcat(name_f,".dat");
 
        /* Obtenemos la posicion del registro en el .dat */

-       reg_offset = emufs_idx_buscar_registro(efs, reg_id);
+       reg_offset = emufs_idx_buscar_registro(efs, id_reg);

        if (reg_offset == EMUFS_NOT_FOUND) {
                /* TODO Manejo de errores */
                PERR("Registro no encontrado");
        if (reg_offset == EMUFS_NOT_FOUND) {
                /* TODO Manejo de errores */
                PERR("Registro no encontrado");


@@ -90,14 +87,7 @@ void *emufs_tipo2_leer_registro(EMUFS* efs, EMUFS_REG_ID reg_id,
        return registro;
 }
 
        return registro;
 }
 

-/**********************************************************************/
-/* EMUFS_REG_ID emufs_tipo2_grabar_registro(EMUFS *efs, void *ptr,    */
-/*                                 EMUFS_REG_SIZE n_RegSize)          */
-/* Objetivo: Grabar un registro en un archivo del Tipo 2.             */
-/* Parametros: EMUFS *efs // Struct con handlers + info del openfile. */
-/*             void *ptr // Puntero al buffer (registro) a guardar    */
-/*             EMUFS_REG_SIZE n_RegSize // Size del reg en cuestion   */
-/**********************************************************************/
+/* Grabar un registro en un archivo del Tipo 2. */

 EMUFS_REG_ID emufs_tipo2_grabar_registro(EMUFS *efs, void *ptr, EMUFS_REG_SIZE reg_size, int* err)
 {
        EMUFS_REG_ID id_reg;
 EMUFS_REG_ID emufs_tipo2_grabar_registro(EMUFS *efs, void *ptr, EMUFS_REG_SIZE reg_size, int* err)
 {
        EMUFS_REG_ID id_reg;


@@ -163,13 +153,7 @@ EMUFS_REG_ID emufs_tipo2_grabar_registro(EMUFS *efs, void *ptr, EMUFS_REG_SIZE r
        return id_reg;
 }
 
        return id_reg;
 }
 

-/**********************************************************************/
-/* int emufs_tipo2_borrar_registro(EMUFS *efs, EMUFS_REG_ID n_IdReg)  */
-/* Objetivo: Borra un registro determinado y actualiza los archivos   */
-/*           de Posicion Relativa (Indice-Offset) y el de Gaps        */
-/* Parametros: EMUFS *efs // Struct con handlers + info del openfile. */
-/*             EMUFS_REG_ID n_IdReg // Id del registro a eliminar.    */
-/**********************************************************************/
+/* Borra un registro determinado y actualiza los archivos de Posicion Relativa (Indice-Offset) y el de Gaps */

 int emufs_tipo2_borrar_registro(EMUFS *efs, EMUFS_REG_ID id_reg)
 {      
        EMUFS_OFFSET reg_offset,reg_size;
 int emufs_tipo2_borrar_registro(EMUFS *efs, EMUFS_REG_ID id_reg)
 {      
        EMUFS_OFFSET reg_offset,reg_size;


@@ -198,14 +182,7 @@ int emufs_tipo2_borrar_registro(EMUFS *efs, EMUFS_REG_ID id_reg)
        return(0);
 }
 
        return(0);
 }
 

-/**********************************************************************/
-/* int emufs_tipo2_get_regsize(EMUFS *efs, EMUFS_OFFSET n_RegPos,     */
-/*                             EMUFS_REG_SIZE *n_RegSize)             */
-/* Objetivo: Devuelve el tamanio de un registro, dado su init offset  */
-/* Parametros: EMUFS *efs // Struct con handlers + info del openfile. */
-/*             EMUFS_OFFSET n_RegPos // Offset al inicio del registro */
-/*             EMUFS_REG_SIZE *n_RegSize // Size to lookup and return */
-/**********************************************************************/
+/* Devuelve el tamanio de un registro, dado su init offset */

 int emufs_tipo2_get_regsize(EMUFS *efs, EMUFS_OFFSET reg_pos, EMUFS_REG_SIZE *reg_size)
 {
     FILE *f_data;
 int emufs_tipo2_get_regsize(EMUFS *efs, EMUFS_OFFSET reg_pos, EMUFS_REG_SIZE *reg_size)
 {
     FILE *f_data;


@@ -223,15 +200,8 @@ int emufs_tipo2_get_regsize(EMUFS *efs, EMUFS_OFFSET reg_pos, EMUFS_REG_SIZE *re
        return (0);
 }
 
        return (0);
 }
 

-/**********************************************************************/
-/* int emufs_tipo2_dummyfill(EMUFS *efs, EMUFS_OFFSET n_RegPos,       */
-/*                           EMUFS_REG_SIZE n_Amount                  */
-/* Objetivo: Pisa con basura lo que es hasta el momento un reg en     */
-/*           el disco para indicar su borrado (Debug Purposes Only).  */
-/* Parametros: EMUFS *efs // Struct con handlers + info del openfile. */
-/*             EMUFS_OFFSET n_RegPos // Offset al inicio del registro */
-/*             EMUFS_REG_SIZE *n_Amount // Size to lookup and return  */
-/**********************************************************************/
+
+/* Pisa con basura lo que es hasta el momento un reg en el disco para indicar su borrado (Debug Purposes Only) */

 int emufs_tipo2_dummyfill(EMUFS *efs, EMUFS_OFFSET reg_pos, EMUFS_REG_SIZE amount)
 {
     FILE *f_data;
 int emufs_tipo2_dummyfill(EMUFS *efs, EMUFS_OFFSET reg_pos, EMUFS_REG_SIZE amount)
 {
     FILE *f_data;

diff --git a/emufs/tipo2.h b/emufs/tipo2.h
index f36aea2e0486798a18dafdb09782bde1a6018959..e663b7d3b17709bee0b5d437a10e7a71ac9e6f63 100644 (file)
--- a/emufs/tipo2.h
+++ b/emufs/tipo2.h
@@ -23,11 +23,34 @@
  *----------------------------------------------------------------------------
  */
 
  *----------------------------------------------------------------------------
  */
 

-/***************************************************************/
-/* Implementación del Tipo Archivo 2: Registros Variables, Sin */
-/* Bloques at all.                                             */
-/***************************************************************/
-
+/** \file
+ * Archivo con registros de longitud variable, sin bloques.
+ *
+ * <b>Interfaz del Archivo Tipo 2</b>
+ *
+ * La organizacion interna de un archivo de tipo 2, presenta registros de longitud variable,
+ * los cuales son grabados secuencialmente, o bien en gaps (espacios libres) que se presenten en
+ * el archivo de datos, pero no se encuentran contenidos por bloques.
+ *
+ * <b>Estructura Interna</b>: Un registro de este tipo, en disco, sera grabado de la siguiente forma:
+ *
+ * [ id_reg ][ reg_size ][ ///// reg_data ///// ]
+ * 
+ *
+ * \li EMUFS_REG_ID \c id_reg Id del registro
+ * \li EMUFS_REG_SIZE \c reg_size Size del registro
+ * \li char* \c reg_data Datos concretos del registro
+ *
+ * <b>Archivos Auxiliares:</b>
+  * Tendra tres archivos auxiliares que actuaran de Indice para localizar los registros,
+ * Indice de GAPS o FreeSpace y por ultimo Indice de ID's Libres (al borrarse regs se liberan ids).
+ *
+ * \li \c .FSC -- Indice de Gaps o Espacios Libres en el .DAT
+ * \li \c .IDX -- Indice de Posiciones Relativas u Offsets de los registros en el .DAT
+ * \li \c .DID -- Indice de Id's Libres para reutilizacion
+ *
+ */
+ 

 #ifndef _EMUFS_TIPO2_H_
 #define _EMUFS_TIPO2_H_
 
 #ifndef _EMUFS_TIPO2_H_
 #define _EMUFS_TIPO2_H_
 


@@ -37,11 +60,60 @@
 #include <unistd.h>
 #include "emufs.h"
 
 #include <unistd.h>
 #include "emufs.h"
 

-int emufs_tipo2_inicializar(EMUFS*);
-void *emufs_tipo2_leer_registro(EMUFS* , EMUFS_REG_ID , EMUFS_REG_SIZE *, int *);
-EMUFS_REG_ID emufs_tipo2_grabar_registro(EMUFS *, void *, EMUFS_REG_SIZE, int *);
-int emufs_tipo2_borrar_registro(EMUFS*, EMUFS_REG_ID);
-int emufs_tipo2_get_regsize(EMUFS *, EMUFS_OFFSET n_RegPos,EMUFS_REG_SIZE *);
-int emufs_tipo2_dummyfill(EMUFS *, EMUFS_OFFSET n_RegPos,EMUFS_REG_SIZE n_Amount);
+/** Inicializa la estructura <em>EMUFS* efs</em> que recibe, asignando las funciones que permiten
+ * el uso del archivo tipo 2.
+ *
+ * \param efs Estructura que realiza el handling de archivos de cualquier tipo.
+ * \return \b int Indicador de exito de la operacion.
+ */
+int emufs_tipo2_inicializar(EMUFS* efs);
+
+/** Realiza la lectura de un registro en archivos del tipo 2 en base a su \em ID, devolviendo ademas el \em Size del
+ * registro leido.
+ *
+ * \param efs Estructura que realiza el handling de archivos de cualquier tipo.
+ * \param id_reg Id del registro a leer del archivo de datos.
+ * \param reg_size Size del registro leido que es devuelto a la funcion invocante.
+ * \param err Indicador de error en la operacion.
+ * \return \b void* Buffer con el registro leido.
+ */
+void *emufs_tipo2_leer_registro(EMUFS* efs, EMUFS_REG_ID id_reg, EMUFS_REG_SIZE* reg_size, int *err);
+
+/** Realiza la escritura de un registro en archivos del tipo 2 en base a su \em ID, devolviendo ademas el \em Size del
+ * registro leido.
+ *
+ * \param efs Estructura que realiza el handling de archivos de cualquier tipo.
+ * \param ptr Puntero a la region de memoria que contiene el registro a grabar.
+ * \param reg_size Size del registro a grabar en disco.
+  * \param err Indicador de error en la operacion.
+ * \return \b EMUFS_REG_ID Id del registro que fue grabado.
+ */
+EMUFS_REG_ID emufs_tipo2_grabar_registro(EMUFS *efs, void *ptr, EMUFS_REG_SIZE reg_size, int* err);
+
+/** Realiza el borrado de un registro en archivos del tipo 2 en base a su \em ID.
+ *
+ * \param efs Estructura que realiza el handling de archivos de cualquier tipo.
+ * \param id_reg Id del registro que se quiere eliminar.
+ * \return \b int Indicador de exito de la operacion.
+ */
+int emufs_tipo2_borrar_registro(EMUFS *efs, EMUFS_REG_ID id_reg);
+
+/** Devuelve el \em Size de un registro dado, en base a su \em ID.
+ *
+ * \param efs Estructura que realiza el handling de archivos de cualquier tipo.
+ * \param reg_pos Id del registro.
+ * \param reg_size Size del registro que se devuelve a la funcion invocante.
+ * \return \b int Indicador de exito de la operacion.
+ */
+int emufs_tipo2_get_regsize(EMUFS *efs, EMUFS_OFFSET reg_pos, EMUFS_REG_SIZE *reg_size);
+
+/** Realiza un fill con basura de una region dada dentro de un .dat del tipo2.
+ *
+ * \param efs Estructura que realiza el handling de archivos de cualquier tipo.
+ * \param reg_pos Offset donde comenzar el fill con basura.
+ * \param amount Cantidad de bytes a escribir en la region indicada.
+ * \return \b int Indicador de exito de la operacion.
+ */
+int emufs_tipo2_dummyfill(EMUFS *efs, EMUFS_OFFSET reg_pos, EMUFS_REG_SIZE amount);

 
 #endif /* _EMUFS_TIPO2_H_ */
 
 #endif /* _EMUFS_TIPO2_H_ */