Ce paragraphe est un résumé de mes notes personnelles, pour que je puisse m’en sortir si je reconsulte ce que j’ai fait dans 6 mois.

Lorsqu’on veut développer un module, il va falloir taper du code. Celui-ci se trouvera à plusieurs endroits possibles (dans le cadre du développement d’un module) :

• lors des phases de lecture de configuration ;
• lors des phases de gestion de la requête client.

Le gestion de la requête client, elle-même, se décompose en plusieurs phases et il faudra préciser parmi laquelle de ces phases, il faudra appeler une routine qu’on aura développé. Le problème c’est que les créateurs d’Apache ont tellement optimisé le code, qu’il y a des rotations qui se font entre les appels des fonctions, alors ils ont décidés de créer, grossièrement, des « groupes » auxquels on pourra associer nos fonctions. Par exemple, si on veut qu’une fonction A soit appelée de manière certaine avant une fonction B, on dit que la fonction A doit appartenir au groupe HOOK_REALLY_FIRST, et la B au groupe HOOK_MIDDLE, qui sera éxécuté forcément après. Il faut bien avoir en tête que si jamais un autre mec fait un module en C dans lequel il a enregistré une fonction A’ dans le groupe HOOK_REALLY_FIRST, il sera possible, que dans certains cas sa fonction A’ soit appelée avant la fonction A, et dans d’autres cas, l’inverse. Ce dont on est sûr, c’est que la B sera éxécutée après les fonctions du groupe HOOK_REALLY_FIRST.

Un et un seul générateur de contenu est éxécuté pour chaque requête HTTP.

N’importe quel module peut s’inscrire en tant que générateur de contenu, en définissant une fonction à appeler. Habituellement, on le fait en activant un « handler » qui peut être configuré via les directives SetHandler et AddHandler dans le fichier de configuration httpd.conf.

Le générateur de contenu par défaut, qui est utilisé lorsqu’aucun générateur n’a été défini, renvoie simplement un fichier, directement récupéré à partir de la requête, dans le système de fichiers de la plateforme sur lequel le serveur tourne.

Les modules qui implémentent des générateurs de contenu sont appelés des générateurs de contenu, en Anglais content generator, ou encore le plus couramment, et c’est le point le plus important, des modules handler.

Lors d’une requête, plusieurs routines (hooks) sont appelés successivement, et c’est à ce moment là que l’on peut, ou non, développer du code dans le module que l’on écrit :

1. post_read_request :
   C’est habituellement le premier hook disponible.
   Il est disponible pour tous les modules qui veulent vraiment gérer la requête le plus tôt possible.
2. translate_name :
   C’est lorsqu’Apache transforme l’URL de la requête en nom de fichier.
   Un module peut placer du code pour ce hook afin d’y mettre sa propre logique de transformation.
   C’est ce que fait le module mod_alias, par exemple.
3. map_to_storage :
   Maintenant que l’URL de la requête a été transformée en nom de fichier, on y applique les directives de configuration des répertoires définies dans httpd.conf. Ce sont les directives <Directory>, <Files> et les ordres dans les fichiers <.htacces>.
   C’est grâce à ce hook qu’Apache applique les options spécifiques à la requête en cours. Il applique les directives de configuration de tous les modules actifs, donc peu de modules ont du code à développer par ici. Le seul module officiel qui fait quelque chose est le module mod_proxy.
4. header_parser :
   C’est ici que l’on inspecte ce qu’il y a dans les en-têtes de la requête.
   On développe un hook très rarement par ici, pour la simple et bonne raison qu’il est possible d’inspecter, utiliser et modifier les en-têtes à n’importe quelle phase, dans un autre hook.
   Le module mod_setenvif est le module standard qui utilise un header_parser pour initialiser certaines variables d’environnement en fonction des entêtes.
5. access_checker :
   C’est ici qu’Apache détermine si l’accès à la ressource demandée est autorisé ou non. Un autre module peut venir s’ajouter ou remplacer le module standard mod_access (httpd 1.x et 2.0) ou mod_authz_host (httpd 2.2), qui implémente les directives Allow/Deny From.
6. check_user_id :
   Si une méthode d’authentification a été activée, alors c’est maintenant qu’elle sera appliquée, et que le champ r->user sera initialisé en conséquence.
   Un module peut implémenter ici une méthode d’authentification.
7. auth_checker :
   Ce hook vérifie si l’utilisateur authentifié a le droit d’effectuer l’opération demandée.
8. type_checker :
   On applique les règles (quand on le peut) en fonction du type MIME et des informations demandées, et on détermine, si ce n’est pas encore fait, le générateur de contenu à utiliser. Les modules stantards qui implémentent ce hook sont mod_negociation et mod_mime (ce dernier définit le type MIME et les informations à partir du type qui a été déterminé, afin choisir le générateur de contenu, en fonction des directives de configuration standards telles que, par exemple, les extensions des noms de fichier)
9. fixups :
   Ce hook très générique offre la possibilité de faire quelque chose après tout ce qui a été fait précédemment, et juste avant l’appel du générateur de contenu.
   C’est l’un des hook les plus implémentés par les développeurs de modules.
10. handler :
    Le fameux et célèbre hook « générateur de contenu !
    Il est entièrement responsable de ce qui est renvoyé au client.
    S’il y a des données envoyées par le client, il est aussi responsable de la lecture et de leur exploitation.
    A l’inverse des autres hooks, durant lesquels plusieurs fonctions de plusieurs modules développés peuvent être appelées, ici, il ne peut y avoir qu’un seul et unique handler. Une seule fonction est appelée, d’un module donné, en fonction de tous les autres modules appelés précédemment.
11. log_transaction :
    Ce hook enregistre dans des fichiers de suivi (des logs), la transaction qui vient de se terminer. Notez bien que c’est après avoir envoyé la réponse au client. Un module peut venir ajouter une fonction ici, ou remplacer la fonction hook standard d’Apache.

NB : tous ces hooks ont une définition de fonction correspondante. Absolument tous. La plupart se ressemblent, mais pas tous ! En général :

• les hooks qui sont appelés pendant la phase de gestion d’une requête ressemblent à :
  static int my_func(request_rec* r) {
...
}
• les hooks qui sont appelés pendant les phases d’initialisation et de configuration ressemblent à :
  static int my_cfg(cmd_parms* cmd, void* cfg, /*args */) {
...
}
• les hooks qui sont appelés pendant les phases de pré-initialisation et de post-configuration ressemblent à :
  static int my_cfg(apr_pool_t* pool, apr_pool_t* plog,
apr_pool_t* ptemp) {
...
}
• le hook qui est appelé pendant la phase de création d’un processus fils ressemble à :
  static void my_child_init(apr_pool_t* pool, server_rec* s) {
...
}
  Sachant que le pool passé en argument est le pool du fils.

Notez qu’il est possible de « créer » ses propres hooks, mais c’est quelque chose de plus complexe et ici on est dans un résumé, pas un cours complet.