L'objet XMLHttpRequest

Résumé

function test(data) {
 // taking care of data
}

function handler() {
 if(this.readyState == 4 && this.status == 200) {
  // so far so good
  if(this.responseXML != null && this.responseXML.getElementById('test').firstChild.data)
   // success!
   test(this.responseXML.getElementById('test').firstChild.data);
  else
   test(null);
 } else if (this.readyState == 4 && this.status != 200) {
  // fetched the wrong page or network error...
  test(null);
 }
}

var client = new XMLHttpRequest();
client.onreadystatechange = handler;
client.open("GET", "test.xml");
client.send();

function ping(message) {
 var client = new XMLHttpRequest();
 client.open("POST", "/ping");
 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();
}

var client = new XMLHttpRequest();

    interface XMLHttpRequest {

           attribut EventListener   onreadystatechange;
  readonly attribut unsigned short  readyState;
  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();
  DOMString          getAllResponseHeaders();
  DOMString          getResponseHeader(en en-tête DOMString);
  attribut DOMString       responseText;
  attribut Document        responseXML;
  attribut unsigned short  status;
  attribut DOMString       statusText;
};

Méthodes

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

Qu'en est-il des invocations multiples de open()? lorsqu'elles se suivent l'une après l'autre ou après invocation de send(), etc...

L'appel de cette méthode doit initialiser l'object en rappelant les arguments méthode, uri, async (valeur par défaut true si omis), utilisateur (valeur par défaut null si omis), et mot-de-passe (valeur par défaut null si omis), en assignant 1 à l'attribut readyState (Ouvert), en restaurant les attributs responseText, responseXML, status, et statusText à leur valeurs initiales, et en restaurant la liste des en-têtes de requêtes.

Les restrictions de sécurité de même origine devraient s'appliquer.

Si l'argument method ne correspond pas à la production de méthode définie dans le section 5.1.1 de [RFC2616] une SYNTAX_ERR doit être levée par l'agent utilisateur. Si l'agent utilisateur ne supporte pas la méthode donnée pour des raisons de sécurité, une SECURITY_ERR doit être levée.

Les agents utilisateurs doivent au moins supportes la liste de méthodes suivante (void [RFC2616], [RFC2518], [RFC3253], [RFC3648] et [RFC3744]):

• GET
• POST
• HEAD
• PUT
• DELETE
• PROPFIND
• PROPPATCH
• MKCOL
• COPY
• MOVE
• LOCK
• UNLOCK
• VERSION-CONTROL
• REPORT
• CHECKOUT
• CHECKIN
• UNCHECKOUT
• MKWORKSPACE
• UPDATE
• LABEL
• MERGE
• BASELINE-CONTROL
• MKACTIVITY
• ORDERPATCH
• ACL

Les agents utilisateurs devraient supporter tout argument de méthode qui correspond à la production de méthode.

Quand une méthode correspond, sans égard à la casse à GET, POST, HEAD, PUT ou DELETE l'agent utilisateur doit utiliser plutôt l'équivalent en majuscules.

Si le paramètre url ne correspond pas à la syntaxe définie dans la section 3.2.2 de [RFC2616] une SYNTAX_ERR doit être levée. Quand un argument url qui n'est pas de même origine est donné les agents utilisateurs devraient envoyer une exception SECURITY_ERR.

Une version future ou une extension de cette spécification définira un moyen de faire des requêtes entre sites.

Les agents utilisateurs ne devraient pas supporter le format "utilisateur:mot-de-passe" dans la production userinfo définie dans la section 3.2.1 de [RFC3986] et doivent envoyer une SYNTAX_ERR quand cela arrive (et qu'ils ne le supportent pas). Quand ils le supportent, ou dans le cas de personnes qui utilisent le format "utilisateur", les agents utilisateurs doivent les utiliser si les arguments utilisateur et mot-de-passe sont omis.Si les arguments ne sont pas omis, ils obtiennent la précédence, même s'ils sont null.

Si l'argument utilisateur ne correspond pas à la prodcution username-value définie dans la section 3.2.2 de [RFC2617] les agents utilisateurs doivent envoyer une exception SYNTAX_ERR.

Il nous faut voir l'argument mot-de-passe.

Si open() est invoquée quand readyState vaut 4 (Chargé) tous les membres de l'objet doivent être remis à leurs valeurs initiales.

La méthode send(données)

Qu'en est-il des invocations multiples de send()? Noter qu'invoquer send() ne change pas directement readyState ce qui rend cela compliqué.

Si l'attribut readyState a une valeur autre que 1 (Ouvert), une exception INVALID_STATE_ERR doit être levée.
Sinon, une requête à url en utilisant la méthode méthode est envoyée.l'url, si relative, doit être résolue en utilisant window.document.baseURI de la window dont le constructeur est utilisé. Si le drapeau async est positionné sur faux, alors la méthode ne doit pas s'achever tant que la requête n'est pas satisfaite. Sinon elle doit s'achever immédiatement. (Voir: open().)

Si une donnée est passée par la méthode send() elles doit être utilisée dans le corps de l'entité en suivant ces règles (le terme corps de l'entité est défini par le section 7.2.1 of [RFC2616]):

• Si la donnée est une DOMString, elle doit encodée comme pour une transmission UTF-8.
• Si la donnée est un Document, elle doit être sérialisée en utilisant l'encodage donné par data.xmlEncoding, si spécifié et supporté, ou UTF-8 autrement [DOM3Core].
• Si la donnée n'est pas une DOMString ni un Document les mécanismes de conversion en chaîne du langage hôte doivent être utilisés sur l'argument qui a été passé et le résultat doit être encodé comme si donnée est une DOMString.

Invoquer send() sans l'argument donnée doit donner le même résultat que si elle était invoquée avec un argument null.

Les auteurs devraient spécifier l'en-tête Content-Type par setRequestHeader avant d'invoquer send avec un argument. Si l'argument pour send() est un Document et qu'aucun en-tête Content-Type n'est assigné, les agents utilisateurs doivent l'assigner en application/xml pour les documents XML et au type de média le plus approprié pour les autres documents (en utilisant la connaissance intrinsèque sur le document).

Si la réponse est une redirection HTTP (code d'état 301, 302, 303 or 307), alors elle doit être suivie de façon transparente (à moins que cela ne viole la sécurité ou les précautions contre l'entrée dans une boucle infinie ou si le schéma n'est pas supporté). Noter que HTTP [RFC2616] impose des obligations aux agents utilisateurs concernant la préservation de la méthode de requête pendant les redirections, et en outre requiert que les utilisateurs soient notifiés de certaines sortes de redirections automatiques.

Une fois que la requête a été reconnue avec succès readyState doit être mis à2 (Envoyé). Immédiatement avec la réception du corps du message (s'il y en a), l'attribut readyState doit être mis à 3 (Réception). Quand la requête a achevé le chargement, l'attribut readyState doit être mis à 4 (Chargé). En cas de requête HEAD readyState doit être mis à 4 (Chargé) immédiatement après être arrivé sur 3 (Réception).

Si quelque chose se passe mal (boucle infinie, erreurs de réseau) l'attribut readyState doit être mis à 4 (Chargé) et tous les autres membres de l'objet doit être remis à leur valeurs initiales.

Dans les versions futures de cette spécification il sera demandé aux agents utilisateurs de ventiler un évènement error dans le cas ou ce qui est ci-dessus se produisait.

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 supporte 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'Autorisation et prendre en charge les requêtes 401 Unauthorised de façon appropriée. Si l'authentication échoue, les agents utilisateurs devraient rester en attente des références des utilisateurs.

Si l'agent utilisateur supporte la gestion des états HTTP [RFC2109][RFC2965] 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.

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 (e.g., 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 (e.g., par un rechargement forcé de la page). Les réponses 304 Not Modified qui sont le résultat des requêtes conditonnelles 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 les réponses 304 Not Modified doivent être surclassées.

Si l'agent utilisateur implémente une négociation du contenu dirigée par le serveur [RFC2616], 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 supprimé automatiquement.

Si l'agent utilisateur supporte Expect/Continue pour les corps de requête [RFC2616] il devrait insérer les en-têtes Expect et gérer les réponses 100 Continue de façon appropriée.

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

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

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

Ceci devrait probablement exposer qu'elle peut seulement être invoquée entre l'invocation de open() et l'invocation de send() étant donné que readyState ne peut pas refléter efficacement cette période.

Le champ valeur de l'en-tête (header) de requête nommée doit être assigné à valeur, avec les exceptions suivantes:

• Si l'attribut readyState a une valeur autre que 1 (Ouvert), une exception INVALID_STATE_ERR doit être levée.
• Si l'argument en-tête ne correspond pas à la production nom-de-champ comme défini par la section 4.2 de [RFC2616] une SYNTAX_ERR doit être levée;
• Si l'argument valeur ne correspond pas à la production valeur-de-champ comme défini par la section 4.2 de [RFC2616] une SYNTAX_ERR doit être levée;
• Pour des raisons de sécurité rien ne devrait être fait si l'argument en-tête correspond à Accept-Charset, Accept-Encoding, Content-Length, Expect, Date, Host, Keep-Alive, Referer, TE, Trailer, Transfer-Encoding ou Upgrade sans égard à la casse.

Les implémentations doivent remplacer toute valeur existante si la valeur de champ de l'en-tête de requête nommée fait partie de: Authorization, Content-Base, Content-Location, Content-MD5, Content-Range, Content-Type, Content-Version, Delta-Base, Depth, Destination, ETag, Expect, From, If-Modified-Since, If-Range, If-Unmodified-Since, Max-Forwards, MIME-Version, Overwrite, Proxy-Authorization, SOAPAction ou Timeout.

Autrement, si le champ d'en-tête de requête a déja une valeur, la nouvelle valeur doit être combinée avec la valeur existante (section 4.2, [RFC2616]). Voir aussi la méthode send() en ce qui concerne la gestion par les agents utilisateurs de l'en-tête pour la mise en cache, l'authentification, les, proxies, et les cookies.

// Le script suivant:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send(null);

// ...devrait avoir pour résultat que l'en-tête suivant soit envoyé:
...
X-Test: one, two
...

La liste d'en-têtes de requêtes doit être restaurée quand la méthode open() est appelée.

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

L'évènement readystatechange doit être généré quand readyState change de valeur. Il ne doit pas être une bulle, ne doit pas être annulable et doit implémenter l'interface Event [DOM3Events]. L'évènement n'a pas d'espace de nom (Event.namespaceURI est null).