Module Apache mod_isapi

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 apache2.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 apache2.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.