CLB_Ezechiele_net
CLB_Ezechiele_net.dll è un assembly contenente le funzioni e classi di interfaccia fra le dll native di Colibri e l’applicativo Ezechiele di Bottinelli.
Fra le classi della libreria una in particolare, la Clb, ha il compito di comunicare le richieste alla CLB_Ezechiele.dll, la dll nativa che ha la funzione di parser dei comandi ricevuti.
In questo articolo descriveremo le singole classe e le modalità d’uso delle stesse.
Prima di cominciare forniamo alcuni concetti base usati nello sviluppo del software e le modalità di compilazione e configurazione del progetto CLB_Ezechiele_net e degli eventuali futuri assembly prodotti.
Table of Contents
Modello di interfacciamento
Il paradigma di comunicazione fra Colibri ed Ezechiele consiste nell’insieme di definizioni di seguito descritte:
Interfaccia
L’interfaccia fra le funzionalità di Colibri ed Ezechiele è fornita attraverso la classe Clb, che contiene un insieme di 7 metodi, attraverso i quali è costruito tutto il protocollo di comunicazione fra Colibrì ed Ezechiele.
Alcuni dei metodi esposti da Clb sono già ora considerati obsoleti, e sono presenti solo per compatibilità con lo sviluppo attuale di Ezechiele. Le funzioni considerate necessarie, le uniche che saranno esposte nella prossima versione, sono appunto la Clb.push_v e la Clb.push_s
tutte le altre funzioni attualmente presenti saranno sostituite utilizzando il paradigma dei Comandi in seguito descritto
Sessione
Una sessione gestisce una connessione aperta fra Colibri ed un client; la sessione permette di comunicare richieste e ricevere dati da parte del client. Ogni sessione è gestita da una classe Session istanziata, connessa ad una istanza Ezc_contex nella dll nativa CLB_Ezechiele, ed è individuata da un id unico assegnatogli a seguito dell’apertura della connessione (vedi Clb.Open_connection ).
Ezc_context è, dal punto di vista funzionale, equivalente ad un socket che permette di accedere a tutte le funzionalità esposte da Colibri, da parte di ciascun client.
Ciascuna sessione può mandare o ricevere dati da Ezc_context attraverso un protocollo ed un insieme di funzioni che saranno di seguito descritte.
Argomenti primitivi
Gli argomenti sono i tipi di dati primitivi che possono essere passati a Ezc_context attraverso la sessione aperta.
La classe che definisce il tipo di argomenti possibili è la arg. i tipi di argomento sono definiti attraverso l’enumeratore push_info_type .
Attualmente sono definiti due soli tipi di argomenti primitivi: char * e void *, sufficienti per definire tutte le funzionalità a basso livello della comunicazione con le dll native di Colibri.
Le classi primitive come come int, float, ecc. sono sempre passate come tali o puntatori void, nel caso di informazione richiesta.
In seguito definiremo meglio tali modalità.
Argomenti complessi
Esistono altre classi di supporto alla gestione degli argomenti, che consideriamo di alto livello, in funzione della loro complessità; queste classi sono fornite, o possono essere costruite, inglobando le funzionalità di scambio dei campi e strutture dati in esse contenuti; ad esempio la classe json_io, che permette di ricevere/esportare strutture di dati (.. un atlante colore, una lista di file in una directory ..ecc) contiene due funzioni, json_io.input e json_io.output che servono ad offuscare le modalità di trasferimento e ricezione degli argomenti relativi con Colibrì.
Comandi
Un comando è una stringa che contiene una frase del tipo
“get color_book“, .., “get list color_book“.. ecc.
Un comando definisce quindi un’azione richiesta a Colibri ed è concepito per essere descrittivo della stessa.
Ad un comando posono seguire seguire uno o più argomenti, definiti argomenti del comando.
I comandi sono il modo standard per comunicare fra Ezechiele e Colibri, ed hanno il vantaggio di non dovere richiedere l’esposizione di altre funzioni da parte di Colibrì, oltre le 7 attualmente fornite dalla classe di interfaccia Clb.
Configurazione del progetto
Come tutte le assembly di Colibrì il progetto viene configurato per un output del codice compilato nella cartella del programma di test CLB_import_native.
Inoltre abilitare nella sezione Debug il debug del codice nativo.
Le classi di CLB_Ezechiele_net
Le classi sono state progettate per la comunicazione con l’applicativo di Colibri.
L’applicazione Ezechiele sul server utilizza direttamente alcune delle classi, mentre altre sono da considerare ad uso interno dell’assembly.
Tutte le classi sono comunque dichiarate pubbliche, accessibili a tutte le funzioni dell’applicazione Ezechiele.
Schema delle comunicazioni fra le classi di Clb_Ezechiele_net. L’assembly è un’interfaccia fra l’applicazione client ed il server che contiene i servizi di Colibrì
Clb
La classe espone attualmente 7 metodi ciascuno relativo ad una funzione esportata dalla dll Clb_Ezechiele in Colibri.
Ogni funzione ritorna un valore booleano che definisce il successo (true) o l’insuccesso della chiamata. nel caso di fallimento, la descrizione dell’eventuale errore sarà ottenuto attraverso la funzione della sessione Session.get_clb_error (), che rimanderà una struttura json di dettaglio.
il primo argomento delle funzioni esposte è sempre un handle all’istanza Ezc_context remota (cioè gestita dalla dll nativa CLB_Ezechiele..). solo la funzione Open_connection riceve un puntatore all’id , le altre il valore dello stesso.
bool Open_connection(int* id)
Apre una connessione fra Colibri ed il client che lo richiede, rimandando l’id di un’istanza (socket) Ezc_context.
La funzione è usata internamente solo dalla classe Session
bool Close(int* id)
anche questa funzione è usata solo internamente dalla classe Session , ed ha il compito di chiudere l’istanza del socket Ezc_context in precedenza aperta (l’id passato individua lo stesso).
bool GetImageInfo(int id, int* dx, int* dy, float* resx, float* resy, int* pixel_size)
La funzione è da considerare obsoleta, e rimanda le informazioni dimensionali di un’immagine aperta e residente in un Ezc_context remoto. Attualmente è sostituita dal Comando “get image info”
public static extern bool GetImageArea(int id, int* x, int* y, int* dx, int* dy, int* pixel_size, void** buf, float scl);
Anche questa funzione è considerata obsoleta perché già sostituita dal comando “get image area” che discuteremo in seguito e che è utilizzato internamente a Session.
La funzione richiede il buffer relativo ad un’area dell’immagine aperta nel contesto remoto (Ezc_context definito dall’id). L’area è ottenuta alla scala richiesta (scl) mentre le dimensioni passate sono sempre nella scala 1:1. le dimensioni reali estratte saranno riportati nei pointer x,y,dx,dy passati inizialmente come origine sull’immagine non scalata.
Il buffer *buf è completamente gestito internamente alla Ezc_Context, che lo rilascerà, quando necessario. La sua accessibilità pertanto è relativa alla fase della richiesta e non sarà più valido in seguito..
bool FreeBuffer(int id, void* buf)
A volte Ezechiele riceverà un buffer remoto contenente informazioni richieste, che dovranno essere rilasciate alla decadenza del loro utilizzo.
Chiamare questa funzione per rilasciare il buffer remoto (chiariremo caso per caso quando necessario).
anche questa funzione è da considerare obsoleta, e sostituita dal comando “free buffer”
bool Push_v(int id, int push_info_type, void* v)
Questa funzione, come la successiva Push_s ha il compito di immettere nello stack di costruzione dei comandi un argomento void *v.
Le due funzioni Push_v e Push_s hanno come altro argomento un valore int push_info_type riconosciuto e gestito internamente dalla classe Sender che ha il compito di trasferire i comandi formattati opportunamente alla Ezc_context remota. L’uso di queste due funzioni sarà descritto in seguito, parlando della classe Sender
bool Push_s(int id, int push_info_type, string v)
Questa funzione, come la precedente Push_s ha il compito di immettere nello stack di costruzione dei comandi un argomento, questa volta di tipo string.
L’uso di questa due funzione sarà descritto in seguito, parlando della classe Sender
