TOC(heading=Í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 ​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):

• Boot - funciones de postconfiguración y arranque de sistemas de archivos
• Cache - funciones de tratamiento de la caché local (a partir de la versión 0.91)
• Disk - funciones de gestión de discos
• File - funciones de control de ficheros y directorios
• FileSystem - funciones de administración de sistemas de archivos
• Image - funciones de creación y clonación de imágenes de sistemas de archivos
• Inventory - funciones de inventario de clientes
• Net - funciones de control de conexión de red
• 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)