[[PageOutline(2-5,Índice)]]

= API de funciones =

== Introducción ==

Para el desarrollo de la interfaz de programación del proyecto deben seguirse estas reglas de estilo:

 * Las reglas de la API se cumplirán independientemente del lenguaje de programación utilizado.
 * La documentación del código debe se r compatible con [http://www.stack.nl/~dimitri/doxygen/ Doxygen].
 * Debe incluirse toda la información necesaria en las cabeceras de las funciones (descripción, formato, salidas, notas, etc.).
 * Deben incluirse comentarios descriptivos en los bloques de código.
 * Las funciones devolverán un código de salida al estilo Unix, que indique si se ha ejecutado correctamente o se ha producido alguno de los tipos de errores definidos. En caso de error, también mostrará el mensaje correspondiente.
 * Todos los nombres de funciones y variables deben estar escritos en inglés, deben ser descriptivos y fáciles de recordar.
 * Nombres de funciones al estilo Rembo-C (sólo con las iniciales en mayúsculas), pero sin copiarlos de Rembo-C. Según se estime oportuno, los nombres de funciones podrán tener un prefijo indicativo del proyecto o del componente del proyecto al que pertenece.
 * Las constantes y variables globales deben ir escritas en mayúsculas.

== Variables y constantes globales ==

||''Constantes'' ||''Valor por defecto''              ||''Descripción''                                   ||
||{{{OPENGNSYS}}}||{{{/opt/opengnsys}}}               ||Directorio principal de complementos del OpenGnSys||
||{{{OGBIN}}}    ||{{{/opt/opengnsys/bin}}}           ||Directorio de ficheros ejecutables                ||
||{{{OGETC}}}    ||{{{/opt/opengnsys/etc}}}           ||Directorio de ficheros de configuración           ||
||{{{OGLIB}}}    ||{{{/opt/opengnsys/lib}}}           ||Directorio de librerías de programas              ||
||{{{OGAPI}}}    ||{{{/opt/opengnsys/lib/engine/bin}}}||Directorio de librerías del motor de clonación    ||
||{{{OGIMG}}}    ||{{{/opt/opengnsys/images}}}        ||Directorio del repositorio remoto de imágenes     ||
||{{{OGCAC}}}    ||{{{/opt/opengnsys/cache}}}         ||Directorio de la caché local del cliente          ||
||{{{OGLOG}}}    ||{{{/opt/opengnsys/log}}}           ||Directorio del registro de incidencias            ||


== Parámetros ==

Los parámetros de las funciones deben estar unificados, ésto es, deben ser comprensibles según su tipo y su contexto.

Tipos de parámetros:
 * Disco: identificado por su número de orden.
 * Partición: número de orden de la partición.
   * Identificador de partición: dupla de valores formada por disco y partición (2 parámetros).
 * Sistema de archivos: mnemónico predefinido identificador del tipo de sistema de archivos.
 * Tamaño: número entero con el tamaño de la partición en KB.
   * Definición de partición: pareja de valores formada por sistema de archivos y tamaño, separados por ":" (1 parámetro compuesto).
 * Repositorio: dirección IP del repositorio de imágenes.
 * Caché local: dirección IP del cliente local o {{{localhost}}}
 * Camino: camino de un fichero relativo a su partición, a su repositorio o su caché local.
   * Camino completo: parámetro compuesto por identificador de partición o repositorio y el camino relativo de un fichero (2 o 3 parámetros).
 * Fichero de imagen: ...
 * ...


=== Mnemónicos de tipos de particiones y sistemas de archivos ===

||Identificador||Mnemónico ||Tipo de partición||
||00           ||EMPTY     ||Partición vacía no definida||
||01           ||FAT12     ||FAT12||
||05           ||EXTENDED  ||Partición extendida que puede contener varias particiones lógicas||
||06, 0e       ||FAT16     ||FAT16||
||07           ||NTFS, EXFAT||NTFS o FAT64 (exFAT)||
||0b, 0c       ||FAT32     ||FAT32||
||11           ||HFAT12    ||FAT12 oculta||
||16, 1e       ||HFAT16    ||FAT16 oculta||
||17           ||HNTFS     ||NTFS oculta||
||1b, 1c       ||HFAT32    ||FAT32 oculta||
||82           ||LINUX-SWAP||Paginación para Linux (''swap'')||
||83           ||EXT2, EXT3, EXT4, REISERFS, REISER4, JFS, XFS||Sistemas operativos disponibles para una partición Linux||
||8e           ||LINUX-LVM ||Partición de volumen lógico para Linux||
||bf           ||SOLARIS   ||Sistemas operativos UFS, ZFS para Solaris||
||ca           ||CACHE     ||Caché local de OpenGNSys Client (se formateará como Ext3)||.
||fd           ||LINUX-RAID||Partición RAID para Linux||
||-            ||UNKNOWN   ||Tipo de partición desconocido.||


=== Mnemónicos de tipos de dispositivos ===

||Mnemónico||Tipo de ''hardware''||
||mod      ||Marca y modelo del equipo||
||boa      ||Placa base||
||bio      ||Modelo y versión de la BIOS||
||cpu      ||Modelo y velocidad del procesador||
||mem      ||Tamaño de la memoria||
||vga      ||Tarjeta gráfica||
||net      ||Tarjeta de red||
||mul      ||Tarjeta de sonido o muldimedia||
||ide      ||Controladora de discos IDE ATA/SATA|| 
||dis      ||Modelo y capacidad del disco duro||
||cdr      ||Modelo de lectora o grabadora de CD/DVD||
||usb      ||Dispositivo USB||
||fir      ||Dispositivo !FireWire||
||bus      ||Bus interno de gestión|| 



== Errores y mensajes ==

Las funciones deben realizar una comprobación y un tratamiento adecuados de posibles errores y fallos, evitando realizar operaciones innecesarias o incorrectas. Se generarán mensajes de error comprensibles y adecuados que ofrezcan información para detectar y corregir el problema, además de devolver un código de error que pueda ser tratado por otras funciones de la API.

Asimismo, se deben presentar mensajes informativos normalizados sobre el estado y la evolución de las operaciones realizadas.

La implementación de las funciones de la API tendrá en cuenta técnicas de internacionalización, para poder presentar los mensajes y los errores en el idioma del usuario.

=== Lista de errores definidos ===

||''Código''|| ''Mnemónico''        || ''Descripción''                            ||
||     1    ||{{{OG_ERR_FORMAT}}}   ||Formato de ejecución incorrecto             ||
||     2    ||{{{OG_ERR_NOTFOUND}}} ||Fichero o dispositivo no encontrado         ||
||     3    ||{{{OG_ERR_PARTITION}}}||Partición no reconocida o no se puede montar||
||     4    ||{{{OG_ERR_LOCKED}}}   ||Partición o fichero bloqueado               ||
||     5    ||{{{OG_ERR_IMAGE}}}    ||Error al crear o restaurar una imagen       ||
||     6    ||{{{OG_ERR_NOTOS}}}    ||Sin sistema operativo                       ||
||     7    ||{{{OG_ERR_NOTEXEC}}}  ||Programa o función no ejecutable            ||


== Funciones del motor de clonación ==

Las funciones de la API se agrupan lógicamente en librerías o clases (según el lenguaje de programación utilizado), con unas características comunes.

Lista de librerías o clases (en orden alfabético):
 * [doxygen:Boot_8lib.html Boot] - funciones de postconfiguración y arranque de sistemas de archivos
 * [doxygen:Cache_8lib.html Cache] - funciones de tratamiento de la caché local ''(a partir de la versión 0.91)''
 * [doxygen:Disk_8lib.html Disk] - funciones de gestión de discos
 * [doxygen:File_8lib.html File] - funciones de control de ficheros y directorios
 * [doxygen:FileSystem_8lib.html FileSystem] - funciones de administración de sistemas de archivos
 * [doxygen:Image_8lib.html Image] - funciones de creación y clonación de imágenes de sistemas de archivos
 * [doxygen:Inventory_8lib.html Inventory] - funciones de inventario de clientes
 * [doxygen:Net_8lib.html Net] - funciones de control de conexión de red
 * [doxygen:System_8lib.html System] - funciones básicas del sistema

''(lista de funciones para clonar "a mano" o desde scripts)''


== Funciones del gestor web ==

''(lista de funciones ejecutadas por el gestor web)''