This doc is obsolete. The html doc is now the authoritative source.


*********************************************************
* TiLT - link program for TI calculators           *
* Copyright (C) 1999-2000, Romain Lievin                *
*                                                       *
*********************************************************


Rem: tous ces fichiers ne necessitent pas GTK pour fonctionner.

I) Structure hierarchique
-------------------------

Fichiers C (par ordre hierarchique):
- error.c: utilise errormsg.h qui contient les differents messages d'erreur
- parlink.c: fonctions d'utilisation des E/S au niveau port parallele
Utilise defs.h et ti_link.h (variables globales)
- tiXX.c: fonctions dediees a la communication entre TI et PC 
Utilise defs.h, defsXX.h, parlink.h (bas niveau) et ti_link.h
- pcx_xpm.c: lecture/ecriture de fichier au format PCX pour le screendump
- ti_link.c: programme principal de test

Fichiers H (par ordre alphabetique):
- defs.h: definition de types et des touches clavier PC
- defsXX.h: definition de types propres a la TIxx (types de variables, touches,
protocole)
- error.h: declaration de la fonction error
- errormsg.h: definition des messages d'erreurs
- parlink.h: declaration des fonctions de bas-niveau
- pcx_xpm.h: declaration de fonctions permettant d'utiliser des fichiers PCX
- tiXX.h: declaration des fonctions permettant la communication TI <-> PC
- ti_link.h: declaration des variables globales et des pointeurs de fonctions
globals pour une utilisation multi-calculatrices.
- typedefs.h: definition de types (byte et word) et de structures (pour le
directory list)


II) Variables
-------------

- uint lpt_adr: adresse de base du port parallele
- uint lpt_out: adresse du registre de sortie 
- uint lpt_in: adresse du registre d'entree
- int time_out: delai (en seconde) au bout duquel les fonctions de bas-niveau
decrochent
- int delay: delai (en micro-secondes) separant 2 bits
- float percent: pourcentage de l'operation en cours effectuee (utile pour les
barres de progression). Cette variable est mise a jour par toutes les fonctions
sauf receive_backup (utiliser la variable block a la place) et directory_list.

III) Structure d'un fichier
---------------------------

Un fichier peut servir a stocker une ou plusieurs variables. Le seul point
auquel il faut faire attention, c'est le bon positionnement du pointeur de
fichier lors de l'appel d'une fonction.

Structure d'un fichier (exemple) sauf pour les backups:

TI92		Le type de calculatrice
str		Le nom local de la variable (8 caracteres max)
my_dir\str	Le nom complet de la variable (8+1+8=17 caracteres max)
00000008	La taille de la variable sous forme d'un unsigned long
STR		Le type de variable
donnees...	Les donnees de la variable

Chaque ligne est terminee par un '\r\n'.

Structure d'un fichier de backup:

TI92            Le type de calculatrice
1.11		Version de la ROM de la calculatrice
main\backup     Inutile (pour remplissage)
00000008        La taille du backup sous forme d'un unsigned long
BACKUP          Le type de variable (evident)
donnees...      Les donnees du backup

IV) Liste des fonctions generales et de leur utilisation:
---------------------------------------------------------

Note: toutes les fonctions renvoient 0 si OK, un code d'erreur sinon. Le
message correspondant au code d'erreur peut etre obtenu a l'aide de la fonction
error de error.c

-> int ti92_isready(void);

Teste si la TI est prete.

-> int ti92_remote_control(void);

Cette fonction permet de telecommander la TI92: la touche frappee sur le PC
equivaut a celle tapee sur la TI92.

-> int ti92_screendump(byte *bitmap);

Cette fonction stocke dans le tableau bitmap une recopie de l'ecran de la TI92.
Le tableau doit avoir TI92_COLS*TI92_ROWS elements.

-> int ti92_receive_backup(FILE *file, ulong *version, word *block);

Cette fonction stocke dans le fichier pointe par file une sauvegarde du contenu
de la calculatrice.
Elle renvoie dans la variable pointee par version le numero de version de la
ROM de la calculatrice.
Format: 4 caracteres ASCII concatenes dans un long. Exemple: "1.12" donne
0x312E3132
La variable block peut etre utilisee pour afficher le numero du bloc en cours
de reception. La variable percent n'est pas utilisable car il est impossible de
savoir a l'avance combien de donnees vont etre recues.

-> int ti92_directorylist(struct varinfo *list, int *n_elts);

Cette fonction effectue un listing de tous les repertoires et de toutes les
variables de la calculatrice. Elle stocke l'ensemble dans une liste chainee.
La structure contient des informations sur le fichier ou le repertoire: son nom
, son type, si la variable est verrouillee/archivee (TI89/TI92+) et la taille 
de la variable.
Le nombre d'elements cree (en fait, il y a n_elts+1 structures donc n_elts 
variables) de la liste chainee est contenu dans n_elts.

Remarques: 
- il ne faut pas tenir compte du premier element de la liste chainee.
- la distinction repertoire/variable se fait grace au type. La 
taille d'un repertoire est le nombre de variables qu'il contient. Le nom d'une
variable est de type local.

-> int ti92_receive_var(FILE *file, char *varname, byte vartype);

Cette fonction stocke dans le fichier pointee par file la variable demandee.
Cette variable est caracterisee par son nom (varname) et son type (vartype).
Ces informations peuvent etre recuperees par un directory list.

-> int ti92_send_var(FILE *file, int local, int mvar);

Cette fonction sert a envoyer la variable contenue dans le fichier pointe par
file vers la calculatrice. 
Si local=1, la variable est envoyee dans le repertoire courant sans tenir 
compte de son repertoire d'origine sinon, la variable est envoyee dans son 
repertoire d'origine.
Si une seule variable doit etre envoyee, mvar=0. Si n variables doivent etre
envoyees, send_var doit etre appellee n-1 fois avec mvar=1 et la derniere
fois avec mvar=0.

-> int ti92_send_backup(FILE *file);

Cette fonction ne fonctionne pas pour l'instant.

V) Fonctions particulieres
--------------------------

-> char *byte_to_type(byte data);

Renvoie le type d'une variable sous forme de chaine.

-> byte type_to_byte(char *s);

Effectue l'operation inverse.
