Tous les modules possèdent obligatoirement 4 fonctions :

1. init ⇒ pour initialiser l'état interne du module (allocation mémoire si besoin, etc.). Appelé automatiquement au premier appel de fonction du module
2. end ⇒ pour libérer les ressources allouées dans init. Appelé automatiquement à la terminaison du programme
3. vers(version) ⇒ renvoie la version en cours du module (variable version Number ou Dynamic)
4. error(modError, modErrorDescription) ⇒ renvoie la dernière erreur spécifique au module dans variable modError (number). Si le paramètre modErrorDescription (chaine) est présent, il contiendra en retour un libellé de l'erreur

Le pseudo module template permet de tester ces 4 fonctions. Exemple :

;
declare v
invoke template&vers(version = v)
;

Module de chiffrement et déchiffrement de données.

• toAES128(key, plaintext, encrypted) : chiffrement AES 128 bits de plaintext en utilisant la clé key (16 octets). Résultat chiffré dans encrypted
• fromAES128(key, encrypted, plaintext) : déchiffrement AES 128 bits de encrypted en utilisant la clé key (16 octets). Résultat en clair dans plaintext
• toAES192(key, plaintext, encrypted) : chiffrement AES 192 bits de plaintext en utilisant la clé key (24 octets). Résultat chiffré dans encrypted
• fromAES192(key, encrypted, plaintext) : déchiffrement AES 192 bits de encrypted en utilisant la clé key (24 octets). Résultat en clair dans plaintext
• toAES256(key, plaintext, encrypted) : chiffrement AES 256 bits de plaintext en utilisant la clé key (32 octets). Résultat chiffré dans encrypted
• fromAES256(key, encrypted, plaintext) : déchiffrement AES 256 bits de encrypted en utilisant la clé key (32 octets). Résultat en clair dans plaintext

TODO : préciser le mode, le vecteur d'init et le padding

Module permettant de faire des conversions de texte en hexadécimal et Base64.

• toHexa(plaintext, hexadecimal) : convertit le texte en clair plaintext en une chaine hexadécimale hexadecimal
• fromHexa(hexadecimal, plaintext) : convertit la chaine en hexadécimal hexadecimal en son équivalent en texte clair plaintext
• toBase64(plaintext, base64encoded) : convertit le texte en clair plaintext en une chaine codée en Base64 base64encoded
• fromBase64(base64encoded, plaintext) : convertit la chaine en Base64 base64encoded en son équivalent en texte clair plaintext

Module permettant de gérer les fichiers de l'OS de l'hôte exécutant le programme en cours.

• get(path, content) : lit le fichier, dont le chemin complet est donné dans path, et renvoie son contenu dans content. Génère une exception si le fichier est inconnu ou inaccessible.
• set(path, content) : écrit la variable Dynamic content dans le fichier dont le chemin complet est donné dans path. Génère une exception si le chemin est inconnu, inaccessible, ou si les données ne peuvent pas être écrites (droits,…)
• size(path, length) : renvoie la taille, dans la variable Number length du fichier dont le chemin complet est donné par path
• delete(path) : supprime le fichier dont le chemin complet est donné dans path. Génère une exception si le fichier ne peut pas être supprimé.
• rename(oldPath, newPath) : renomme/déplace le fichier oldPath en newPath. Génère une exception en cas d'erreur (droits, FS différents, chemin cible inexistant).
• append(path, content) : écrit la variable Dynamic content à la fin du fichier dont le chemin complet est donné dans path. S'il n'existait pas, le fichier est créé. Génère une exception en cas d'erreur.
• dir(path, fileList) : prend en compte le chemin donné par path et renvoie, dans la variable fileList , la liste des fichiers et répertoires trouvés dans le répertoire indiqué, en multi-champs. Les fichiers spéciaux ne sont pas retournés (Unix seulement), ni les pseudo fichiers . et ..

Module permettant de calculer différents hash de données, selon divers algorithmes. Sauf indication contraire, le résultat hashedText est le hash hexadécimal, mis en chaine de caractères.

• MD2(plaintext, hashedText) : calcule le hash selon l'algorithme MD2 des données fournies dans plaintext et renvoie le résultat dans la variable hashedText
• MD4(plaintext, hashedText) : calcule le hash selon l'algorithme MD4 des données fournies dans plaintext et renvoie le résultat dans la variable hashedText
• MD5(plaintext, hashedText) : calcule le hash selon l'algorithme MD5 des données fournies dans plaintext et renvoie le résultat dans la variable hashedText
• Sha1(plaintext, hashedText) : calcule le hash selon l'algorithme Sha1 des données fournies dans plaintext et renvoie le résultat dans la variable hashedText
• Adler32(plaintext, hashedText) : calcule le hash selon l'algorithme Adler32 des données fournies dans plaintext et renvoie le résultat dans la variable hashedText

NOTA : module/doc à revoir (treefetch et print)

• decode(jsonText, extractedKey, extractedValue) : réalise le décodage du contenu json présent dans la variable chaîne jsonText, et renvoie l'ensemble des clés/valeurs décodées dans les chaînes extractedKey et extractedValue. Les informations globales liées au contenu json qui vient d'être décodé restent mémorisées dans le module.
• print(extractedKey, extractedValue, prettyPrint) : restitue de manière lisible dans la variable chaîne prettyPrint le contenu json déjà décodé dans les 2 chaines extractedKey et extractedValue.
• treeFetch(fetchParameters, done) : récupère une série de clés, en utilisant les informations données par la hashtable fetchParameters. La variable Number done renvoie @true quand la récupération est terminée, @false sinon. La hashtable fetchParameters doit contenir en entrée les deux chaines issues du décodage json. fetchParameters.DecodedKey doit recevoir extractedKey et fetchParameters.DecodedValue doit recevoir extractedValue.

Module permettant de faire des analyses syntaxiques sur des chaines, selon des règles données en paramètre.

• compile(lexRules, compiledRules, [rulesNameSet]) : à partir des règles lex, paramètre lexRules, génère le format interne utilisé par le module, paramètre compiledRules, pour les analyses de chaines en entrée. Si le paramètre rulesNameSet est présent, de type hashtable, il est rempli avec les constantes correspondant aux numéros de chaque règle
• analyze(compiledRules, value, tokenList) : à partir des règles au format interne, paramètre compiledRules fourni par la fonction compile, lit la chaine paramètre value et génère le résultat de l'analyse syntaxique dans le paramètre tokenList. Le résultat contient les tokens trouvés, selon 3 champs en multi-champs ; chaque sous-champ donne l'élément trouvé, dans l'ordre :
  1. token{1, x} : valeur du token en hexa (à décoder avec conv&fromHexa)
  2. token{2, x} : numéro de la regle trouvée pour le token, à comparer avec les constantes créées suite à l'appel de la fonction compile (rulesNameSet)
  3. token{3, x} : position du token trouvé dans la chaine source value
• getToken(tokenList, tokenIndex, tokenSet) : renvoie dans la hashtable paramètre tokenSet le token trouvé (.tokenNumber.tokenValue.tokenLocation), indice dans le paramètre tokenIndex, à partir de la liste de tous les tokens trouvés depuis le dernier analyze (paramètre tokenList). Si l'indice du token demandé n'est pas présent dans le résultat, .tokenNumber est renvoyé à 0.

Module permettant de compresser et décompresser des données, algorithme LZW compatible au format lzw utilisé dans les fichiers PDF.

• set(plaintextThenCompressed) : compresse les données contenues dans la variable Dynamic plaintextThenCompressed, et renvoie dans la même variable les données compressées, compatibles Lzw-PDF.
• get(compressedThenPlaintext, [reverse]) : décompresse les données fournies dans la variable Dynamic compressedThenPlaintext, et renvoie dans la même variable les données en clair. Mettre le paramètre reverse à @true pour décompresser des données spécifiquement au format GIF ; par défaut à @false (compatible Lzw-PDF).

NOTA : revoir la gestion des numéros des images (del_image change les numéros)

• beginDoc(pdfParameterSet) : démarre un nouveau document Pdf. pdfParameterSet est une hashtable qui doit contenir les champs suivants, permettant d'initialiser le document :
  • .Title : titre du document (string)
  • .Fonts : liste des fontes qui seront utilisées dans le document, chaîne contenant les noms des fontes en multi-champs (cf. tableau, le n° associé est le compteur interne du format PDF, à ignorer)
  • .Pages : nombre total de pages du document
  • .Format : nombre donnant la taille de chaque page - A4P A4L A3P A3L (1 2 3 4)
• endDoc(pdfContent) : clôture le document Pdf en cours, et renvoie tout son contenu dans la chaine pdfContent
• addPage : valide l'ajout d'une page au document Pdf en cours, à appeler après avoir ajouté les éléments de la page grâce aux fonctions qui suivent. Les pages sont toutes compactées avec l'algorithme Lzw.
• addText(pdfParameterSet, string) : ajoute à la page courante la chaine string selon le formatage décrit dans la hashtable pdfParameterSet qui doit contenir les champs suivants :
  • .X, .Y, .W, .H : position x,y et dimension w,h du cadre englobant la chaîne
  • .Font : nombre donnant la police à utiliser pour le rendu de la chaîne, indice dans la liste des polices envoyée à la fonction beginDoc (PAS le numéro interne du tableau)
  • .Size : taille de la police pour la fonte
  • .Color : couleur du texte, format RGB (R * 65536 + G * 256 + B)
• addGraph(pdfParameterSet) : ajoute à la page courante un élément graphique décrit dans la hashtable pdfParameterSet qui doit contenir les champs suivants :
  • .X, .Y, .W, .H : position x,y et dimension w,h du cadre englobant l'élément
  • .StrokeColor : couleur des lignes, si affichées, de l'élément
  • .FillColor : couleur de remplissage de l'élément
  • .LineThickness : nombre donnant l'épaisseur des traits, de 0 à 9
  • .Dotted : nombre indiquant le type de ligne pointillé à utiliser, ou aucun, de 0 à 9
  • .Type : chaîne indiquant le type d'élément graphique à insérer :
    • L ligne
    • C cadre sans remplissage
    • R remplissage de la zone sans cadre
    • D cadre avec remplissage
• addCab128(pdfParameterSet, string) : ajoute à la page la chaîne string transformée en code à barre EAN128, pdfParameterSet doit contenir les éléments suivants :
  • .X, .Y, .H : position x,y et hauteur h des barres
• addImage(pdfParameterSet) : ajoute à la page courante une image déjà chargée au préalable, selon les informations décrites dans la hashtable pdfParameterSet qui doit contenir les champs suivants :
  • .X, .Y : coordonnées x,y du coin haut/gauche de l'image dans la page
  • .ImageIndex : numéro de l'image
• loadImage(image, format) : charge dans le module, pour un usage ultérieur, l'image dont le contenu est passé dans la chaîne image. La première image chargée porte le numéro 1, etc. Formats supportés, chaîne format : BMP (32bpp) et GIF.
• delImage(imageIndex) : supprime l'image numéro imageIndex du module ; elle ne pourra plus être utilisée par la suite (NOTA pbm de numéro avec suppression)
• listing(pdfParameterSet, textThenPdfContent) : crée un document Pdf, de type listing, avec les données textuelle de textThenPdfContent et renvoie le contenu du Pdf généré dans textThenPdfContent. Les éléments permettant de créer le listing sont donnés par la hashtable pdfParameterSet qui doit contenir les champs suivants :
  • .Title : titre du listing (texte)
  • .Format : nombre donnant le format de la page à utiliser : A4P A4L (1 2)

Liste des fontes ⇒

Module permettant de générer des nombres pseudo-aléatoires, algorithme Mersenne twister.

• setSeed(seedValue) : utilise le nombre seedValue donné, pour initialiser le générateur de nombres pseudo-aléatoires
• get(nextRandomNumber) : renvoie dans nextRandomNumber le prochain nombre pseudo-aléatoire calculé par le générateur (nombre entier compris entre 0 et 4 294 967 295)

NOTA : module à finir, revoir doc (newprocessshmreader/writer) Module gérant la communication inter-processus, basée sur des messages textes. Chaque processus possède une queue qui permet de recevoir les messages émis par les autres processus.

• get(content) : renvoie dans content le prochain message reçu depuis la queue interne du processus en cours. S'il n'y a pas de message à lire, renvoie vide. Si le programme n'a pas de nom (identifiant mis à la suite de begin ou background), seul le premier process lisant ces messages pourra les recevoir, via un nom vide. Les autres ne les recevront pas car en interne la zone mémoire est déjà utilisée.
• set(textMessage, processName) : envoie le message texte textMessage au processus identifié par processName. L'identifiant d'un process est le nom donné au module principal dans l'instruction begin ou background du programme W.

Module gérant la communication sockets, côté serveur et côté client. Les données transitent en clair.

• server(portNumber) : crée un point d'entrée serveur sur le n° de portNumber indiqué (n° autorisés : 1024 à 65535 uniquement). Le module ne gère qu'un seul serveur actif au même moment.
• wait(timeout, clientSock) : attend une demande de connexion entrante depuis un client. Si une demande de connexion est acceptée, clientSock contient en retour un id de connexion, à mémoriser car il servira a identifier la connexion à utiliser lors des lectures get et écritures set entre ce client et le serveur. Si aucune connexion n'est demandée au bout du délai timeout (en secondes), l'id renvoyé dans clientSock est négatif, confirmant qu'aucune de demande de connexion n'est arrivée dans le délai indiqué. Le module gère plusieurs connexions entrantes simultanées.
• stopServer : supprime le point d'entrée serveur créé avec server.
• connect(host, portNumber, socket) : initie une connexion socket au serveur host sur le n° de portNumber (sans limitation de numéro). host peut contenir un nom de serveur, mais aussi une adresse IP v4. Quand la demande est acceptée par le serveur, socket contient en retour un id de connexion, à mémoriser car il servira a identifier la connexion à utiliser lors des lectures get / écritures set entre ce client et le serveur. Quand la demande est refusée, une exception est générée. Le module gère plusieurs connexions sortantes simultanées.
• stop(socket) : arrête la connexion identifiée par l'id socket, que ce soit la partie cliente donnée par connect aussi bien que la partie serveur donnée par wait.
• get(socket, data, timeout) : lit les données venant de l'autre côté de la connexion identifiée par l'id socket. Les données lues sont renvoyées dans la chaîne data. Si aucune donnée n'est disponible au bout du délai timeout donné, (en secondes), la chaîne data est renvoyée vide.
• set(socket, data) : écrit les données de data sur la connexion identifiée par l'id socket.
• getHostname(name, ip) : renvoie le nom (dans name) et l'adresse ip (dans ip) de l'hôte qui exécute le programme en cours.

Module basé sur lib_ssh permettant l'accès sécurisé à un serveur.

• openSession(host, username, password) : ouvre une connexion sécurisée vers le serveur host (nom ou adresse IP), en utilisant l'authentification username /password
• endSession : ferme la connexion courante
• execChannel(command, response, timeout) : exécute la commande command sur le serveur distant, et lit la réponse dans response, en utilisant le paramètre timeout comme délai de lecture (en seconde).
• openChannel : ouvre un pseudo terminal sur le serveur distant.
• closeChannel : termine le pseudo terminal distant.
• readChannel(response, timeout) : lit la réponse du serveur distant dans response, en utilisant timeout comme délai de lecture (en seconde).
• writeChannel(command) : exécute la commande command sur le serveur distant
• openSftp : ouvre un canal de type transfert avec le serveur distant.
• closeSftp : ferme le canal de type transfert mais laisse la connexion au serveur ouverte.
• to be continued…

Pour l'exécution de commandes ponctuelles, le workflow typique d'exécution est le suivant :

;
invoke wssh&openSession(host, user, pwd)
;
; do something
;
invoke wssh&execChannel(cmd, res, timeout)
;
; do another thing
;
invoke wssh&execChannel(cmd, res, timeout)
;
; terminate
invoke wssh&endSession
;

Pour l'exécution de plusieurs commandes à la suite les unes des autres, tel une émulation de terminal distant, voici le workflow à utiliser :

;
invoke wssh&openSession(host, user, pwd)
invoke wssh&openChannel
;
; read login information
invoke wssh&readChannel(res, timeout)
;
loop
   ;
   invoke wssh&writeChannel(cmd)
   ;
   invoke wssh&readChannel(res, timeout)
   ;
endloop
;
invoke wssh&closeChannel
; terminate
invoke wssh&endSession
;

Module gérant les liens avec le shell et l'OS hôte.

• execute(command, returnCode, [capturing]) : exécute la commande OS command dans un shell. Renvoie le code retour de la commande dans returnCode. Si le 3ème paramètre capturing est fourni, il contient en retour la sortie générée par la commande dans le terminal (sortie standard)
• getEnv(varName, value) : renvoie dans value le contenu de la variable d'environnement (dans la session courante) nommée varName. Génère l'exception EXMOD_SYSTEM_UNKNOWNVARENV si la variable d'environnement est inconnue
• createEnv(varName, value) : crée la variable d'environnement nommée varName dans la session courante, avec la valeur value. Génère l'exception EXMOD_SYSTEM_SETENV si la variable est déjà présente (utiliser updateEnv dans ce cas)
• updateEnv(varName, value) : met à jour la variable d'environnement varName avec la valeur value. Génère l'exception EXMOD_SYSTEM_SETENV si la variable est inconnue de la session en cours.
• deleteEnv(varName) : supprime la variable d'environnement nommée varName de la session courante. Génère l'exception EXMOD_SYSTEM_SETENV si la variable est inconnue
• getOS(OScode) : renvoie un code, dans le paramètre OScode, indiquant le type de l'OS hôte du programme en cours (de type chaîne) : Windows, Linux (différent du contenu de la variable système @os)
• sendSignal(pid, signalNumber) : envoie le signal numéro signalNumber au processus identifié par son numéro pid. Seuls les 3 signaux SIGTERM, SIGINT, SIGUSR1 sont pris en charge. Les autres sont ignorés. Fonction compatible Unix/Windows mais sous Windows, ce sont des évènements qui sont générés, pas des signaux ; SIGTERM et SIGINT génèrent un évènement Global\\wterm<pid> et SIGUSR1 génère un évènement Global\\wdebug<pid>
• sleep(duration) : endort le process en cours, pour une durée de duration secondes

Module permettant de manipuler des horodates, en TU et temps local, de mesurer le temps passé (chrono) et de gérer des alarmes temporelles. Nota : TU, UTC et GMT ont la même signification ici : temps universel méridien de Greenwich.

• startChrono : démarre le chronomètre, pour mesurer une durée
• lapChrono(duration) : donne le temps passé en secondes depuis le dernier appel de start ou lap (variable Number duration)

• set(timeParameterSet, timestamp, offset, string, stringFormat) : mémorise dans la hashtable timeParameterSet (obligatoire dans tous les cas) la date ; deux combinaisons de paramètres en entrée sont prises en charge, selon la présence ou non de paramètres (travailler avec des paramètres nommés ici, et ne pas passer ceux à ignorer) :
  • timestamp seul ou timestamp et offset : date passée dans timestamp (au sens Unix) et donc en TU, ou offset en plus, permettant une date locale (offset ajouté au timestamp)
  • string seul (le format est le standard ISO8601 A-M-JTh:m:SF) ou string et stringFormat ; dans ce dernier cas, en l'absence du fuseau, le traitement considère que la chaine représente une date locale
• setNow(timeParameterSet) : mémorise la date heure en cours, résultat dans la hashtable timeParameterSet
• get(timeParameterSet, timedateFormat, timedateUTC, timedateString) : convertit la date déjà présente dans la hashtable timeParameterSet, la date UTC si timedateUTC vaut @true sinon la date locale, selon le format timedateFormat, et met le résultat dans timedateString

• setAlarm(name, beginning, delay, gmt, occurence) : déclare une alarme name, à déclencher à l'heure hh:mm:ss (paramètre beginning, vide signifiant tout de suite), selon une fréquence de hh:mm:ss (paramètre delay), et pour un nombre d'activation donné par occurence (0 permettant un nombre infini d'activation). Le paramètre gmt indique si l'heure de début beginning donne une heure UTC (si @true) ou locale (sinon) quand renseignée
• stopAlarm(name) : désactive l'alarme name
• getNextActivation(name, nextTime) : renvoie la prochaine échéance de l'alarme name dans l'horodate nextTime (hashtable à passer à la méthode get ci-dessus comme paramètre timeParameterSet pour une sortie chaine)
• alarmActive(name, isActive) : indique en retour dans isActive si l'alarme name est active (@true alors, sinon @false), c'est à dire s'il y a encore au moins une activation à venir
• triggeredAlarm(name, triggered, reposition) : indique si l'alarme name est arrivée à échéance : renvoie @true dans triggered dans ce cas, sinon @false (une alarme inactive qui n'a plus d'occurrence renvoie toujours @false). Si le paramètre reposition vaut @true, la prochaine occurrence est recalée à une date postérieure à la date courante, en ajoutant le délai autant de fois que nécessaire. Sinon, le délai est ajouté une seule fois ; dans ce cas, si le programme a pris du retard, un nouvel appel de triggeredAlarm peut immédiatement renvoyer @true.

Liste des caractères assurant le formatage des timedate (paramètres stringFormat et timedateFormat) :

  A Y : annee sur 4 chiffres
  a y : annee sur 2 chiffres ( 0 => 2000 )
  M   : mois sur 2 chiffres
  L   : mois sur 3 lettres (RFC822/5322) Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
  J D : jour sur 2 chiffres
  l   : jour de la semaine sur 3 lettres (RFC822/5322) Mon Tue Wed Thu Fri Sat Sun
  h   : heure sur 2 chiffres
  m   : minutes sur 2 chiffres
  S   : secondes sur 2 chiffres avec les fractions de secondes (de 0 a 7 decimales), exemple "12,456" ou "01.1234567" (les fractions de secondes sont ignorees et ne sont pas memorisees)
  s   : secondes sur 2 chiffres
  F   : fuseau horaire, soit "Z" pour UTC, soit "+/-hh:mm" heures et minutes en plus ou moins, exemples "+01:00" "-02:30" etc.
  f   : zone (RFC822/5322) UT GMT EST EDT CST CDT MST MDT PST PDT
                           0  0   -5  -4  -6  -5  -7  -6  -8  -7
  g   : zone (RFC822/5322 militaire) (1,1,a-ik-zA-IK-Z) ; A à M : -1 à -12 ; N à Y : +1 à +12 ; Z = UTC
  n   : zone numerique (1,1,+-) (4,4,0-9) : +0000 pour UTC, +0200, -0100, etc.

Nota : le module ignore les fractions de secondes (en entrée) et n'en affiche pas en sortie (même avec le formatage S)