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 � [email protected] (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 [email protected].

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