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

OPENGNSYS="/opt/opengnsys

export OGBIN=$OPENGNSYS/bin

export OGETC=$OPENGNSYS/etc
export OGLIB=$OPENGNSYS/lib
export OGAPI=$OGLIB/engine/bin
export OGIMG=$OPENGNSYS/images
export OGCAC=$OPENGNSYS/cache -------propuesta 2 ->>>- OGCAC=ogMountCache
export OGLOG=$OPENGNSYS/log

OGCLIENTREGISTERED # Si el cliente está registrado o no en la web

OGCLIENTTYPE # tipo de cliente, iniciado desde "cdrom", "pxeram2, "pxenfs", o desde la misma "cache".

OGIPREPO # IP del repositorio de imagenes asignado al equipo (mcast, torrent)
OGIPADMIN # IP del servidor de administracion (hidra)

CLONETOOLSNTFS # Herramienta de clonación para los sistemas de archivos NTFS.
CLONETOOLSEXT # Herramienta de clonación para los sistemas de archivos EXT2 EXT3 EXT4
CLONETOOLSCOMPRESOR # compresor a utilizar al generar una imagen.
CLONEMEMORYSIZE # Tamaño de memoria RAM para utilizarlo de buffer para las distintas E/S

UNICASTSESSION # informacion de sesión para una conexion unicast. protocolo:usuario:password eje1. smb:user:pass ssh:user:pass nfs

MULTICASTSESSION # informacion de sesión multicas: IP-puerto:NumeroEquipos:TiempoMaximoEspera

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

Parámetros futuras versión

Los actuales sistemas de los que parte OpenGnsys (Hidra, Brutalix, EAC) comparten los parámetros indicados en el apartado anterior. Con dichos parámetros ciertas funcionalidades no podrán ser implementadas, o deben de realizarse de una manera no muy clara. Un ejemplo claro es RestorePartitionFromPartition (EAC), donde ambas particiones pueden ser locales, o pueden ser remotas, es decir un equipo envia por multicast su partión a multiples particiones remotas. Siguiendo en nuevo formato de particiones se podrían unificar tanto RestorePartitionFromPartition? y RestorePartitionFromImage? en una sola:

La sintaxis podría set tal como RecursoOrigen RecursoDestino. Donde cada Recurso estaría compuesto por unos valores que lo identifiquen. De esta manera tendríamos los siguientes recursos simples: (,)

* DISK (disco local)          DISK:int_disk,int_partition
* DISKREMOTE (disco remoto)   DISKREMOTE:str_IP,int_disk,int_partition
* CDROM (cdrom,dvd)           CDROM:
* USB (dispositivos usb)      USB:
* RAM (particiones en ram)    RAM:
* LOOP (dispositivos loop     LOOP:

y los siguientes recursos compuestos: (;)

* FILE (archivo)              FILE//DISK|diskRemote|crdrom|usb|ram|loop|variables$REPO$CACHE;subdirectorio;fichero

Algunos ejemplos:

*RestorePartition Disk:1,1 Disk:1,2 
*RestorePartition DiskRemote:1,2:172.16.72.242 DISK:1,2
*RestorePartition Disk:1,1 File://$GLOBAL:hdimages/curso0809/:xpbase0.lzop1

*UpdateCache File//$GLOBAL:hdimages/curso0809/:xpbase0.lzop1
*RestoreImageToPartition File//$CACHE;hdimages/curso0809/;xpbase0.lzop1  Disk:1,1
*DeployImageToPartition File//$GLOBAL;hdimages/curso0809/;xpbase0.lzop1 Disk:1,1
*CapturePartitionToImage Disk:1,1 File//$GLOBAL;hdimages/curso0809/;xpbase0.lzop

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
• 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
• String - funciones de tratamiento de cadenas de caracteres
• 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)