L'objet XMLHttpRequest

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
• 2. Conformité
• 2.1 Dépendances
• 2.2 Terminologie
• 2.3 Extensibilité
• 3. Considérations sur la sécurité
• 4. L'objet XMLHttpRequest
• 4.1. Evénements de l'Objet XMLHttpRequest
• 4.2. Exceptions pour l'objet XMLHttpRequest
• Hors spécification
• Références
• Remerciements

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.

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

function log(message) {
 var client = new XMLHttpRequest();
 client.open("POST", "/log");
 client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
 client.send(message);
}

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:

• GET
• POST
• HEAD
• PUT
• DELETE
• OPTIONS

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]

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.

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.

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]

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

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

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

// 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

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

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 spécification n'inclut par les fonctionnalités suivantes qui sont envisagées pour une version future de cette spécification.

• Evènement load et attribut onload;
• Evènement error et attribut onerror;
• Evènement progress et attribut onprogress;
• Evènement abort et attribut onabort;
• Des minuteurs ont été suggérés, peut-être un attribut ontimeout;
• Une propriété pour désactiver les redirections qui suivront;
• 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.

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