W3C

L'objet XMLHttpRequest

Traduction française du document de travail du 15 Avril 2008.

Auteur: Denis Sureau - Xul.fr

Dernière Version:
https://www.xul.fr/XMLHttpRequest en français ou https://www.w3.org/TR/XMLHttpRequest/ original en anglais
Précédentes Versions:
XMLHttpRequest du 26 Octobre 2007 ou en anglais https://www.w3.org/TR/2007/WD-XMLHttpRequest-20071026/
XMLHttpRequest du 18 Juin 2007 ou en anglais https://www.w3.org/TR/2007/WD-XMLHttpRequest-20070618/
XMLHttpRequest du 27 Février 2007 ou en anglais https://www.w3.org/TR/2007/WD-XMLHttpRequest-20070227/
XMLHttpRequest du 27 Septembre 2006 ou en anglais https://www.w3.org/TR/2006/WD-XMLHttpRequest-20060927/
XMLHttpRequest du 19 Juin 2006 ou en anglais https://www.w3.org/TR/2006/WD-XMLHttpRequest-20060619/
https://www.w3.org/TR/2006/WD-XMLHttpRequest-20060405/
Editeur:
Anne van Kesteren (Opera Software ASA) <annevk@opera.com>

Résumé

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.

Statut de ce Document

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 à https://www.w3.org/TR/.

C'est la version du 15 Avril 2008 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 avant le 2 juin 2008.

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.

Table des matières

1. Introduction

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 permet des "requêtes" 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.

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();
}

2. Conformité

Tout dans cette spécification est normatif, à l'exception des diagrammes, exemples, notes et des sections notées comme n'étant pas normatives.

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:

Agent utilisateur conforme

Un agent utilisateur doit se comporter tel que décrit dans cette spécification pour être considéré comme conforme.

Si l'agent utilisateur n'est pas un agent utilisateur XML conforme le corps d'entité de réponse XML doit (toujours ) être null.

Les agents utilisateurs peuvent implémenter tout algorithme donné dans cette spécification de la façon qui leur convient, 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.

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.

Agent utilisateur XML conforme

Un agent utilisateur qui est à la fois un agent utilisateur conforme et un processeur XML qui rapporte les violations de formation dans les espaces de noms. [XML] [XMLNS]

2.1 Dépendances

Cette spécification dépend de plusieurs autres spécifications sous-jacentes.

DOM

Un agent utilisateur conforme doit reconnaître quelque sous-ensemble des fonctionnalités définies dans DOM Events (Evénements DOM) et DOM Core (coeur de DOM) parce que cette spécification se base là dessus. [DOM3Events] [DOM3Core]

HTML 5

Cette spécification dépends de HTML 5 pour definir l'objet Window et trouver l'encodage de caractères d'une ressource text/html. Un agent utilisateur conforme doit supporter ces caractéristiques. [HTML5]

L'ébauche de Window Object 1.0 n'est pas référencée normativement puisqu'il semble qu'elle ne soit plus mise à jour et HTML 5 définit l'objet Window avec plus de details. Cette spécification dépends déjà de HTML 5 pour d'autres raisons aussi ceci n'occasionne pas de surcoût.

HTTP

Un agent utilisateur conforme doit reconnaître quelque version du protocole HTTP. Il doit reconnaître toute méthode HTTP qui corresponde à la production de Méthode et doit au moins supporter les méthodes suivantes:

Les autres pré-requis concernant HTTP sont donnés dans la spécification. [RFC2616]

2.2. Terminologie

Il y a une correspondance insensible à la casse des chaînes s1 et s2 si après mise en majuscules des deux chaînes (en faisant correspondre a-z à A-Z) elles s'avèrent identique.

Deux URIs sont de même même-origine si après que l'on ait accompli une normalisation basée sur les schémas des deux URIs comme décrit dans la section 5.3.3 de la RFC 3987, les schémas, les composants ihost et port sont identiques. Si une des URIs n'a pas de composant ihost les URIs ne doitvent pas être considérées de même origine. [RFC3987]

2.3. Extensibilité

Les extensions de l'API définie 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é, de préférence sur public-webapi@w3.org.

3. Considérations sur la sécurité

Outre les pré-requis pour la sécurité donnés dans cette spécification, les implémentations peuvent, à leur discrétion, ne pas présenter certains en-têtes, tels les cookies HttpOnly.

4. L'Objet XMLHttpRequest

L'objet XMLHttpRequest peut être utilisé pour permettre aux scripts de se connecter selon leur programmation à leur serveur d'origine par HTTP.

Les objets implémentant l'interface XMLHttpRequest doivent aussi implémenter l'interface EventTarget [DOM2Events].

Les objets implémentant l'interface Window doivent fournir un constructeur XMLHttpRequest() . [HTML5]

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 Document est stocké sur l'objet nouvellement créé. C'est le pointeur Document. L'objet Document associé est celui qui est retourné par l'attribut document de l'objet sur lequel le constructeur XMLHttpRequest a été invoqué (un objet Window). Le pointer peut devenir "null" si l'objet a été supprimé.

Puisque du fait des critères de conformité les implémentations sont libres d'implémenter ceci de la façon qu'elle veulent pourvu que les résultats finaux soient identiques à ceux donnés par la prose Française.

Si iframe est un objet Window le client aura un pointeur sur iframe.document dans l'exemple suivant:

var client = new iframe.XMLHttpRequest()
 interface XMLHttpRequest {

attribut EventListener onreadystatechange;

// état

const unsigned short UNSENT = 0;
const unsigned short OPENED = 1;
const unsigned short HEADERS_RECEIVED = 2;
const unsigned short LOADING = 3;
const unsigned short DONE = 4;
attribut lectureseule unsigned short readyState;

// requête

void open(en méthode DOMString, en url DOMString);
void open(en méthode DOMString, en url DOMString, en boolean async);
void open(en méthode DOMString, en url DOMString, en boolean async, en utilisateur DOMString);
void open(en méthode DOMString, en url DOMString, en boolean async, en utilisateur DOMString, mot-de-passe DOMString);
void setRequestHeader(en en-tête DOMString, en valeur DOMString));
void send();
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 lectureseule DOMString responseText;
attribut lectureseule Document responseXML;
attribut lectureseule unsigned short status;
attribut lectureseule DOMString statusText;
};

L'objet XMLHttpRequest peut avoir cinq états: UNSENT, OPENED, HEADERS_RECEIVED, 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 OPENED 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 OPENED, dont la valeur est 1.

L'état OPENED a un drapeau send() associé qui peut valoir soit "true" ou "false" (vrai ou faux). La valeur initiale du drapeau send() est "false".

L'état HEADERS_RECEIVED est l'état de l'objet quand tous les en-têtes de réponse ont été reçus. Cet état est représenté par la constante HEADERS_RECEIVED, dont la valeur est 2.

L'état LOADING est l'état de l'objet quand le corps de l'entité réponse a en cours de réception. L'état est représenté par la constante LOADING, dont la valeur est 3.

L'état DONE est l'état de l'objet quand soit le transfert des données s'est terminé ou quelquechose n'a pas fonctionné durant le transfert (redirections infinies par exemple). L'état est représenté par la constante DONE, dont la valeur est 4.

L'état DONE a été associé avec le drapeau error qui peut être soir "true" ou "false". La valeur initale du drapeau error est "false".

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:

  1. Si le corps d'entité response est "null" retourner null et terminer ces étapes.

  2. Faire que le charset soit "null".

  3. S'il n'y a pas d'en-tête Content-Type ou s'il y a un en-tête Content-Type qui contient un type MIME qui est text/xml, application/xml ou se termine en +xml (en ignorant tous paramètres) utiliser l'ensemble de règles mises 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é.

  4. S'il y a un en-tête Content-Type contenant un type MIME text/html suivre les règles mises en avant dans la spécification HTML 5 pour déterminer l'encodage des caractères. Faire que charset soit l'encodage de caractères déterminé. [HTML5]

  5. Si le type MIME spécifié par l'en-tête Content-Type contient un paramètre 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.

  6. Si charset est "null" alors, pour chacune des lignes dans la table qui suit, en partant de la première et en descendant, si le premier octet de Octets correspond aux octets donnés dans la première colonne, alors faire que charset soit l'encodage donné dans la cellule de la seconde colonne de la ligne. S'il y a pas correspondance charset reste à "null".

    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
  7. Si charset est "null" faire que charset soit UTF-8.

  8. Retourner le résultat du décodage du corps d'entité response en utilisant le charset. Remplacer les octets ou séquences d'octets qui ne sont pas valide selon le charser avec un simple caractère U+FFFD.

  9. Authors are encouraged to simply encode their resources using UTF-8.

Le corps d'entité response XML est soit un Document représentant le corps d'entité response ou null. Le corps d'entité response XML est la valeur de retour de l'algorithme suivant:

  1. Si le corps d'entité response est "null" terminer ces étapes et retourner null.

  2. Si un Content-Type est présent et ne contient pas de type MIME (en ignorant tous paramètres) 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.)

  3. Parser le corps d'entité response dans l'arborescence du document 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 formation d'espace de nom et cetera) terminer ces étapes et retourner null. [XML] [XMLNS]

  4. Les scripts dans l'arborescence du document qui en résulte ne seront pas exécutés, les ressources référencées ne seront pas chargées et aucun XSLT associé ne sera appliqué.

  5. Retourner un objet implémentant l'interface Document représentant le document parsé.

onreadystatechange de type EventListener

Cet attribut est un attribut du gestionnaire d'évènement de DOM et doit être invoqué quand un évènement readystatechange est destiné à l'objet.

readyState de type unsigned short, lecture seule

Lorsqu'on l'obtient l'attribut doit retourner la valeur de la constante correspondant à l'état actuel de l'objet.

La méthode open(méthode, url, async, utilisateur, mot-de-passe)

Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes (à moins qu'il ne soit indiqué de faire autrement):

  1. Faire que la méthode stockée soit l'argurment method.

  2. Si la méthode stockée 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]

  3. Si la méthode stockée correspond sans égard à la casse à CONNECT, DELETE, GET, HEAD, OPTIONS POST, PUT, TRACE, ou TRACK faire que la méthode stockée soit sous la forme canonique majuscules du nom de méthode correspondant..

  4. Si la méthode stockée est CONNECT, TRACE, ou TRACK, l'agent utilisateur devrait lever une exception SECURITY_ERR et terminer ces étapes.

  5. Ôter l'identifieur de fragment (s'il en est) de l' url et faire que l'url stockée soit le résultat de cette opération.

  6. Si l'url stockée est une référence relative la résoudre en utilisant la valeur courante de l'attribut baseURI du pointer Document. Si cela échour lever une exception SYNTAX_ERR et terminer ces étapes.

  7. Si l'url stockée contient un schéma non reconnu lever une exception NOT_SUPPORTED_ERR et terminer ces étapes.

  8. 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 pour le schéma concerné et que l'url stockée contient ce format, lever une exception SYNTAX_ERR et terminer ces étapes. [RFC3986]

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

  10. Si l'url stockée contient juste le format "user" faire que l'utilisateur stocké soit la partie utilisateur.

  11. Si l' url n'est pas de même origine que l'origine du pointeur Document, l'agent utilisateur devrait lever une exception SECURITY_ERR et terminer ces étapes.

  12. Assigner à async la valeur de l'argument async ou true s'il était omis.

  13. Si l'argument utilisateur n'était pas omis et que la syntaxe ne corresponde pas à ce que spécifie le schéma d'authentification concerné, lever une exception SYNTAX_ERR et terminer ces étapes.

  14. 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 pourrait avoir été assigné par l'argument d'url.

  15. Si l'argument utilisateur n'était pas omis et qu'il soit null, ôter l'utilisateur stocké.

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

  17. Si l'argument mot de passe n'était pas omis et n'est pas null assigner mot de passe encodé a mot de passe stocké 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.

  18. Si l'argument mot de passe n'était pas omis et est null ôter le mot de passe stocké.

  19. Abandonner l'algorithme send() , assigner "null" au corps d'entité response et réinitialiser la liste d'en-têtes de requête.

  20. L'agent utilisateur devrait abandonner toute activité sur le réseau dont l'objet soit responsable.
  21. Basculer l'objet sur l'état OPEN, assigner "false" au drapeau send() et ensuite envoyer en mode synchrone un é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 définira plus probablement une façon de faire des requêtes entre sites.

La méthode setRequestHeader(en-tête, valeur)

Chaque requête dispose d'une liste d'en-tête de requête avec des valeurs associées. La méthode setRequestHeader() peut être utilisée pour manipuler ces valeurs et ajouter de nouveaux en-têtes de requêtes.

La méthode setRequestHeader() ajoute une valeur si l'en-tête HTTP donné comme argument fait déjà partie de la liste des en-têtes de la requête.

Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes (à moins qu'on qu'il ne soit indiqué de faire autrement):

  1. Si l'état de l'objet n'est pas OPENED lever une exception INVALID_STATE_ERR et terminer ces étapes.

  2. Si le drapeau send() vaut "true" lever une exception INVALID_STATE_ERR et terminer ces étapes.

  3. Si l'argument en-tête ne correspond pas à la production field-name 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]

  4. Si l'argument valeur est null terminer ces étapes. (Ne pas lever d'exception.)

  5. Si l'argument valeur ne correspond pas à la production field-value comme défini par la section 4.2 de RFC 2616 lever une exception SYNTAX_ERR et terminer ces étapes. [RFC2616]

  6. 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 suivants:

    • Accept-Charset
    • Accept-Encoding
    • Connection
    • Content-Length
    • Content-Transfer-Encoding
    • Date
    • Expect
    • Host
    • Keep-Alive
    • Referer
    • TE
    • Trailer
    • Transfer-Encoding
    • Upgrade
    • Via
  7. En outre pour des raisons de sécurité, ces étapes devraient être terminées si les six premiers caractères de l'argument en-tête correspond sans sensibilité à la casse à Proxy- ou Sec-.
  8. Si l'argument header n'est pas dans la liste des en-têtes de requête, ajouter l'en-tête avec ses valeurs associées à la liste et terminer ces étapes.
  9. 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();

// ...devrait avoir pour résultat que l'en-tête suivant soit envoyé:
...
X-Test: un, deux
...
La méthode send(données)

La méthode send() lance la requête et son argument optionnel fournit le corps d'entité.

Les auteurs sont 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.

  1. Si l'état de l'objet n'est pas OPENED lever une exception INVALID_STATE_ERR et terminer ces étapes.

  2. Si le drapeau send() vaut "true" lever une exception INVALID_STATE_ERR et terminer ces étapes.

  3. Si async est true assigner "true" au drapeau send().

  4. Si la méthode enregistrée est GET agir comme si l'agument données était null.

    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]

    la donnée est une DOMString

    Encoder la donnée en utilisant UTF-8 pour la transmission.

    Si un en-tête Content-Type est assigné par l'utilisation de setRequestHeader() assigner le paramètre charset de cet en-tête à UTF-8.

    la donnée est un 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.inputEncoding, quand non null, ou UTF-8 sinon. Ou, si cela échoue parce que le Document ne peut pas être sérialisé, faire comme si la donnée était null.

    S'il aucun en-tête Content-Type n'a été assigné par l'utilisation de setRequestHeader() ajouter un en-tête Content-Type à la liste des en-têtes de requête avec une valeur application/xml;charset=charsetcharset est l'encodage utilisé pour le document.

    Les modifications subséquentes dans le Document n'ont pas d'effet sur ce qui a été soumis.

    la donnée n'est ni une DOMString ni un Document

    Utiliser les mécanismes de transformation en chaîne de caractère du langage hôte sur la donnée et traiter les résultats comme si la donnée était une 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.

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

  6. 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 des raisons historiques.

  7. Si async est true revenir de l'appel de la méthode send(). (Pour autant ne pas terminer les étapes de l'algorithme.)

  8. Lors du téléchargement des ressources, les règles suivantes doivent être observées:

    Si la réponse est une redirection HTTP

    Si la redirection ne viole pas la sécurité (en l'occurence est de même origine) 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 (étape 8).

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

    Sinon suivre la série d'étapes suivante:

    1. Assigner le corps d'entité response à "null", le drapeau error à "true" et réinitialiser la liste des en-têtes de requête.

    2. De façon synchrone basculer l'état sur DONE.

    3. Si async est mis sur false lever une exception NETWORK_ERR et terminer l'algorithme global.

    4. De façon synchrone envoyer un évènement readystatechange à l'objet.

    5. 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 l'utilisateur annule le téléchargement

    Lancer la série d'étapes qui suit:

    1. Mettre le corps d'entité response à "null", le drapeau error à"true" et réinitialiser le liste des en-têtes de requête.

    2. De façon synchrone basculer l'état sur DONE.

    3. Si async est mis sur false lever une exception ABORT_ERR et terminer l'algorithme global.

    4. De façon synchrone envoyer un évènement readystatechange à l'objet.

    5. 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 réseau

    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.

    1. Mettre le corps d'entité response à "null", le drapeau error à"true" et réinitialiser la liste des en-têtes de requête.

    2. De façon synchrone basculer l'état sur DONE.

    3. Si async est mis sur false lever une exception NETWORK_ERR et terminer l'algorithme global.

    4. De façon synchrone envoyer un évènement readystatechange à l'objet.

    5. Terminer l'algorithme global.

    Il y a des chances qu'une future version de l'objet XMLHttpRequest envoie un évènement error ici aussi.

    Une fois que tous les en-têtes HTTP ont été reçus

    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:

    1. De façon synchrone basculer l'état sur HEADERS_RECEIVED.

    2. De façon synchrone envoyer un évènement readystatechange à l'objet.

    Une fois le premier octet (ou plus) du corps d'entité response reçu
    S'il n'y a pas de corps d'entité  response
    1. De façon synchrone basculer l'état sur LOADING.

    2. De façon synchrone envoyer un évènement readystatechange à l'objet.

    Finalement une fois la ressource entièrement téléchargée, aller à l'étape suivante.

  9. Lorsque la requête a complètement terminé le chargement avec succès, 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 à l'utilisateur 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  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 HTTP State Management (la Gestion de l'Etat 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  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é. L'agent utilisateur doit permettre aux scripts 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-Encoding et Accept-Charset de façon appropriée; il ne doit pas assigner l'en-tête Accept automatiquement. Si l'en-tête Accept-Language n'est pas assigné par l'utilisation de setRequestHeader() les agents utilisateurs doivent avoir les encodages du contenu décodés automatiquement. [RFC2616]

La méthode abort()

Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes (à moins qu'il ne soit indiqué de faire autrement):

  1. Interrompre l'algorithme send(), mettre le corps d'entité de response à "null", mettre le drapeau error sur "true" et supprimer tous en-têtes de requête non enregistrés.

  2. L'agent utilisateur devrait abandonner tout activité du réseau dont est responsable l'objet.

  3. Si l'état est UNSENT, OPENED et que le drapeau send() est "false", ou DONE aller à l'étape suivante.

    Sinon, basculer sur l'état DONE, mettre le drapeau send() sur "false"et de façon synchrone envoyer un évènement readystatechange à l'objet.

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

La méthode getAllResponseHeaders()

Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes:

  1. Si l'état est UNSENT ou OPENED lever une exception INVALID_STATE_ERR et terminer ces étapes.

  2. Si le drapeau error vaut "true" retourner null et terminer ces étapes.

  3. Retourner tous les en-têtes HTTP, en tant que simple chaîne de caractères, avec chaque ligne d'en-tête séparée 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
La méthode getResponseHeader(en-tête)

Lorsqu'elle est invoquée, l'agent utilisateur doit suivre les étapes suivantes:

  1. Si l'état n'est UNSENT ou OPENED lever une exception INVALID_STATE_ERR et terminer ces étapes.

  2. Si l'argument header ne correspond pas à la production field-name, retourner null et terminer ces étapes.

  3. Si le drapeau error vaut "true" retourner null et terminer ces étapes.

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

  5. Si l'argument en-tête correspond sans égard à 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.

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

Quand il est obtenu, l'agent utilisateur doit accomplir les étapes suivantes:

  1. Si l'état n'est pas LOADING ni DONE retourner une chaîne vide et terminer ces étapes.

  2. Retourner le corps d'entité response texte.

responseXML de type Document, lecture seule

Quand il est obtenu, l'agent utilisateur doit accomplir les étapes suivantes:

  1. Si l'état n'est pas DONE retourner null et terminer ces étapes.

  2. Retourner le corps d'entité response XML.

status de type unsigned short lecture seule

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

statusText de type DOMString, lecture seule

Quand il est obtenu, s'il est disponible, il doit retourner le texte de l'état envoyé par le serveur (il apparaît après le code d'erreur). Sinon, s'il n'est pas disponible, l'agent utilisateur doit lever une exception INVALID_STATE_ERR.

4.1. Evènements de l'objet 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
Quand l'agent utilisateur envoie un évènement readystatechange (comme indiqué plus haut) il 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. [DOM2Events].

4.2. Exceptions pour l'objet XMLHttpRequest

Plusieurs algorithmes dans cette spécification peuvent avoir pour résultat qu'une exception soit envoyée. Ces exceptions font toutes partie du groupe ExceptionCode et utilisent l'objet DOMException qui est défini dans DOM Level 3 Core. En outre cette spécification étend le groupe ExceptionCode avec plusieurs nouvelles constantes comme indiqué ci-dessous. [DOM3Core]
const unsigned short SECURITY_ERR = 18;
const unsigned short NETWORK_ERR = 101;
const unsigned short ABORT_ERR = 102;

L'exception SECURITY_ERR est levée si une tentative est faite de réaliser une opération ou d'accéder à des données d'une façon qui pourrait créer un risque de sécurité ou une violation de la police de sécurité de l'agent utilisateur.

On s'attend à ce que l'exception SECURITY_ERR soit éventuellement intégrée dans une mise à jour de la spécification DOM Level 3 Core avec une définition équivalente et une valeur de constante identique. Jusqu'à ce que ce soit le cas elle est définie ici pour guider les implémenteurs. (C'est aussi la raison pour laquelle elle a une valeur différente des autres exceptions.)

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.

Hors spécification

Cette section n'est pas normative.

Cette spécification n'inclut par les fonctionnalités suivantes qui sont envisagées pour une version future de cette spécification.

Références

[DOM2Events]
Document Object Model (DOM) Level 2 Events Specification, T. Pixley, editor. W3C, November 2000.
[DOM3Core]
Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. World Wide Web Consortium, April 2004.
[ECMAScript]
ECMAScript Language Specification, Third Edition. ECMA, December 1999.
[HTML5]
HTML 5 (travail en cours), I. Hickson, D. Hyatt, editors. W3C, 2008.
HTML 5 (travail en cours), I. Hickson, editor. WHATWG, 2008.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
[RFC2616]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, editors. IETF, June 1999
[RFC2617]
HTTP Authentication: Basic and Digest Access Authentication, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart, editors. IETF, June 1999.
[RFC2965]
HTTP State Management Mechanism, D. Kristol, L. Montulli, editors. IETF, October 2000.
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, editors. IETF, January 2005.
[RFC3987]
Internationalized Resource Identifiers (IRIs), M. Duerst, M. Suignard, editors. IETF, January 2005.
[XML]
Extensible Markup Language (XML) 1.0 (Fourth Edition), T. Bray, J. Paoli, C. Sperberg-McQueen, E. Maler, F. Yergeau. W3C, September 2006.
[XMLNS]
Namespaces in XML (Second Edition), T. Bray, D. Hollander, A. Layman, R. Tobin. W3C, August 2006.
 

Remerciements

Cette section n'est pas normative.

L'éditeur aimerait remercier  Ahmed Kamel,  Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Asbørn Ulsberg, Boris Zbarsky, Björn Höhrmann, Cameron McCormack, Christophe Jolif, Charles McCathieNevile, Dan Winship, David Håsäther, Dean Jackson, Denis Sureau, Doug Schepers,Douglas Livingstone, Elliotte Harold, Eric Lawrence, Gideon Cohn, Gorm Haug Eriksen, Hallvord R. M. Steen, Håkon Wium Lie, Ian Davis, Ian Hickson, Ivan Herman, Jeff Walden, Jens Lindström, Jim Deegan, Jim Ley, Joe Farro, Jonas Sicking, Julian Reschke, Karl Dubost, Maciej Stachowiak, Magnus Kristiansen, Marc Hadley, Marcos Caceres, Mark Baker, Mark Nottingham, Mohamed Zergaoui, Pawel Glowacki, Robin Berjon, Ruud Steltenpool, Simon Pieters, Stewart Brodie, Sunava Dutta and Zhenbin Xu pour leur contributions à cette spécifiaction.

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 (renommé maintenant HTML 5). [HTML5] .

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!)