Serveur HTTP Apache Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

# Module Apache mod_isapi

Description: | Extensions ISAPI dans Apache pour Windows
Statut: | Base
Identificateur de Module: | isapi_module
Fichier Source: | mod_isapi.c
Compatibilité: | Win32 only

### Sommaire

Ce module implémente l'API des extensions du Serveur Internet. Il permet à Apache pour Windows de servir les extensions du Serveur Internet (par exemple les modules .dll ISAPI), compte tenu des restrictions spécifiées.

Les modules d'extension ISAPI (fichiers .dll) sont des modules tiers. Leur auteur n'est pas le Groupe Apache, et nous n'assurons donc pas leur support. Veuillez contacter directement l'auteur d'ISAPI si vous rencontrez des problèmes à l'exécution d'une extension ISAPI. Merci de ne pas soumettre ce genre de problème dans les listes d'Apache ou dans les pages de rapports de bogues.

### Sujets

- Utilisation
- Notes additionnelles
- Journal du programmeur

### Directives

### Traitement des bugs

- Journal des modifications de httpd
- Problèmes connus
- Signaler un bug

## Utilisation

Dans le fichier de configuration du serveur, utilisez la directive `AddHandler` pour associer les fichiers ISAPI au gestionnaire `isapi-handler` à l'aide de l'extension de leur nom de fichier. Pour faire en sorte que tout fichier .dll soit traité en tant qu'extension ISAPI, éditez le fichier httpd.conf et ajoutez les lignes suivantes :

    AddHandler isapi-handler .dll

Dans les versions plus anciennes du serveur Apache, le nom du gestionnaire était `isapi-isa` au lieu de `isapi-handler`. Depuis les versions de développement 2.3 du serveur Apache, `isapi-isa` n'est plus valide, et vous devrez éventuellement modifier votre configuration pour utiliser `isapi-handler` à la place.

Le serveur Apache ne propose aucun moyen de conserver en mémoire un module chargé. Vous pouvez cependant précharger et garder un module spécifique en mémoire en utilisant la syntaxe suivante dans votre httpd.conf :

    ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll

Que vous ayez ou non préchargé une extension ISAPI, ces dernières sont toutes soumises au mêmes restrictions et possèdent les mêmes permissions que les scripts CGI. En d'autres termes, `Options` `ExecCGI` doit être défini pour le répertoire qui contient le fichier .dll ISAPI.

Reportez-vous aux Notes additionnelles et au Journal du programmeur pour plus de détails et une clarification à propos du support spécifique ISAPI fourni par le module `mod_isapi`.

## Notes additionnelles

L'implémentation ISAPI d'Apache se conforme à toutes les spécifications ISAPI 2.0, à l'exception de certaines extensions "spécifiques Microsoft" utilisant des entrées/sorties asynchrones. Le modèle des entrées/sorties d'Apache ne permet pas l'écriture et la lecture asynchrone de la manière dont ISAPI pourrait le faire. Si une extension tente d'utiliser des fonctionnalités non supportées, comme les entrées/sorties asynchrones, un message est enregistré dans le journal des erreurs afin d'aider au débogage. Comme ces messages peuvent devenir envahissants, la directive `ISAPILogNotSupported Off` permet de filter ce bruit de fond.

Si aucune option de configuration particulière n'est spécifiée, certains serveurs, comme Microsoft IIS, chargent l'extension ISAPI dans le serveur et la conservent en mémoire jusqu'à ce que l'utilisation de cette dernière devienne trop élevée. Apache, par contre, charge et décharge réellement l'extension ISAPI chaque fois qu'elle est invoquée, si la directive `ISAPICacheFile` n'a pas été spécifiée. Ce n'est pas très performant, mais le modèle de mémoire d'Apache fait que cette méthode est la plus efficace. De nombreux modules ISAPI présentent des incompatibilités subtiles avec le serveur Apache, et le déchargement de ces modules permet d'assurer la stabilité du serveur.

En outre, gardez à l'esprit que si Apache supporte les extensions ISAPI, il ne supporte pas les filtres ISAPI. Le support des filtres sera peut-être ajouté dans le futur, mais n'a pas encore été planifié.

## Journal du programmeur

Si vous écrivez des modules `mod_isapi` Apache 2.0, vous devez limiter vos appels à `ServerSupportFunction` aux directives suivantes :

`HSE_REQ_SEND_URL_REDIRECT_RESP`
  Redirige l'utilisateur vers une autre adresse.
  Il doit s'agir d'une URL pleinement qualifiée (comme `http://serveur/chemin`).
`HSE_REQ_SEND_URL`
  Redirige l'utilisateur vers une autre adresse.
  Ce ne doit pas être une URL pleinement qualifiée ; la mention du protocole ou du nom du serveur n'est pas autorisée (par exemple, utilisez simplement `/chemin`).
  La redirection n'est pas assurée par le navigateur mais par le serveur lui-même.

  ### Avertissement

  Dans sa documentation récente, Microsoft semble avoir abandonné la distinction entre les deux fonctions `HSE_REQ_SEND_URL`. Apache, quant à lui, continue de les traiter comme deux fonctions distinctes avec des contraintes et des comportements spécifiques.

`HSE_REQ_SEND_RESPONSE_HEADER`
  Apache accepte un corps de réponse après l'en-tête s'il se situe après la ligne vide (deux caractères newline consécutifs) dans la chaîne des arguments d'en-têtes. Ce corps ne doit pas contenir de caractères NULL, car l'argument des en-têtes est lui-même terminé par un caractère NULL.
`HSE_REQ_DONE_WITH_SESSION`
  Apache considère ceci comme sans objet, car la session est fermée lorsque l'extension ISAPI termine son traitement.
`HSE_REQ_MAP_URL_TO_PATH`
  Apache va traduire un nom virtuel en nom physique.
`HSE_APPEND_LOG_PARAMETER`
  Ce paramètre peut intervenir dans un de ces journaux :
  - dans le composant `\"%{isapi-parameter}n\"` d'une directive `CustomLog`
  - dans le composant `%q` avec la directive `ISAPIAppendLogToQuery` `On`
  - dans le journal des erreurs avec la directive `ISAPIAppendLogToErrors` `On`

  La première option, le composant `%{isapi-parameter}n`, est préférable et toujours disponible.

`HSE_REQ_IS_KEEP_CONN`
  retourne le statut négocié Keep-Alive.
`HSE_REQ_SEND_RESPONSE_HEADER_EX`
  se comportera comme indiqué dans le documentation, bien que le drapeau `fKeepConn` soit ignoré.
`HSE_REQ_IS_CONNECTED`
  renverra faux si la requête a été abandonnée.

Apache renvoie `FALSE` pour tout appel non supporté à `ServerSupportFunction`, et `GetLastError` renverra la valeur `ERROR_INVALID_PARAMETER`.

`ReadClient` extrait la partie du corps de la requête qui dépasse le tampon initial (défini par la directive `ISAPIReadAheadBuffer`). En fonction de la définition de la directive `ISAPIReadAheadBuffer` (nombre d'octets à mettre dans le tampon avant d'appeler le gestionnaire ISAPI), les requêtes courtes sont envoyées en entier à l'extension lorsque celle-ci est invoquée. Si la taille de la requête est trop importante, l'extension ISAPI doit faire appel à `ReadClient` pour extraire la totalité du corps de la requête.

`WriteClient` est supporté, mais seulement avec le drapeau `HSE_IO_SYNC` ou le drapeau "aucune option" (valeur `0`). Toute autre requête `WriteClient` sera rejetée avec une valeur de retour `FALSE`, et `GetLastError` renverra la valeur `ERROR_INVALID_PARAMETER`

`GetServerVariable` est supporté, bien que les variables étendues de serveur n'existent pas (comme défini par d'autres serveurs). Toutes les variables d'environnement CGI usuelles d'Apache sont disponibles à partir de `GetServerVariable`, ainsi que les valeurs `ALL_HTTP` et `ALL_RAW`.

Depuis httpd 2.0, `mod_isapi` propose des fonctionnalités supplémentaires introduites dans les versions actualisées de la spécification ISAPI, ainsi qu'une émulation limitée des entrées/sorties asynchrones et la sémantique `TransmitFile`. Apache httpd supporte aussi le préchargement des .dlls ISAPI à des fins de performances.

## Directive ISAPIAppendLogToErrors

Description: | Enregistrement des requêtes `HSE_APPEND_LOG_PARAMETER` de la part des extensions ISAPI dans le journal des erreurs
Syntaxe: | `ISAPIAppendLogToErrors on|off`
Défaut: | `ISAPIAppendLogToErrors off`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet d'enregistrer les requêtes `HSE_APPEND_LOG_PARAMETER` de la part des extensions ISAPI dans le journal des erreurs.

## Directive ISAPIAppendLogToQuery

Description: | Enregistre les requêtes `HSE_APPEND_LOG_PARAMETER` de la part des extensions ISAPI dans la partie arguments de la requête
Syntaxe: | `ISAPIAppendLogToQuery on|off`
Défaut: | `ISAPIAppendLogToQuery on`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet d'enregistrer les requêtes `HSE_APPEND_LOG_PARAMETER` de la part des extensions ISAPI dans la partie arguments de la requête (ajouté au composant `%q` de la directive `CustomLog`).

## Directive ISAPICacheFile

Description: | Fichiers .dll ISAPI devant être chargés au démarrage
Syntaxe: | `ISAPICacheFile chemin-fichier [chemin-fichier] ...`
Contexte: | configuration globale, serveur virtuel
Statut: | Base
Module: | mod_isapi

Cette directive permet de spécifier une liste, séparés par des espaces, de noms de fichiers devant être chargés au démarrage du serveur Apache, et rester en mémoire jusqu'à l'arrêt du serveur. Cette directive peut être répétée pour chaque fichier .dll ISAPI souhaité. Le chemin complet du fichier doit être spécifié. Si le chemin n'est pas absolu, il sera considéré comme relatif au répertoire défini par la directive `ServerRoot`.

## Directive ISAPIFakeAsync

Description: | Emulation du support des entrées/sorties asynchrones pour les appels ISAPI
Syntaxe: | `ISAPIFakeAsync on|off`
Défaut: | `ISAPIFakeAsync off`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_isapi

Lorsquelle est définie à "on", cette directive permet d'émuler le support des entrées/sorties asynchrones pour les appels ISAPI.

## Directive ISAPILogNotSupported

Description: | Journalisation des demandes de fonctionnalités non supportées de la part des extensions ISAPI
Syntaxe: | `ISAPILogNotSupported on|off`
Défaut: | `ISAPILogNotSupported off`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet d'enregistrer dans le journal des erreurs toutes les demandes de fonctionnalités non supportées de la part des extensions ISAPI. Ceci peut aider les administrateurs à décortiquer certains problèmes. Lorsqu'elle a été définie à "on" et si tous les modules ISAPI fonctionnent, elle peut être redéfinie à "off".

## Directive ISAPIReadAheadBuffer

Description: | Taille du tampon de lecture anticipée envoyé aux extensions ISAPI
Syntaxe: | `ISAPIReadAheadBuffer taille`
Défaut: | `ISAPIReadAheadBuffer 49152`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet de définir la taille maximale du tampon de lecture anticipée envoyé aux extensions ISAPI lorsqu'elles sont initialement invoquées. Toute donnée restante doit être extraite en faisant appel à `ReadClient` ; certaines extensions ISAPI peuvent ne pas supporter la fonction `ReadClient`. Pour plus de détails, veuillez vous adresser à l'auteur de l'extension ISAPI.