Références des fonctions

Cette page énumère les différentes fonctions disponibles dans la bibliothèque trthtml et détaille la liste des paramètres à fournir à chaque fonction pour l'utiliser.

Vous pouvez aller directement à la section qui vous intéresse à partir de ce menu.

Réception d'une demande sur le port éthernet

Une seule fonction permet de récupérer la demande d'une page web ou d'un autre fichier effectuée par le navigateur web connecté au port éthernet de la carte Arduino.

C'est la fonction lire_trame_client

Prototype : 
void lire_trame_client (EthernetClient client, char *url=0, int taille=14,
            char *post=0, int tailpost=0, char *cookie=0, int tailcook=0);
Cette fonction comporte un paramètre obligatoire et 6 paramètres optionnels.

Selon les informations qu'on souhaite pouvoir récupérer du navigateur web, on peut appeler lire_trame_client avec 1, 3, 5 ou 7 paramètres.

Paramètre obligatoire : Paramètres optionnels : La liste des paramètres à utiliser dépend de la nature du site web supporté par la carte Arduino.

Site web constitué d'une page unique

Si le site web est constitué d'une seule page destinée seulement à être consultée, et que cette page ne fait pas appel à un fichier CSS distinct du fichier HTML, le programme serveur n'a pas besoin d'analyser la demande du navigateur client pour fournir l'information demandée.

Dans ce cas, l'utilisation de la fonction lire_trame_client est très simple :
    lire_trame_client (client);
Ce mode d'utilisation de la fonction lire_trame_client est employé dans le programme Compteur de passages et des 2 exemples de station météo.

Site web multi-page sans formulaire de saisie

Si le site web comporte plusieurs pages (ou même une page unique avec un fichier CSS séparé), il est nécessaire d'analyser la demande du navigateur web pour lui fournir l'information demandée.

Pour cela, on va récupérer le nom du fichier que le navigateur web a demandé dans l'url :
    lire_trame_client (client, url, sizeof (url));
Au préalable, on aura déclaré un tableau de caractères comme ceci :
    char url [14];
Comme on n'a besoin de récupérer qu'un nom de fichier (implanté dans le répertoire racine de la carte micro SD avec un nom supporté par le système de fichier FAT de MS-DOS), la taille optimale pour la variable url est de 12 + 2 = 14 caractères.

Ce mode d'utilisation de la fonction lire_trame_client est employé dans les programmes de la série Site statique multi pages

Site web interactif avec formulaire utilisant la méthode GET

Si le site web est interactif, avec des formulaires qui utilisent seulement la méthode GET, l'appel de la fonction lire_trame_client est le même que dans le cas précédent :
    lire_trame_client (client, url, sizeof (url));
Cependant, le tableau de caractères url devra être plus grand, afin de mémoriser aussi la liste des paramètres passés par la méthode GET.

Dans la pratique, le nombre de caractères nécessaires pour le tableau sera le nombre de caractères compris entre le / qui suit l'adresse IP et la fin de l'URL la plus longue que le navigateur peut transmettre en réponse à la validation d'un formulaire du site.

Site web interactif avec formulaire utilisant la méthode POST

Dans le cas où le site web transmet des données par la méthode POST, une autre variable devra être utilisée pour récupérer et mémoriser ces données.

Dans ce cas, l'appel de la fonction lire_trame_client sera le suivant :
    lire_trame_client (client, url, sizeof (url), post, sizeof (post));
La taille du tableau de caractères url (14 caractères ou plus) dépend de l'utilisation ou non de la méthode GET pour certains formulaires.

La taille du tableau de caractères post devra être suffisante pour mémoriser la totalité des données de la forme :
avec un caractère de plus pour chaque variable passée par la méthode POST.

Site web avec cookies

Enfin, si le site web utilise des cookies (ça risque d'être rare sur un site hébergé par une carte Arduino), l'appel de la fonction lire_trame_client se fera de l'une des 2 manières suivantes :
    lire_trame_client (client, url, sizeof (url), 0, 0, cookie, sizeof (cookie));

    lire_trame_client (client, url, sizeof (url), post, sizeof (post), cookie, sizeof (cookie));
Dans la première syntaxe, on ne récupère pas de variable par la méthode POST, dans la deuxième, on le fait.

La taille du tableau de caractères cookie devra être suffisante pour mémoriser la totalité des données de la forme :
avec un caractère de plus pour chaque cookie.

Envoi sur le port éthernet

4 fonctions sont disponibles pour envoyer des données au navigateur web via le port éthernet :

Envoi d'un caractère

Prototype : 
void envoie_car (char car, EthernetClient client);
Cette fonction comporte 2 paramètres obligatoires :
Exemples d'appel : 
    envoie_car (car, client);
    envoie_car ('A', client);
Dans le premier cas, le caractère à envoyer est mémorisé dans une variable, dans le 2ème cas, il est précisé directement.

Envoi d'une série de caractères

Prototype : 
void envoie_trame (String trame, EthernetClient client);
Cette fonction comporte 2 paramètres obligatoires :
Exemples d'appel : 
    envoie_trame (message, client);
    envoie_trame ("Bonjour", client);
Dans le premier cas, la chaine de caractères à envoyer est mémorisée dans une variable, dans le 2ème cas, elle est précisée directement.

Envoi d'une série de caractères suivi d'un passage à la ligne

Prototype : 
void envoieln_trame (String trame, EthernetClient client);
Cette fonction comporte 2 paramètres obligatoires :
Cette fonction s'utilise exactement comme la fonction envoie_trame

Envoi de l'entête d'une page web acceptée par le serveur

Cette fonction envoie au navigateur web le début de la réponse suite à une demande de page.

Le code de retour envoyé au navigateur est toujours 200 (requête acceptée) et après avoir appelé cette fonction, il faudra envoyer le contenu du fichier demandé.

Prototype : 
void envoie_entete_reponse (EthernetClient client, char *url=0);
Paramètre obligatoire : Paramètre optionnel mais souhaitable : Si le paramètre url n'est pas précisé, cette fonction envoie la bonne entête pour une page html.
En indiquant le nom de fichier demandé dans le paramètre url, cette fonction fonctionne aussi pour un fichier css.

L'envoi d'autres catégories de fichiers, par exemple des images ne nécessiterait pas forcément une grosse adaptation de cette fonction, mais ce type d'envoi n'a pas été testé.

Traitement des chaines de caractères

Les 2 fonctions qui suivent existent en PHP et dans d'autres langages de programmation, mais pas en langage C.

Elles ont été rajoutées.

Recherche de la position d'une sous-chaine dans une chaine de caractères

Prototype : 
    int  strpos (char *chaine, char *rech);
Cette fonction comporte 2 paramètres obligatoires :
Code de retour :

Si la sous-chaine rech a été trouvée dans la chaine de caractères chaine, la fonction retourne le nombre de caractères dans chaine avant le début de la sous-chaine rech.

En particulier, si la chaine de caractères chaine commence par la sous-chaine rech, la valeur retournée sera 0.

Si la sous-chaine rech n'est pas trouvée dans la chaine de caractères chaine, la fonction retourne la valeur -1

Extraction d'une sous-chaine de caractères

Prototype : 
    void substr (char *orig, char *dest, int debut, int fin);
Cette fonction comporte 4 paramètres obligatoires :

Récupération de la valeur de variables

3 fonctions sont disponibles pour récupérer la valeur d'une variable d'un formulaire passée par la méthode GET ou POST ou la valeur d'un cookie.

Récupération de la valeur d'une variable passée par la méthode GET

Prototype : 
    int lecvar_get (char *nom, char *liste, char *result);
Cette fonction comporte 3 paramètres obligatoires :
Code de retour :

Récupération de la valeur d'une variable passée par la méthode POST

Prototype : 
    int lecvar_post (char *nom, char *liste, char *result);
Cette fonction comporte 3 paramètres obligatoires :
Code de retour :

Récupération de la valeur d'un cookie

Prototype : 
    int lecval_cookie (char *nom, char *liste, char *result);
Cette fonction comporte 3 paramètres obligatoires :
Code de retour :

Utilisation d'un fichier HTML présent sur la carte SD

Cette série de fonction lit ligne par ligne le contenu du fichier html qui a été ouvert en lecture par SD.open et envoie éventuellement les lignes lues au navigateur web jusqu'à ce qu'une condition d'arrêt soit réalisée.

Dans le cas d'un site web dynamique, plusieurs appels des fonctions qui suivent seront nécessaire.

Lors du premier appel d'une de ces fonctions, la lecture du fichier html commencera à la première ligne. Lors des appels suivants, elle commencera à la ligne qui suit celle où on s'était arrêté lors de l'utilisation de la fonction précédente.

Lecture d'une ligne du fichier html

Prototype : 
    void lire_ligne (File descfic);
Paramètre obligatoire : Remarque : Le rôle principal de cette fonction est de permettre le fonctionnement des 3 fonctions qui suivent ci-dessous. Toutefois, elle est mise à la disposition des utilisateurs. La ligne lue est stockée dans la variable ligne du fichier trthtml.cpp .

Lecture et envoi vers le navigateur du fichier html jusqu'à la ligne contenant la chaine de caractères cherchée

Prototype : 
    void copie_jusque_chaine (File descfic, EthernetClient client,
                              char *chaine, int cop_derlig = 0);
Paramètres obligatoires : Paramètre optionnel : Par défaut, ou si cop_derlig = 0, la ligne contenant la de caractères cherchée n'est pas envoyée au navigateur web.
Si on veut envoyer cette ligne, le paramètre cop_derlig devra être mis à 1 (ou tout autre valeur non nulle).

Lecture du fichier html jusqu'à la ligne contenant la chaine de caractères cherchée, sans rien envoyer au navigateur

Prototype : 
    void sauter_jusque_chaine (File descfic, char *chaine);
Paramètres obligatoires :

Lecture et envoi vers le navigateur du fichier html jusqu'à la ligne contenant la chaine de caractères cherchée et remplacement de cette chaine par une autre

Prototype : 
    void coprep_chaine (File descfic, EthernetClient client,
                        char *chaineorig, char *chainedest);
Paramètres obligatoires :

Lecture et envoi vers le navigateur de la fin du fichier html

Prototype : 
    void copie_jusque_fin (File descfic, EthernetClient client);
Paramètres obligatoires :

Génération du menu d'une page à partir d'un fichier texte

Génération d'une indentation en début de ligne

Prototype : 
    void indente (EthernetClient client, int indent=4);
Paramètre obligatoire : Paramètre optionnel : Le rôle de cette fonction est essentiellement de permettre à la fonction ajoute_menu de générer du code html bien présenté.

Cette fonction est appelée pour générer des espaces en début de ligne dans le code html. Par défaut, elle génère 4 espaces, mais on peut changer cette valeur grâce au paramètre indent.

Génération du menu de la page html à partir d'un fichier texte

Prototype : 
    void ajoute_menu (char *ficmenu, char *url, EthernetClient client,
                      int indent=4, char *couleur="#FF8000");
Paramètres obligatoires : Paramètres optionnels : Cette fonction génère un menu qui sera commun à toutes les pages du site (ou plusieurs d'entre elles, s'il y a plusieurs menus). Les différents liens du menu sont présentés sur une colonne, comme sur la partie gauche de cette page.

Le fichier ficmenu est un fichier texte. Chaque ligne non vide correspond à un élément du menu.

Chaque ligne du menu commence en colonne 1 par le nom de la page html à afficher. Ensuite, après un ou plusieurs espaces, il y a le texte à afficher dans le menu. Un exemple de fichier est visible dans la deuxième partie de cette page (Version 2 : menu dans un fichier texte).

Le paramètre optionnel indent permet d'indiquer le nombre d'espaces à générer en début de ligne pour une bonne présentation du code html. Par défaut, 4 espaces sont générés au début de chaque ligne du menu.

Pour la page du site qu'on est en train de visualiser, le texte dans le menu apparaît par défaut en orange. Le paramètre optionnel couleur permet de fixer une autre couleur sous la forme d'un code hexadécimal de 6 caractères précédé d'un #.