No Fragments Archive 10: Diskmags/nf_archive_10.iso/MAGS/DNTPAPER/DNT_01.MSA/PROTOCOL.GEM/PROT_DOC/DOCUMENT.TXT

Text File | 1987-04-22 | 11KB | 210 lines

           TRANSMISSION DE DONNÉES ENTRE APPLICATIONS
            DOCUMENTATION RELATIVE AU PROTOCOLE GEM


Auteurs de ce protocole:
LAMBALLAIS Pierre-Louis    (Le Féroce Lapin)
Ecole Publique
53110 Ste Marie du Bois
Tél:[phone]

ALLEN Douglas            (Dad)
La Retardière
Rennes en Grenouille
53110 Lassay les Chateaux
Tél:[phone]


 -- Fonctionnement / Point de vue de l'utilisateur --

 Par convention,  l'utilisateur déclenche toujours  l'application
émétrice des données.  Ainsi un PRG traitement de texte  désirant
envoyer  un  texte  vers  un ACC qui  pourra  le  compacter  sera
l'émetteur.  Par  contre lorsque l'on voudra recharger  ce  texte
compacté,  c'est  l'accessoire qui sera l'émetteur puisque  c'est
lui qui enverra le fichier aprés l'avoir décompacté.
L'utilisateur déclenche donc l'application émétrice des  données,
celle-ci  lui  propose  la liste des  applications  présentes  en
mémoire,  compatibles  avec  cette  série de  protocole  et  donc
suceptibles  de  recevoir  ces  données.   L'utilisateur  choisit
l'application   réceptrice   et  le  transfert   se   fait   avec
éventuellement   demande   de   paramètres   pour   l'application
réceptrice.

 -- Fonctionnement / Point de vue du programmeur --
  Pour écrire,  une application utilise la fonction APPL_WRITE  à
laquelle  elle fournit l'APP_ID de l'application destinataire  du
message,  la taille de celui-ci et son adresse.  Les applications
compatibles  avec ce protocole noterons donc leur APP_ID dans  un
tableau, dont l'adresse sera notée dans le Cookie-Jar, avec comme
identificateur _TUB.
Ce  systéme de notation et d'utilisation sera fait avec  quelques
réserves, à cause de l'existence de programmes tels que MULTIDESK
ou  STUFFER,  mais  aussi afin d'envisager le cas  d'une  version
multitâche du GEM.

Le  tableau dans lequel seront notés les APP_ID des  applications
compatibles avec ce protocole, sera composé comme ceci:
PROT           */ identificateur en ascii donc sur 4 octets */
NBR_APPID      */ nbr de slot de ce tableau (sur un word)   */
slot1          */ les slots contenant les APP_IDs           */
slot2          */ des applications compatibles              */
END_FLAG       */ indication de fin des APP_ID ($FFFF)      */
emplacement pour les autres APP_ID possibles.

NBR_APPID indique donc le nombre maxi d'APP_ID que peut  contenir
le  tableau,  mais pas le nombre d'APP_ID en  place.  Le  dernier
APP_ID est suivi d'un indicateur de fin (word à $FFFF).
(ainsi  un  tableau pouvant contenir 10 APP_ID fera  en  tout  28
octets)
     Comme dans le cas du Cookie-jar, il est tout à fait possible
de fabriquer une nouvelle liste,  plus grande,  et d'y transférer
le  contenu de l'ancienne,  si une application voulant y  déposer
son APP_ID s'apperçoit qu'elle est pleine.

     Il  convient  cependant  d'être  trés  prudent:   il  faudra
vérifier avant chaque transmission,  le bon état du  tableau.  En
effet, tout comme pour le Cookie-Jar, il est tout a fait possible
que   des   applications   non-respectueuses   des   régles    de
programmation  viennent piétiner nos  plates-bandes!  C'est  trés
génant  car en cas de tentative d'écriture par APPL_WRITE  à  une
application inexistante, il y a plantage de la machine, le GEM ne
renvoyant aucun numéro d'erreur, mais juste quelques bombes...

     Une   vérification   de  l'en-tête   (PROT)   ainsi   qu'une
vérification,  en  cours  de lecture du  tableau,  d'un  éventuel
débordement  (évité  en comptant les APP_ID lus et  en  comparant
avec NBR_APPID) est donc fortement conseillé!

  -- Initialisation / Point de vue d'un ACC --
L'accessoire va chercher dans le Cookie-Jar le cookie _TUB. Il en
déduit  l'adresse  du tableau des APP_ID.  Il  vérifie  alors  la
validité  de  ce tableau à l'aide de son  en-tête,  et  si  cette
vérification  est  correcte,  il place son propre AP_ID  dans  la
liste.  Le  cas des accessoire lancés avec Multidesk  ou  Stuffer
doit  être  prévu.  L'accessoire envisageage donc le cas  ou  son
APP_ID  serait déja inscrit dans la liste,  auquel cas il  ne  le
rajoute  pas.  Si  l'accessoire se rajoute,  il n'oublie  pas  de
reculer le flag de fin ($FFFF). Si par hasard le tableau est déja
plein  (on le vérifie en comptant les APP_ID de celui-ci  est  en
comparant ce nombre avec NBR_APPID indiquant combien d'emplcament
son  disponible),  l'accessoire  à la possibilité  de  créer  une
nouvelle liste d'APP_ID,  plus grande, d'y recopier le contenu de
l'ancienne  puis  de noter son adresse dans le  Cookie-Jar  à  la
place de l'adresse de l'ancienne liste.  Ceci explique  également
qu'il  faudra  demander  à chaque transmission  l'adresse  de  la
liste,  plutôt  que  de  se fier à l'adresse  trouvé  lors  d'une
précédente demande.

S'il  estime  que  l'initialisation est  bonne  il  continue  son
déroulement normal.  Si par contre il estime que l'initialisation
n'est  pas  correcte (par exemple s'il n'a pas trouvé  de  Cookie
_TUB,  ou  bien  si l'en-tête du tableau n'est pas bonne)  il  va
créer un nouveau tableau et placer l'adresse de celui-ci, avec le
Cookie _TUB,  dans le Cookie-Jar en créant éventuellement  celui-
ci.

 -- Initialisation / Point de vue d'un programme --
 Au démarrage un PRG doit se déclarer, la liste ne comprenant que
les  APP_ID des accessoires.  Il va donc chercher le cookie  _TUB
dans le Cookie-Jar.  S'il ne le trouve pas,  il en déduit que  la
transmission sera impossible,  idem si le Cookie-Jar existe  mais
qu'il  ne  contient  pas de Cookie  _TUB.  Lorsque  le  programme
posséde  l'adresse du tableau pour le protocole,  il teste  l'en-
tête de celui-ci.  Si cette liste n'est pas valable, il abandonne
(étant  un  programme il ne peut pas fabriquer de  liste  puisque
celle-ci disparaitrait avec lui), sinon il y rajoute son APP_ID.
Lorsque  l'on quittera le programme,  celui-ci devra retirer  son
APP_ID de la liste,  afin que les accessoires ne cherchent pas  à
communiquer avec lui alors qu'il n'est plus en mémoire.
S'il n'y a plus de place dans la liste des APP_ID,  le  programme
ne pourra pas être appelé.  Cependant rien ne l'empéchera de lire
cette  liste  et donc d'appeler  les  autres  applications.  Pour
éviter d'avoir une liste d'APP_ID pleines, les accessoire doivent
en prévoir une assez grande.  Dans les exemples fournis sur cette
disquette,  la liste d'APP_ID permet d'en recevoir 10.  Il serait
normal  de songer à en mettre par exemple une de 16,  au  cas  ou
celle  de  10  serait  pleine.  Il  est  également  tout  à  fait
envisageable  de  réaliser un petit programme  placé  en  dossier
AUTO,  qui fabriquerait une liste,  et pourquoi pas un Cookie-Jar
éventuel (pour penser aux STF!).

A  chaque fois qu'un programme tentera de placer son APP_ID  dans
la liste,  il devra impérativement la parcourir afin de  vérifier
si cet identificateur ne s'y trouve pas déja, ceci pour envisager
le cas d'un programme ayant précédement placé son APP_ID et ayant
oublié de le retirer (cas d'un programme quittant par une  erreur
par exemple).

 -- Préparation d'une transmission  --
L'application va chercher l'adresse du Cookie-Jar,  y cherche  le
Cookie  _TUB,  et  en  déduit  l'adresse  du  tableau  Protocole.
L'application vérifie l'en-tête de ce tableau.  Deux cas  peuvent
se présenter:
 1) données incorrectes: transmission impossible
 2) données correctes: début de communication

  Cette étape de préparation sera exécutée à chaque  fois  qu'une
transmission  sera demandée car il est tout à  fait  envisageable
qu'une application étrangère vienne détruire le tableau protocole
(ou  même le Cookie-Jar) à notre insu.  Il est donc impératif  de
tout vérifier avant chaque transmission.

 -- COMMUNICATION ENTRE 2 APPLICATIONS  --
  L'application désirant correspondre avec une autre  application
est  donc  actuellement en possession de l'adresse  d'un  tableau
contenant  les  APP_ID des applications actives  en  mémoire.  Ce
tableau contient la liste des APP_ID, que ceux-ci appartiennent à
des  applications compatibles avec le protocole ou non.  (cas  de
Multidesk ou d'autres lanceurs d'accessoires...)

Petite  explication pour multidesk:  celui-ci une fois  lancé  ne
note pas son APP_ID dans la liste puisqu'il n'est pas compatible.
Nous lançons ensuite gràce à Multidesk,  un accessoire compatible
avec le protocole.  Cet accessoire va donc noter son APP_ID  dans
la  liste,  mais il s'agit en fait du même APP_ID que  Multidesk.
Lorsque nous quittons cet accessoire (il disparait de la  mémoire
à  cause  de Multidesk),  son APP_ID reste dans  la  liste.  Nous
allons  donc  envoyer des messages à Multidesk,  en  croyant  les
envoyer à une application compatible!

 Le communication va pouvoir commencer,  en utilisant la fonction
APPL_WRITE.  L'application recevant le message sera en mesure  de
le lire après un EVNT_MESAG ou bien un EVNT_MULTI.  Le  protocole
consiste en fait à se mettre d'accord sur les numéros de  message
que  nous  allons  utiliser et sur le  format  de  ces  messages.
Toujours par convention nous avons attribué aux messages émis par
les applications engageant la conversation,  des numéros  paires.
L'application  répondant  envoyant des  messages  impaires.  Nous
avons mis au point 3 séries de codes.

  La  première série est utilisée pour  transmettre  des  données
(échange de blocs mémoires divers) et ces messages sont numérotés
à partir de 300.
   La  seconde  série  est  utilisée  pour  l'échange  de   menus
déroulants.  Son utilisation permet à un ACC d'avoir un véritable
menu  déroulant GEM,  classiquement fabriqué avec un  éditeur  de
ressource  et géré tout aussi classiquement.  Ces  messages  sont
numérotés à partir de 400.
   La  troisième  série  est  utilisée  pour  le   pilotage   des
applications.  Avec cette série de messages, une application peut
en  piloter  une  autre.  Ainsi un  ACC  pourra  automatiser  les
procédures de recherches d'une base de données,  par exemple. Les
messages de cette série sont numérotés à partir de 500.

 Vous trouverez ci-joint la liste et la description des  messages
du   protocole,   ainsi  que  les  listings  en   assembleur   de
l'initialisation vue par un ACC, l'initialisation vue par un PRG,
la préparation des transmissions, etc... Vous trouverez également
le listing d'un ACC et d'un PRG s'échangeant des documents,  ceux
d'un ACC et d'un PRG dont le second gére le menu du  premier,  et
enfin  ceux  d'un ACC et d'un PRG dont le premier  déclenche  les
routines  de  dessins du second.  Il est bien évident  qu'il  est
possible  de  réaliser des applications répondant  à  toutes  ces
fonctions, mais ces listings n'étant que des exemples, nous avons
jugé plus clair de montrer séparement les possibilités.

     Bonne utilisation de ce protocole !!!