Finalmente se describe el API de pDI-Tools. Esta API permitirá al programador de "backends" realizar desde su código muchas operaciones de pDI-Tools como cargar "backends", instalar interposiciones, gestionar ficheros de comandos, etc.
En este capítulo se subdivide el API en diferentes partes según el fichero de cabecera donde está definida cada función.
Este módulo ofrece un conjunto de herramientas para leer y manipular ficheros de configuración para los "backends", y también para aplicar dicha configuración en el proceso actual. En dichos ficheros se especifican los objetos y funciones sobre los que realizaremos interposiciones de código, y evidentemente, los "backends" y sus funciones de interposición.
Esta API se ofrece para que los "backend", si lo desean, puedan cargar y procesar ficheros de comandos y así instalar configuraciones complejas de interposiciones de un modo casi automático.
Descripción.
Añade un nuevo comando de interposición a la configuración
cfg
.
Parámetros.
cfg
.
Configuración que manipulamos.
type
.
Tipo de comando. Puede tomar los valores
BECFG_IT_RELINK
, BECFG_IT_REDEFINITION
o
BECFG_IT_CALLBACK
.
trgObj
.
Objeto que afectara esta definición (NULL
si se usa un
comodín).
trgFunc
.
Función a la que afectará (o NULL
si comodín).
backend
.
El "backend" encargado de gestionar esta interposición.
wrapper
.
El nombre de la función "wrapper" (o nuevo
"generic wrapper" en caso de ser un "callback") que
gestionará la interposición. NULL
si no se indica
ninguna.
Valor devuelto. 0 en caso de éxito, -1 en caso de error.
Descripción. Añade un nuevo objeto a la lista de objetos en la configuración.
Parámetros.
cfg
.
Configuración que manipulamos.
o_path
.
Ruta al binario.
o_alias
.
Alias que le asignamos.
is_backend
.
Distinto de cero si declaramos un "backend".
Valor devuelto.
Un puntero a la información del nuevo objeto en caso de éxito,
NULL
en caso de error.
Descripción.
Ejecuta la lista de comandos de interposición contenida en la
configuración cfg
.
Parámetros.
cfg
.
Configuración a aplicar.
Valor devuelto. 0 en caso de éxito, o -1 en caso de error.
Descripción.
La función _pdi_becfg_destroyConfig()
destruye la estructura
BECFG_CONFIG devuelta por _pdi_becfg_newConfig()
y
libera memoria.
Parámetros.
cfg
.
Puntero a la configuración a destruir.
Valor devuelto. La función no devuelve nada.
Descripción.
_pdi_becfg_finalizeRead()
termina la lectura del fichero de
comandos activa en la estructura cfg
.
Parámetros.
cfg
.
Puntero a la configuración sobre la que trabajaremos.
Valor devuelto.
La función _pdi_becfg_finalizeRead()
no devuelve nada.
Descripción.
Prepara la estructura de configuración cfg
para empezar a leer un fichero de comandos a través del
descriptor fichero f
.
Parámetros.
cfg
.
Puntero a la configuración sobre la que trabajaremos.
f
.
Puntero a un descriptor de fichero desde donde leeremos
el fichero de comandos.
Valor devuelto.
La función _pdi_becfg_initializeRead()
devuelve 0 en caso de
éxito, o -1 en caso de error.
Descripción.
La primera, _pdi_becfg_getObjectByPath()
, busca la
información sobre un objeto en una configuración por la ruta a su
binario. _pdi_becfg_getObjectByAlias()
busca el objeto por su
alias y la última, _pdi_becfg_getObject()
busca primero por
el alias y en caso de no encontrarse vuelve a buscar por la ruta
al binario.
Parámetros.
cfg
.
Puntero a la configuración donde haremos la búsqueda.
alias
.
Cadena con el alias a buscar.
path
.
Cadena con el binario a buscar.
x
.
Cadena con la ruta al binario o el alias a buscar.
Valor devuelto.
Estas funciones devuelven NULL
si no se encontró el objeto, en
caso de éxito se devuelve un puntero a una estructura
BECFG_OBJ_INFO.
Descripción. Esta función devuelve el nombre del objeto (la ruta al binario, o el alias en su defecto).
Parámetros.
object
.
Puntero con información sobre el objeto.
Valor devuelto.
Una cadena con el nombre del objeto, o NULL
en caso de error.
Descripción. Estas funciones permiten cargar desde fichero(s) la configuración de los "backend" en memoria. No comprueban que los símbolos, objetos, "backends", etc. existan, tan solo los declara.
Parámetros.
fname
.
Nombre del fichero a abrir y a procesar.
f
.
Fichero desde el cual se lee el fichero de comandos.
Valor devuelto.
NULL
en caso de error, un puntero a una configuración en caso
de éxito.
Descripción.
Combina las configuraciones csrc
y
ctrg
y deja el resultado en la
configuración ctrg
.
Parámetros.
csrc
.
Configuración origen.
ctrg
.
Configuración destino.
Valor devuelto. 0 en caso de éxito, o -1 en caso de error.
![]() |
Si la ejecución falla (devuelve un valor distinto de cero), se
desaconseja usar la configuración |
Descripción.
La primera función, _pdi_becfg_newConfig()
, reserva memoria para
una nueva lista de comandos de interposición.
Parámetros.
name
.
Nombre del fichero de comandos (generalmente suele
ponerse el nombre del fichero desde donde la hemos
leído).
Valor devuelto.
Devuelve un puntero a una configuración o NULL
en caso de
error.
Descripción. Esta función devuelve el nombre del objeto (la ruta al binario, o el alias en su defecto).
Parámetros.
object
.
Puntero con información sobre el objeto.
new_alias
.
Nuevo alias a asignar. NULL
si se desea quitarle el
alias actual.
Valor devuelto. 0 en caso de éxito, -1 en caso de error
Descripción.
Imprime por el canal de "log" la lista de objetos que contiene la
configuración cfg
. El parámetro
nivel
puede tomar uno de los valores
LOG_LEVEL_*
definidos en log.h e indica a
partir de que nivel de verbosidad debe mostrarse la lista.
Parámetros.
nivel
.
Nivel de verbosidad con el que mostramos la lista.
ctrg
.
Configuración que queremos examinar.
Valor devuelto. Nada.