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

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

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

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

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

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

Directive ISAPILogNotSupported

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

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.