1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1584572 -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : Vincent Deffontaines -->
9 Licensed to the Apache Software Foundation (ASF) under one or more
10 contributor license agreements. See the NOTICE file distributed with
11 this work for additional information regarding copyright ownership.
12 The ASF licenses this file to You under the Apache License, Version 2.0
13 (the "License"); you may not use this file except in compliance with
14 the License. You may obtain a copy of the License at
16 http://www.apache.org/licenses/LICENSE-2.0
18 Unless required by applicable law or agreed to in writing, software
19 distributed under the License is distributed on an "AS IS" BASIS,
20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 See the License for the specific language governing permissions and
22 limitations under the License.
25 <modulesynopsis metafile="mod_isapi.xml.meta">
27 <name>mod_isapi</name>
28 <description>Extensions ISAPI dans Apache pour Windows</description>
30 <sourcefile>mod_isapi.c</sourcefile>
31 <identifier>isapi_module</identifier>
32 <compatibility>Win32 only</compatibility>
35 <p>Ce module implémente l'API des extensions du Serveur Internet. Il
36 permet à Apache pour Windows de servir les extensions du Serveur
37 Internet (par exemple les modules .dll ISAPI), compte tenu des
38 restrictions spécifiées.</p>
40 <p>Les modules d'extension ISAPI (fichiers .dll) sont des modules
41 tiers. Leur auteur n'est pas le Groupe Apache, et nous n'assurons
42 donc pas leur support. Veuillez contacter directement l'auteur
43 d'ISAPI si vous rencontrez des problèmes à l'exécution d'une
44 extension ISAPI. <strong>Merci de <em>ne pas</em> soumettre ce genre
45 de problème dans les listes d'Apache ou dans les pages de rapports
46 de bogues.</strong></p>
49 <section id="usage"><title>Utilisation</title>
51 <p>Dans le fichier de configuration du serveur, utilisez la
52 directive <directive module="mod_mime">AddHandler</directive> pour
53 associer les fichiers ISAPI au gestionnaire
54 <code>isapi-handler</code> à l'aide de l'extension de leur nom de
55 fichier. Pour faire en sorte que tout fichier .dll soit traité en
56 tant qu'extension ISAPI, éditez le fichier httpd.conf et ajoutez les
57 lignes suivantes :</p>
58 <highlight language="config">
59 AddHandler isapi-handler .dll
62 <note>Dans les versions plus anciennes du serveur Apache, le nom du
63 gestionnaire était <code>isapi-isa</code> au lieu de
64 <code>isapi-handler</code>. Depuis les versions de développement 2.3
65 du serveur Apache, <code>isapi-isa</code> n'est plus valide, et vous
66 devrez éventuellement modifier votre configuration pour utiliser
67 <code>isapi-handler</code> à la place.</note>
69 <p>Le serveur Apache ne propose aucun moyen de conserver en mémoire
70 un module chargé. Vous pouvez cependant précharger et garder un
71 module spécifique en mémoire en utilisant la syntaxe suivante dans
72 votre httpd.conf :</p>
73 <highlight language="config">
74 ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
77 <p>Que vous ayez ou non préchargé une extension ISAPI, ces dernières
78 sont toutes soumises au mêmes restrictions et possèdent les mêmes
79 permissions que les scripts CGI. En d'autres termes, <directive
80 module="core">Options</directive> <code>ExecCGI</code> doit être
81 défini pour le répertoire qui contient le fichier .dll ISAPI.</p>
83 <p>Reportez-vous aux <a href="#notes">Notes additionnelles</a> et au
84 <a href="#journal">Journal du programmeur</a> pour plus de détails
85 et une clarification à propos du support spécifique ISAPI fourni par
86 le module <module>mod_isapi</module>.</p>
89 <section id="notes"><title>Notes additionnelles</title>
91 <p>L'implémentation ISAPI d'Apache se conforme à toutes les
92 spécifications ISAPI 2.0, à l'exception de certaines extensions
93 "spécifiques Microsoft" utilisant des entrées/sorties asynchrones.
94 Le modèle des entrées/sorties d'Apache ne permet pas l'écriture et
95 la lecture asynchrone de la manière dont ISAPI pourrait le faire. Si
96 une extension tente d'utiliser des fonctionnalités non supportées,
97 comme les entrées/sorties asynchrones, un message est enregistré
98 dans le journal des erreurs afin d'aider au débogage. Comme ces
99 messages peuvent devenir envahissants, la directive
100 <code>ISAPILogNotSupported Off</code> permet de filter ce bruit de
103 <p>Si aucune option de configuration particulière n'est spécifiée,
104 certains serveurs, comme Microsoft IIS, chargent l'extension ISAPI
105 dans le serveur et la conservent en mémoire jusqu'à ce que
106 l'utilisation de cette dernière devienne trop élevée. Apache, par
107 contre, charge et décharge réellement l'extension ISAPI chaque fois
108 qu'elle est invoquée, si la directive <directive
109 module="mod_isapi">ISAPICacheFile</directive> n'a pas été spécifiée.
110 Ce n'est pas très performant, mais le modèle de mémoire d'Apache
111 fait que cette méthode est la plus efficace. De nombreux modules
112 ISAPI présentent des incompatibilités subtiles avec le serveur
113 Apache, et le déchargement de ces modules permet d'assurer la
114 stabilité du serveur.</p>
116 <p>En outre, gardez à l'esprit que si Apache supporte les extensions
117 ISAPI, il <strong>ne supporte pas les filtres ISAPI</strong>. Le
118 support des filtres sera peut-être ajouté dans le futur, mais n'a
119 pas encore été planifié.</p>
122 <section id="journal"><title>Journal du programmeur</title>
124 <p>Si vous écrivez des modules <module>mod_isapi</module> Apache
125 2.0, vous devez limiter vos appels à
126 <code>ServerSupportFunction</code> aux directives suivantes :</p>
129 <dt><code>HSE_REQ_SEND_URL_REDIRECT_RESP</code></dt>
130 <dd>Redirige l'utilisateur vers une autre adresse.<br />
131 Il doit s'agir d'une URL pleinement qualifiée (comme
132 <code>http://serveur/chemin</code>).</dd>
134 <dt><code>HSE_REQ_SEND_URL</code></dt>
135 <dd>Redirige l'utilisateur vers une autre adresse.<br />
136 Ce ne doit pas être une URL pleinement qualifiée ; la mention du
137 protocole ou du nom du serveur n'est pas autorisée (par exemple,
138 utilisez simplement <code>/chemin</code>).<br />
139 La redirection n'est pas assurée par le navigateur mais par le
140 serveur lui-même.<br />
141 <note type="warning"><title>Avertissement</title>
142 <p>Dans sa documentation récente, Microsoft semble avoir
143 abandonné la distinction entre les deux fonctions
144 <code>HSE_REQ_SEND_URL</code>. Apache, quant à lui, continue de
145 les traiter comme deux fonctions distinctes avec des contraintes
146 et des comportements spécifiques.</p>
149 <dt><code>HSE_REQ_SEND_RESPONSE_HEADER</code></dt>
150 <dd>Apache accepte un corps de réponse après l'en-tête s'il se
151 situe après la ligne vide (deux caractères newline consécutifs)
152 dans la chaîne des arguments d'en-têtes. Ce corps ne doit pas
153 contenir de caractères NULL, car l'argument des en-têtes est
154 lui-même terminé par un caractère NULL.</dd>
156 <dt><code>HSE_REQ_DONE_WITH_SESSION</code></dt>
157 <dd>Apache considère ceci comme sans objet, car la session est
158 fermée lorsque l'extension ISAPI termine son traitement.</dd>
160 <dt><code>HSE_REQ_MAP_URL_TO_PATH</code></dt>
161 <dd>Apache va traduire un nom virtuel en nom physique.</dd>
163 <dt><code>HSE_APPEND_LOG_PARAMETER</code></dt>
165 Ce paramètre peut intervenir dans un de ces journaux :
168 <li>dans le composant <code>\"%{isapi-parameter}n\"</code>
169 d'une directive <directive module="mod_log_config">CustomLog</directive></li>
171 <li>dans le composant <code>%q</code> avec la directive
173 module="mod_isapi">ISAPIAppendLogToQuery</directive>
176 <li>dans le journal des erreurs avec la directive <directive
177 module="mod_isapi">ISAPIAppendLogToErrors</directive>
181 <p>La première option, le composant
182 <code>%{isapi-parameter}n</code>, est préférable et toujours
186 <dt><code>HSE_REQ_IS_KEEP_CONN</code></dt>
187 <dd>retourne le statut négocié Keep-Alive.</dd>
189 <dt><code>HSE_REQ_SEND_RESPONSE_HEADER_EX</code></dt>
190 <dd>se comportera comme indiqué dans le documentation, bien que le
191 drapeau <code>fKeepConn</code> soit ignoré.</dd>
193 <dt><code>HSE_REQ_IS_CONNECTED</code></dt>
194 <dd>renverra faux si la requête a été abandonnée.</dd>
197 <p>Apache renvoie <code>FALSE</code> pour tout appel non supporté à
198 <code>ServerSupportFunction</code>, et <code>GetLastError</code>
199 renverra la valeur <code>ERROR_INVALID_PARAMETER</code>.</p>
201 <p><code>ReadClient</code> extrait la partie du corps de la requête
202 qui dépasse le tampon initial (défini par la directive <directive
203 module="mod_isapi">ISAPIReadAheadBuffer</directive>). En fonction de
204 la définition de la directive
205 <directive>ISAPIReadAheadBuffer</directive> (nombre d'octets à
206 mettre dans le tampon avant d'appeler le gestionnaire ISAPI), les
207 requêtes courtes sont envoyées en entier à l'extension lorsque
208 celle-ci est invoquée. Si la taille de la requête est trop
209 importante, l'extension ISAPI doit faire appel à
210 <code>ReadClient</code> pour extraire la totalité du corps de la
213 <p><code>WriteClient</code> est supporté, mais seulement avec le
214 drapeau <code>HSE_IO_SYNC</code> ou le drapeau "aucune option"
215 (valeur <code>0</code>). Toute autre requête
216 <code>WriteClient</code> sera rejetée avec une valeur de retour
217 <code>FALSE</code>, et <code>GetLastError</code> renverra la valeur
218 <code>ERROR_INVALID_PARAMETER</code></p>
220 <p><code>GetServerVariable</code> est supporté, bien que les
221 variables étendues de serveur n'existent pas (comme défini par
222 d'autres serveurs). Toutes les variables d'environnement CGI
223 usuelles d'Apache sont disponibles à partir de
224 <code>GetServerVariable</code>, ainsi que les valeurs
225 <code>ALL_HTTP</code> et <code>ALL_RAW</code>.</p>
227 <p>Depuis httpd 2.0, <module>mod_isapi</module> propose des
228 fonctionnalités supplémentaires introduites dans les versions
229 actualisées de la spécification ISAPI, ainsi qu'une émulation
230 limitée des entrées/sorties asynchrones et la sémantique
231 <code>TransmitFile</code>. Apache httpd supporte aussi le préchargement
232 des .dlls ISAPI à des fins de performances.</p>
236 <name>ISAPICacheFile</name>
237 <description>Fichiers .dll ISAPI devant être chargés au
238 démarrage</description>
239 <syntax>ISAPICacheFile <var>chemin-fichier</var>
240 [<var>chemin-fichier</var>]
242 <contextlist><context>server config</context><context>virtual host</context>
246 <p>Cette directive permet de spécifier une liste, séparés par des
247 espaces, de noms de fichiers devant être chargés au démarrage
248 du serveur Apache, et rester en mémoire jusqu'à l'arrêt du serveur.
249 Cette directive peut être répétée pour chaque fichier .dll ISAPI
250 souhaité. Le chemin complet du fichier doit être spécifié. Si le
251 chemin n'est pas absolu, il sera considéré comme relatif au
252 répertoire défini par la directive <directive
253 module="core">ServerRoot</directive>.</p>
258 <name>ISAPIReadAheadBuffer</name>
259 <description>Taille du tampon de lecture anticipée envoyé aux extensions
261 <syntax>ISAPIReadAheadBuffer <var>taille</var></syntax>
262 <default>ISAPIReadAheadBuffer 49152</default>
263 <contextlist><context>server config</context><context>virtual host</context>
264 <context>directory</context><context>.htaccess</context></contextlist>
265 <override>FileInfo</override>
268 <p>Cette directive permet de définir la taille maximale du tampon de
269 lecture anticipée envoyé aux extensions ISAPI lorsqu'elles sont
270 initialement invoquées. Toute donnée restante doit être extraite en
271 faisant appel à <code>ReadClient</code> ; certaines extensions ISAPI
272 peuvent ne pas supporter la fonction <code>ReadClient</code>.
273 Pour plus de détails, veuillez vous adresser à l'auteur de
274 l'extension ISAPI.</p>
279 <name>ISAPILogNotSupported</name>
280 <description>Journalisation des demandes de fonctionnalités non
281 supportées de la part des extensions ISAPI</description>
282 <syntax>ISAPILogNotSupported on|off</syntax>
283 <default>ISAPILogNotSupported off</default>
284 <contextlist><context>server config</context><context>virtual host</context>
285 <context>directory</context><context>.htaccess</context></contextlist>
286 <override>FileInfo</override>
289 <p>Cette directive permet d'enregistrer dans le journal des erreurs
290 toutes les demandes de fonctionnalités non supportées de la part des
291 extensions ISAPI. Ceci peut aider les administrateurs à décortiquer
292 certains problèmes. Lorsqu'elle a été définie à "on" et si tous les
293 modules ISAPI fonctionnent, elle peut être redéfinie à "off".</p>
298 <name>ISAPIAppendLogToErrors</name>
299 <description>Enregistrement des requêtes
300 <code>HSE_APPEND_LOG_PARAMETER</code> de la part des extensions ISAPI
301 dans le journal des erreurs</description>
302 <syntax>ISAPIAppendLogToErrors on|off</syntax>
303 <default>ISAPIAppendLogToErrors off</default>
304 <contextlist><context>server config</context><context>virtual host</context>
305 <context>directory</context><context>.htaccess</context></contextlist>
306 <override>FileInfo</override>
309 <p>Cette directive permet d'enregistrer les requêtes
310 <code>HSE_APPEND_LOG_PARAMETER</code> de la part des extensions
311 ISAPI dans le journal des erreurs.</p>
316 <name>ISAPIAppendLogToQuery</name>
317 <description>Enregistre les requêtes
318 <code>HSE_APPEND_LOG_PARAMETER</code> de la part des extensions ISAPI
319 dans la partie arguments de la requête</description>
320 <syntax>ISAPIAppendLogToQuery on|off</syntax>
321 <default>ISAPIAppendLogToQuery on</default>
322 <contextlist><context>server config</context><context>virtual host</context>
323 <context>directory</context><context>.htaccess</context></contextlist>
324 <override>FileInfo</override>
327 <p>Cette directive permet d'enregistrer les requêtes
328 <code>HSE_APPEND_LOG_PARAMETER</code> de la part des extensions
329 ISAPI dans la partie arguments de la requête (ajouté au composant
330 <code>%q</code> de la directive <directive
331 module="mod_log_config">CustomLog</directive>).</p>
336 <name>ISAPIFakeAsync</name>
337 <description>Emulation du support des entrées/sorties asynchrones pour
338 les appels ISAPI</description>
339 <syntax>ISAPIFakeAsync on|off</syntax>
340 <default>ISAPIFakeAsync off</default>
341 <contextlist><context>server config</context><context>virtual host</context>
342 <context>directory</context><context>.htaccess</context></contextlist>
343 <override>FileInfo</override>
346 <p>Lorsquelle est définie à "on", cette directive permet d'émuler le
347 support des entrées/sorties asynchrones pour les appels ISAPI.</p>