XMLHttpRequest
Copyright © 2007 W3C® (MIT, ERCIM, Keio),Tous droits réservés. Les règles du W3C pour les responsabilité, nom de marque et usage du document sont applicables.
La spécification de l'objet XMLHttpRequest
définit
une API (Interface d'application) qui procure au script client des fonctionnalités
pour transférer des données entre un client et un serveur.
Cette section décrit le statut de ce document au moment de sa publication. D'autres documents peuvent remplacer ce document. Une liste des publications W3C en cours et la dernière révision de ce compte-rendu technique peuvent être trouvés dans l' index des compte-rendus techniques W3C à http://www.w3.org/TR/.
C'est la version du 26 Octobre 2007 du Document de Travail de la spécification
de l'objet XMLHttpRequest
. Envoyez s'il vous plaît vos
commentaires à public-webapi@w3.org
(archives)
avec soit [XHR] ou [XMLHttpRequest] au
début de la ligne du sujet.
Ce document est produit par le groupe de travail API Web (Web APIs Working Group), qui fait partie de l'activité clients web riches (Rich Web Clients Activity) dans le domaine d'interaction (Interaction Domain) W3C. Les modifications faites sur ce document peuvent être trouvée sur le serveur CVS public du W3C.
La publication en tant que Document de Travail n'implique pas l'approbation par les membres du W3C. C'est un document de travail et il peut être mis à jour, remplacé ou rendu obsolète par d'autres documents à tout moment. Il serait inapproprié de citer ce document autrement que comme un travail en cours.
Ce document a été produit par un groupe opérant sous
la politique
de brevet du W3C du 5 février 2004. Le W3C maintient une liste publique
de toutes divulgations de brevet faites en relation avec les productions
du groupe; cette page inclut également les instructions pour divulguer
un brevet. Une personne ayant connaissance d'un brevet dont il croit qu'il
contient des Revendications
Essentielles vis à vis de cette spécification doit divulguer
cette information, comme le demande la section
6 de politique de brevet du W3C.
Cette section n'est pas normative.
L'objet XMLHttpRequest
implémente
une interface mise à disposition par un interpréteur de scripts
qui permet aux scripts d'accomplir les fonctionnalités de client HTTP,
telles que soumettre des données de formulaire ou le chargement de
données à partir d'un serveur.
Le nom de l'objet est XMLHttpRequest
pour la compatibilité avec le web, bien que chaque composant du nom
puisse induire en erreur. Premièrement, l'objet supporte tout format
basé sur du texte, incluant XML. Deuxièmement, il peut être
utilisé à la fois pour faire des requêtes sous HTTP ou
HTTPS (quelques implémentations supportent des protocoles en plus de
HTTP et HTTPS, mais cette fonctionnalité n'est pas couverte par cette
spécification). Finalement, il supporte "requête" au
sens large du terme, puisqu'il concerne HTTP; nommément toute activité
en rapport avec les requêtes HTTP ou réponses pour les méthodes
HTTP définies.
Cette section n'est pas normative.
Différents exemples [ECMAScript] sont listés dans le contenu de la spécification. En outre, vous pouvez en trouver quelques uns ci-dessous.
Un simple code pour faire quelque chose avec les données d'un document XML récupéré sur le réseau:
function test(data) {
// prendre en compte les données
}
function handler() {
if(this.readyState == 4 && this.status == 200) {
// jusque là cela va
if(this.responseXML != null && this.responseXML.getElementById('test').firstChild.data)
// succès!
test(this.responseXML.getElementById('test').firstChild.data);
else
test(null);
} else if (this.readyState == 4 && this.status != 200) {
// demandé la mauvaise page ou problème de réseau...
test(null);
}
}
var client = new XMLHttpRequest();
client.onreadystatechange = handler;
client.open("GET", "test.xml");
client.send();
Si vous voulez juste passer un message au serveur:
function log(message) {
var client = new XMLHttpRequest();
client.open("POST", "/log");
client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
client.send(message);
}
Ou si vous voulez tester le statut d'un document sur le serveur:
function fetchStatus(address) {
var client = new XMLHttpRequest();
client.onreadystatechange = function() {
// en cas d'erreur du réseau les résultats obtenus ne seraient pas fiables
if(this.readyState == 4)
returnStatus(this.status);
}
client.open("HEAD", address);
client.send();
}
Tout dans cette spécification est normatif, à l'exception des diagrammes, exemples, notes et sections notées comme n'étant pas normatifs.
Les mots clés doit, ne doit pas, requis, va, ne va pas, devrait, ne devrait pas, recommandé, peut et optionnel dans le document doivent être interprétés comme décrit en RFC 2119 [RFC2119].
Cette spécification définit les classes de produits suivantes:
Un agent utilisateur doit se comporter tel que décrit dans cette spécification pour être considéré comme conforme.
Si l'agent utilisateur ne reconnaît pas XML (incluant la reconnaissance
des espaces de nom) le corps d'entité
de réponse XML must (toujours ) être
null
.
Les agents utilisateurs peuvent optimiser tout algorithme donné dans cette spécification, du moment que le résultat final ne peut se distinguer du résultat qui aurait été obtenu par les algorithmes de la spécification. (Les algorithmes dans cette spécification sont généralement écrits dans une optique de clarté plutôt que d'efficacité.)
Cette spécification utilise à la fois les termes "agent(s) utilisateur(s) conforme(s)" et "agent(s) utilisateur(s)" pour se référer à cette classe de produits.
Un agent utilisateur qui est un agent utilisateur conforme et qui supporte aussi XML (incluant la reconnaissance des espaces de noms).
Cette spécification dépend de plusieurs autres spécifications sous-jacentes.
Les agents utilisateurs conformes doivent reconnaître quelque version de DOM Events (Evénements DOM) et DOM Core (coeur de DOM) parce que cette spécification utilise quelques unes des fonctionnalités définies dans ces spécifications. [DOM3Events] [DOM3Core]
Ils doivent aussi reconnaître quelque version de Window Object (Objet Fenêtre) parce que quelques unes des fonctionnalités dans cette spécification en dépendent. [Window]
Les agents utilisateurs conformes doivent reconnaître
quelque version du protocole HTTP. L'agent utilisateur devrait reconnaître
toutes méthodes HTTP qui correspondent à la
production de Method
et doit
aussi supporter les méthodes:
GET
POST
HEAD
PUT
DELETE
OPTIONS
Les agents utilisateurs XML conformes doivent reconnaître XML (incluant les espaces de noms). [XML] [XMLNS]
Il y a une correspondance insensible à la casse des chaînes s1 et s2 si après mise en majuscules, les deux chaînes (en faisant correspondre a-z à A-Z) s'avèrent identique.
Les extensions des APIs (classes et méthodes) définies dans cette spécification sont fortement découragées. Les agents utilisateurs, Groupes de Travail et autres parties intéressées devraient discuter d'extensions sur un forum public concerné, comme celui du public-webapi@w3.org.
XMLHttpRequest
L'objet XMLHttpRequest
peut être
utilisé pour permettre aux scripts de se connecter informatiquement
à leur serveur d'origine par HTTP.
Les objets implémentant l'interface XMLHttpRequest
doivent aussi implémenter l'interface EventTarget
[DOM3Events].
Les objets implémentant l'interface Window
doivent
fournir un constructeur XMLHttpRequest()
. [Window]
En ECMAScript cela peut être utilisé de la façon
suivante :
var client = new XMLHttpRequest();
Quand le constructeur XMLHttpRequest()
est invoqué,
un pointeur persistant associé à l'objet Window
doit être stocké sur l'objet nouvellement créé.
C'est le pointeur Window
. L'objet Window
associé est celui où le constructeur XMLHttpRequest
a été invoqué. Ce pointeur
doit persister même après que le contexte
de navigation dans lequel la Fenêtre
se trouvait
est supprimé (quand on le supprime du contexte de navigation parent,
par exemple).
Le terme "contexte de navigation" est défini dans la spécification Window Object 1.0. [Window].
Si win
est un objet Window
le client
aura un pointeur sur win
dans l'exemple suivant:
var client = new win.XMLHttpRequest()
interface XMLHttpRequest { attribut EventListener onreadystatechange; // état const unsigned short UNSENT = 0; const unsigned short OPEN = 1; const unsigned short SENT = 2; const unsigned short LOADING = 3; const unsigned short DONE = 4; readonly attribute unsigned short readyState; // requête void open(en méthode DOMString, en uri DOMString); void open(en méthode DOMString, en uri DOMString, en boolean async); void open(en méthode DOMString, en uri DOMString, en boolean async, en utilisateur DOMString); void open(en méthode DOMString, en uri DOMString, en boolean async, en utilisateur DOMString, mot-de-passe DOMString); void setRequestHeader(en en-tête DOMString, en valeur DOMString) raises(DOMException); void send(en donnée DOMString); void send(en donnée Document); void abort(); //réponse DOMString getAllResponseHeaders(); DOMString getResponseHeader(en en-tête DOMString); attribut DOMString responseText; attribut Document responseXML; attribut unsigned short status; attribut DOMString statusText; };
L'objet XMLHttpRequest
peut avoir cinq états: UNSENT, OPEN, SENT,
LOADING et DONE. L'état courant est donné par l'attribut readyState
.
Les définitions de méthodes ci-dessous définissent
quand une transition d'état est opérée.
Lorsqu'il est construit, l'objet XMLHttpRequest
doit être dans l'état UNSENT. Cet état
est représenté par la constante UNSENT
,
dont la valeur est 0
.
L'état OPEN est l'état de l'objet lorsque la méthode
open()
a été invoquée
avec succès. Durant cet état les en-têtes de requêtes
peuvent être assignés par l'utilisation de setRequestHeader()
et la requête peut être faite en utilisant send()
.
Cet état est représenté par la constante OPEN
, dont la valeur est 1
.
Durant l'état OPEN il y a un drapeau send()
qui peut valoir soit "true" ou "false" (vrai ou faux). L'état
initiale du drapeau send()
est "false".
L'état SENT est l'état de l'objet quand l'agent utilisateur
est mis au courant de la requêtre avec succès. Cet état
est représenté par la constant SENT
,
dont la valeur est 2
.
L'état LOADING est l'état de l'objet quand tous les en-têtes
HTTP ont été reçus. L'objet normalement reste dans
cet état jusqu'à ce que le corps du message complet (s'il
en est) ait été reçu. L'état est représenté
par la constante LOADING
, dont la valeur est 3
.
L'état DONE est l'état de l'objet où soit le transfert
des données s'est terminé ou quelquechose d'anormal s'est
produit durant le tranfert (redirections infinies par exemple). L'état
est représenté par la constant DONE
,
dont la valeur est 4
.
Le corps d'entité response est le fragment du corps d'entité reçu jusque là (état LOADING) ou le corps d'entité complet (état DONE). S'il n'y a pas de corps d'entité le corps d'entité response entity body vaut "null".
Le corps d'entité response text
est soit une DOMString
représentant le corps
d'entité response ou null
. La valeur du corps d'entité
response text doit être déterminé
en exécutant l'algorithme suivant:
Si le corps d'entité response est "null" retourner null
et terminer ces étapes.
Faire que le charset soit "null".
S'il n'y a pas d'en-tête Content-Type
ou s'il y
a un en-tête Content-Type
qui contiennent un type
MIME qui est text/xml
, application/xml
ou
se termine en +xml
(en ignorant tout paramètre)
utiliser l'ensemble de règles mise en avant par la spécification
XML pour déterminer l'encodage des caractères. Faire que
charset soit l'encodage de caractères déterminé.
S'il y a un en-tête Content-Type
contant un type
MIME text/html
taper l'ensemble de règles suivantes
mise en avant dans la spécification HTML pour déterminer
l'encodage des caractères. Faire que charset soit
l'encodage de caractères déterminé.
Si le type MIME Content-Type
contient un paramètres
charset
et que charset soit "null" faire que
charset soit la valeur de ce paramètre.
L'algorithme décrit par les spécifications
XML et HTML prend déjà en compte Content-Type
.
Si charset est alors "null", pour chaque ligne dans la table qui suit, en partant de la première et en descendant, si le début du corps d'entité (bytes) est égal ou plus grand que le nombre d'octets dans la première colonne et que les premiers octets de bytes correspondent aux octets donnés dans la première colonne, alors faites que charset soit l'encodage donné dans la cellule de la seconde colonne sur cette ligne. Quand un encodage est déterminé ou quand aucun ne l'est aller à l'étape suivante:
Octets en Hexadécimal | Description |
---|---|
00 00 FE FF | UTF-32BE BOM |
FF FE 00 00 | UTF-32LE BOM |
FE FF | UTF-16BE BOM |
FF FE | UTF-16LE BOM |
EF BB BF | UTF-8 BOM |
Si charset est "null" faire que charset soit UTF-8.
Retourner le résultat du décodage du corps d'entité
response en utilisant charset. Ou, si cela échoue,
retourner null
.
Le corps d'entité response XML
est soit un Document
représentant le corps
d'entité response ou null
et est déterminé
en exécutant l'algorithme suivant (la valeur retournée est
sa valeur):
Si le corps d'entité response est "null" terminer étapes
et retourner null
.
Si un Content-Type
est présent et ne contient pas
de type MIME (en ignorant tout paramètre) qui soit text/xml
,
application/xml
ou finisse en +xml
terminer ces étapes et retourner null
. (Ne pas terminer
ces étapes s'il n'y a pas d'en-tête Content-Type
du tout.)
Parser le corps d'entité response en suivant les règles
des spécifications XML. Faire que le résultat soit le
document parsed. Si cela échoue (encodage de caractères
non supporté, erreur de bonne formation d'espace de nom et cetera)
terminer ces étapes et retourner null
. [XML]
[XMLNS]
Retourner un objet implémentant l'interface Document
représentant le document parsé.
onreadystatechange
de type EventListener
Un attribut qui prend un EventListener
comme valeur et qui
doit être invoqué ainsi que tout autre
récepteur d'évènement approprié qui soit enregistré
sur cet objet quand un événement readystatechange
lui est envoyé pendant la phase ou l'évènement est
pris en charge par les noeuds parent de l'arborescence DOM. Sa valeur
initiale doit être null
.
readyState
de type unsigned short
,
lecture seuleL'attribut doit être la valeur de la constante correspondant à l'état actuel de l'objet.
open(méthode,
url, async, utilisateur, mot-de-passe)
Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes (à moins qu'on qu'il ne soit indiqué de faire autrement):
Si l'argument méthode ne correspond par à
une production de Method
définie en section 5.1.1 de la RFC 2616 lever un exception
SYNTAX_ERR
et terminer ces étapes. [RFC2616]
Si la méthode donnée n'est pas supportée
pour des raisons de sécurité l'agent utilisateur devrait
lever une exception SECURITY_ERR
et terminer ces étapes.
Faire que la méthode stockée soit méthode.
Si méthode correspond
sans égard à la casse à GET
, POST
,
HEAD
, PUT
, DELETE
ou OPTIONS
la convertir en son équivalent majuscules (en faisant correspondre
a-z à A-Z) et assigner la méthode stockée
au résultat.
Abandonner l'identifieur de fragment (s'il en est) de url et faire que l'url stockée soit le résultat de cette opération.
Si l'url stockée est une référence
relative la résoudre en utilisant la valeur courante de l'attribut
baseURI
de l'objet Document
associé
actuellement avec le pointeur de Window
. Si cela échoue, lever une exception SYNTAX_ERR
et terminer ces étapes.
Si l'url stockée contient un schéma non supporté,
lever une NOT_SUPPORTED_ERR
et terminer ces étapes.
Si le format "utilisateur:mot-de-passe"
dans la production
userinfo
définie en section 3.2.1 de la RFC 3986
n'est pas reconnu, le schéma concerné et que l'url
stockée contient ce format, lever un SYNTAX_ERR
et terminer ces étapes. [RFC3986]
Si l'url stockée contient le format "utilisateur:mot-de-passe"
faire que l'utilisateur stocké soit la partie utilisateur
et que le mot de passe stocké soit la partie mot-de-passe.
Si l'url stockée contient juste le format "user"
faire que l'utilisateur stocké soit la partie utilisateur.
Si l'url stockée n'a pas la même origine (que
le site) l'agent utilisateur devrait lever une exception
SECURITY_ERR
et terminer ces étapes.
La spécification ne définit pas ce qui constitue une origine exogène. Il n'est pas prévu que ce qui constitue une origine exogène soit défini avant que cette spécification n'atteigne le statut de Recommandation W3C au moyen d'une référence à la spécification qui le définisse.
Assigner à async la valeur de l'argument async
ou true
si s'il était omis.
Si l'argument utilisateur n'�tait pas omis et que la syntaxe
ne corresponde pas à ce que spécifie le schéma
d'authentification, lever une exception SYNTAX_ERR
et terminer
ces étapes.
Si l'argument utilisateur n'�tait pas omis et qu'il n'est
pas null
assigner à l'utilisateur stocké
l' utilisateur encodé en utilisant l'encodage spécifié
dans le schéma d'authentification concerné ou UTF-8 si
le schéma échoue à spécifier un encodage.
Cette étape remplace tout utilisateur qui aurait été assigné par l'argument d'url.
Si l'argument utilisateur n'�tait pas omis et qu'il soit
null
supprimé l'utilisateur stocké.
Si l'argument mot de passe n'était pas omis et que
sa syntaxe ne corresponde par à ce qui est spécifié
by le schéma d'authentification concerné lever une exception
SYNTAX_ERR
et terminer ces étapes.
Si l'argument mot de passe n'était pas omis et n'est
pas null
assigner mot de passe a mot de
passe stocké encodé en utilisant l'encodage spécifié
dans le schéma d'authentification concerné ou UTF-8 si
le schéma échoue à spécifier un encodage.
Si l'argument mot de passe n'était pas omis et est
null
supprimer le mot de passe stocké.
Abandonner l'algorithme
send()
, assigner "null" au corps
d'entité response et réinitialiser la liste d'en-têtes
de requête.
L'agent utilisateur devrait abandonner toute activité sur le réseau dont l'objet soit responsable.
Basculer l'objet sur l'état OPEN,
assigner "false" au drapeau send()
et ensuite envoyer en mode synchrone une évènement à
readystatechange
sur
l'objet et revenir de l'appel de la méthode.
Une version future ou une extension de cette spécification aura plus de chances de définir une façon de faire des requêtes entre sites.
setRequestHeader(en-tête, valeur)
Chaque requête dispose d'une liste d'en-tête de requête avec des valeurs associées. Cette méthode peut être utilisée pour manipuler ces valeurs et placer de nouveaux en-têtes de requêtes.
Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes (à moins qu'on qu'il ne soit indiqué de faire autrement):
Si l'état de l'objet n'est pas OPEN lever une exception INVALID_STATE_ERR
et terminer
ces étapes.
Si le drapeau send()
est "true"
lever une exception INVALID_STATE_ERR
et terminer ces étapes.
Si l'argument en-tête ne correspond pas à la
production nom-de-champ
comme
défini par la section 4.2 de RFC 2616 ou s'il est null
lever une exception SYNTAX_ERR
et terminer ces étapes.
[RFC2616]
Si l'argument valeur est null
terminer ces
étapes. (Ne pas lever d'exception.)
Si l'argument valeur ne correspond pas à la production
nom-de-champ
comme défini par la section
4.2 de RFC 2616 lever une exception SYNTAX_ERR
et terminer
ces étapes. [RFC2616]
Pour des raisons de sécurité ces étapes devraient se terminer si l'argument en-tête correspond sans égard à la casse à un des en-têtes qui suit:
Accept-Charset
Accept-Encoding
Connection
Content-Length
Content-Transfer-Encoding
Date
Expect
Host
Keep-Alive
Referer
TE
Trailer
Transfer-Encoding
Upgrade
Via
Si l'argument en-tête n'est pas dans la liste des en-têtes de requête ajouter l'en-tête avec sa valeur associée à la liste et terminer ces étapes.
Si l'argument en-tête est dans la liste des en-têtes de requête soit utiliser de multiples en-têtes, combiner les valeurs ou utiliser une combinaison de ceux-ci (section 4.2, RFC 2616). [RFC2616]
Voir aussi la méthode send()
concernant la prise en charge par les agents des en-têtes pour la
mise en cache, l'authentification, les proxies, et cookies.
// Le script suivant: var client = new XMLHttpRequest(); client.open('GET', 'demo.cgi'); client.setRequestHeader('X-Test', 'un'); client.setRequestHeader('X-Test', 'deux'); client.send(null); // ...devrait avoir pour résultat que l'en-tête suivant soit envoyé: ... X-Test: un, deux ...
send(données)
La méthode send()
lance la
requête et son argument optionnel fournit le corps
d'entité. Les auteurs sont fortement encouragés à
s'assurer qu'ils ont spécifié l'en-tête Content-Type
par setRequestHeader()
avant d'invoquer send()
avec un argument
de donn�es non-null
.
Lorsqu'elle est invoquée, l'agent utilisateur doit
suivre les étapes suivantes (à moins qu'il ne soit indiqué
de faire autrement). Noter que cet algorithme pourrait être interrompu
si les méthodes open()
ou abort()
sont invoquées. Quand l'algorithme
send()
est interrompu l'agent utilisateur doit
terminer l'algorithme après avoir accompli l'étape en cours.
L'algorithme qui suit ne peut pas être interrompu par
un script quand async est false
. Il peut seulement
l'être quand il est true
et seulement après le
retour de l'appel de la méthode.
Si l'état de l'objet n'est pas OPEN lever une exception INVALID_STATE_ERR
et terminer
ces étapes.
send()
est "true"
lever une exception INVALID_STATE_ERR
et terminer ces étapes.Si async est true
assigner "true"
au drapeau send()
.
Si l'argument données n'a pas été omis
et n'est pas null
l'utiliser pour le corps
d'entité comme défini par la section 7.2 de RFC
2616 en observant les règles suivantes: [RFC2616]
DOMString
Document
Sérialiser la donnée dans un document XML
bien formé avec un espace de nom et encodé en utilisant
l'encodage donné par data.xmlEncoding
,
si spécifié, ou UTF-8 sinon. Si cela échoue parce
que le Document
ne peut pas être sérialisé,
faire comme si la donnée était null
.
S'il n'y a pas d'en-tête Content-Type
dans la
liste des en-têtes de requêtes, l'ajouter à la
liste avec la valeur application/xml
.
Les modification subséquentes dans le Document
n'ont pas d'effet sur ce qui a été soumis.
DOMString
ni
un Document
DOMString
. Ou, si cela échoue,
faire comme si donnée est null
. Si l'argument donnée a été omis ou s'il est null
,
aucun corps d'entité ne sera utilisé dans la requête.
Faire une requête à l'url stockée, en utilisant la méthodes HTTP méthode stockée, l'utilisateur utilisateur stocké (s'il en est et le mot de passe mot de passe stocké (s'il est fourni), en prenant en compte le corps de l'entité, la liste des en-têtes de requête et les règles listées directement après cette suite d'étapes.
Envoyer de façon synchrone un évènement readystatechange
sur l'objet.
L'état de l'objet ne change pas. L'événement est envoyé pour l'historique.
Si async est true
revenir de l'appel de méthode
send()
. (Par là même
ne pas terminer les étapes de l'algorithme.)
Lors du téléchargement des ressources, ce qui suit doit être observé:
Si la redirection ne viole pas la sécurité ou les précautions contre les boucles infinies et que le schéma soit supporté de façon transparente, suivre le lien et revenir au début de cette étape.
HTTP impose des pré-requis à l'agent utilisateur concernant la préservation de la méthode de requête et le corps d'entité lors des redirections, et requiert aussi que les utilisateurs soient avertis de certaines sortes de redirections.
Sinon suivre la série d'étapes suivante:
Assigner le corps d'entité response à "null" et réinitialiser la liste des en-têtes de requête.
De façon synchrone basculer l'état sur DONE.
Si async est mis sur false
lever une
exception NETWORK_ERR
et terminer l'algorithme global.
De façon synchrone envoyer un évènement
readystatechange
à l'objet.
Terminer l'algorithme global.
Il y a des chances qu'une future version de l'objet
XMLHttpRequest
envoie un événement error
ici aussi.
Lancer la série d'étapes qui suit:
Mettre le corps d'entité response à "null" et réinitialiser le liste des en-têtes de requête.
De façon synchrone basculer l'état sur DONE.
Si async est mis sur false
lever une
exception ABORT_ERR
et terminer l'algorithme global.
De façon synchrone envoyer un évènement
readystatechange
à l'objet.
Terminer l'algorithme global.
Il y a des chances qu'une future version de l'objet
XMLHttpRequest
envoie un événement abort
ici aussi.
En cas d'erreurs de DNS ou autre type d'erreur réseau, exécuter la liste d'étapes suivantes. Cela n'inclut pas les réponses HTTP qui indiquent une erreur de type quelconque tel que le code d'état HTTP 410.
Mettre le corps d'entité response à "null" et réinitialiser la liste des en-têtes de requête.
De façon synchrone basculer l'état sur DONE.
Si async est mis sur false
lever une
exception NETWORK_ERR
et terminer l'algorithme global.
De façon synchrone envoyer un évènement
readystatechange
à l'objet.
Terminer l'algorithme global.
Il y a des chances qu'une future version de l'objet
XMLHttpRequest
envoie un évènement error
ici aussi.
Si tous les en-têtes HTTP on été reçus, avant de recevoir le corps du message (s'il en est), suivre les étapes suivants:
De façon synchrone basculer l'état sur SENT.
De façon synchrone envoyer un évènement
readystatechange
à l'objet.
De façon synchrone basculer l'état sur LOADING.
De façon synchrone envoyer un évènement
readystatechange
à l'objet.
Finalement si la ressource à été entièrement téléchargée, aller à l'étape suivante.
Lorsque la requête a complètement terminé le chargement,
de façon synchrone basculer l'état sur DONE
et ensuite de façon synchrone envoyer un évènement
readystatechange
à
l'objet et revenir de l'appel de méthode au cas où async
serait false
.
Si l'agent utilisateur permet la spécification d'un proxy, il devrait
modifier la requête de façon appropriée; i.e.,
se connecter au proxy au lieu du serveur originel, modifier Request-Line
et envoyer les en-têtes Proxy-Authorization
comme spécifié.
Si l'agent utilisateur reconnaît l'Authentification HTTP
[RFC2617] il devrait
considérer les requêtes venant de cet objet comme faisant partie
de l'espace de protection qui inclut les URIs accédés et envoyer
des en-têtes d'Authorisation
et prendre en charge les
requêtes 401 Unauthorised
de façon appropriée.
Si l'authentification échoue, les agents utilisateurs devraient
rester en attente des références des utilisateurs. [RFC2617]
Si l'agent utilisateur supporte la gestion des états HTTP
il devrait persister, mettre de coté et envoyer
des cookies (tels que reçus dans les en-têtes de réponse
Set-Cookie
et Set-Cookie2
, et envoyés dans
l'en-tête Cookie
) selon la façon dont cela est
applicable. [RFC2965]
Si l'agent utilisateur implémente une antémémoire
HTTP [RFC2616]
il devrait respecter les en-têtes de requête Cache-Control
assignées par l'auteur (si Cache-Control:
no-cache
outrepasse l'antémémoire). Il ne
doit pas envoyer les en-têtes de requête Cache-Control
ou Pragma
automatiquement à moins que l'utilisateur
ne requiert explicitement un tel comportement (donc par un rechargement
forcé de la page). Les réponses 304 Not Modified
qui sont le résultat des requêtes conditionnelles générées
par l'agent utilisateur doivent être présentées
comme réponse 200 OK
avec le contenu approprié.
De tels agents utilisateurs doivent permettre aux auteurs
de surcharger la validation automatique d'antémémoire en assignant
des en-têtes de requête (e.g., If-None-Match
, If-Modified-Since
),
auquel cas on doit passer outre les réponses 304 Not Modified
.
[RFC2616]
Si l'agent utilisateur implémente une négociation du contenu
dirigée par le serveur il devrait assigner les
en-têtes Accept-Language
, Accept-Encoding
et Accept-Charset
de façon appropriée; il ne
doit pas assigner l'en-tête Accept
automatiquement.
Les réponses à de telles requêtes doivent
avoir l'encodage du contenu décodé automatiquement. [RFC2616]
abort()
Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes (à moins qu'on qu'il ne soit indiqué de faire autrement):
Interrompre l'algorithme
send()
, mettre le corps
d'entité de response à "null", mettre le drapeau
send()
sur "false" et supprimer tous en-têtes
de requête non enregistrés.
L'agent utilisateur devrait abandonner tout activité du réseau dont est responsable l'objet.
Si l'état est UNSENT,
OPEN et que le drapeau
send()
est "false", ou DONE
aller à l'étape suivante.
Sinon, basculer sur l'état DONE et de façon synchrone envoyer un évènement
readystatechange
à
l'objet.
Basculer l'état sur UNSENT. (Ne pas envoyer l'événement readystatechange
)
Il y a des chances qu'une future version de l'objet XMLHttpRequest
envoie un évènement abort
ici aussi.
getAllResponseHeaders()
Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes:
Si l'état n'est pas LOADING ni DONE lever
une exception INVALID_STATE_ERR
et terminer ces étapes.
Retourner tous les en-têtes HTTP, en tant que simple chaîne de caractères, les lignes d'en-tête étant séparées par une paire U+000D CR U+000A LF sauf la ligne d'état.
// Le script suivant:
var client = new XMLHttpRequest();
client.open("GET", "test.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == 3) {
print(this.getAllResponseHeaders());
}
}
// ...devrait afficher un texte similaire à ce qui suit:
Date: Sun, 24 Oct 2004 04:58:38 GMT
Server: Apache/1.3.31 (Unix)
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8
getResponseHeader(en-tête)
Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes:
Si l'état n'est pas LOADING ni DONE lever
une exception INVALID_STATE_ERR
et terminer ces étapes.
Si l'argument header ne correspond pas à la production
field-name
, lever une exception SYNTAX_ERR
et terminer ces étapes.
Si l'argument en-tête correspond sans égard à la casse de multiples en-têtes HTTP pour la dernière requête envoyée, retourner les valeurs de ces en-têtes concaténés dans une simple chaîne de caractères séparés entre eux par une VIRGULE U+002C suivie par un ESPACE U+0020 et terminer ces étapes
Si l'argument en-tête correspond avec la casse à un simple en-tête HTTP pour la dernière requête envoyée retourner la valeur de cet en-tête et terminer ces étapes.
Retourner null
.
// Le script suivant:
var client = new XMLHttpRequest();
client.open("GET", "test.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == 3) {
print(client.getResponseHeader("Content-Type"));
}
}
// ...devrait afficher quelque chose d'équivalent au texte suivant:
Content-Type: text/plain; charset=utf-8
responseText
de type DOMString
,
lecture seule.Si l'état n'est pas reçu ni chargé, les agents utilisateurs doivent
lever une exception INVALID_STATE_ERR
. Sinon il n'y a pas
de corps de l'entité,
cet attribut doit être null
. Si
c'est le cas, il doit être un fragment du corps
de l'entité reçu jusque là (quand l'état
était reçu)
ou le corps de l'entité complet
(quand l'état est chargé),
interprété comme un flux de caractères.
Si la réponse inclut un type MIME compris par l'agent utilisateur
les caractères sont décodés en suivant la spécification
de type MIME concerné. Si l'agent utilisateur ne peut dériver
un flux en accord avec la spécification du type de média,
responseText doit
être null
.
Sa valeur initiale doit être null
.
responseXML
de type Document
,
lecture seuleQuand il est obtenu, l'agent utilisateur doit accomplir les étapes suivantes:
Si l'état n'est pas LOADING ni DONE lever
une exception INVALID_STATE_ERR
et terminer ces étapes.
Retourner le corps d'entité response.
status
de type unsigned shortQuand il est obtenu, l'agent utilisateur doit accomplir les étapes suivantes:
Si l'état n'est pas DONE
lever une exception INVALID_STATE_ERR
et terminer ces étapes.
Retourner le corps d'entité response XML.
statusText
de type DOMString
,
lecture seuleQuand il est obtenu, s'il est disponible, il doit retourner
le code d'état HTTP envoyé par le serveur (normalement 200
pour une requête réussie). Sinon, s'il n'est pas disponible,
l'agent utilisateur doit lever une exception INVALID_STATE_ERR
.
XMLHttpRequest
Ces sections décrivent les différents évènements
qui peuvent être affectés à l'objet implémentant
l'interface XMLHttpRequest
. Dans
cette version de la spécification, un seul évènement est
défini.
readystatechange
readystatechange
(comme indiqué plus haut) celui-ci ne doit pas être pris en charge
par les noeuds parents dans l'arborescence DOM, ne doit pas
être annulable et doit implémenter l'interface
Event
. Son attribut namespaceURI
doit être
null
. [DOM3Events]. XMLHttpRequest
exception XMLHttpRequestException { unsigned short code; }; const unsigned short NETWORK_ERR = 101; const unsigned short ABORT_ERR = 102;
L'exception NETWORK_ERR
est levée
quand une erreur de réseau survient dans les requêtes synchrones.
L'exception ABORT_ERR
est levée
quand l'utilisateur annule une requête dans les requêtes synchrones.
Voir la section send()
pour plus de détails.
La spécification actuelle n'inclut par les fonctionnalités suivantes qui peuvent ou non être implémentées par les agents utilisateurs.
load
et attribut onload
;error
et attribut onerror
;progress
et attribut onprogress
;abort
et attribut onabort
;
ontimeout
;responseXML
pour les documents text/html
;
XMLHttpRequest
entre sites différents.responseBody
pour traiter les flux d'octets; overrideMimeType
pour corriger les types MIME; getRequestHeader
et removeRequestHeader
. Cette section n'est pas normative.
L'éditeur aimerait remercier les personnes suivantes qui ont contribué à cette spécification (par ordre alphabétique de nom propre):
Merci particulièrement aussi aux employés de Microsoft qui
les premiers ont implémenté l'interface XMLHttpRequest
,
qui tout d'abord a été largement diffusée par le navigateur
Internet Explorer de Windows.
Merci spécialement aussi au WHATWG pour l'esquisse de la première
version de cette spécification dans leur document Web Applications
1.0.
Merci aussi à tous ceux qui ont aidé à améliorer cette spécification en envoyant des suggestions et des corrections. (S'il vous plaît, continuez à nous embêter avec vos problèmes!)