• JS
• Ajax

Спецификация объекта XMLHttpRequest определяет API, который обеспечивает клиентский скрипт функциональностью для обмена данными между клиентом и сервером.

Этот документ является переводом оригинальной спецификации http://www.w3.org/TR/XMLHttpRequest/ специально для сайта http://xmlhttprequest.ru. Если Вы копируете этот документ - оставьте ссылку на исходный (этот) вариант. Спецификация не окончательна и будет обновляться вместе с переводом.

Статус этого документа

Этот раздел описывает статус этого документа на момент его публикации. Другие документы могут заменить этот документ. Список текущих публикаций W3C и последних редакции этих документов могут быть найдены в списке технических докладов и публикаций W3C по адресу http://www.w3.org/TR/.

Это последний черновой вариант спецификации объекта XMLHttpRequest от 15 апреля 2008. Пожалуйста, присылайте комментарии на public-webapi@w3.org (архив) с пометкой [XHR] или [XMLHttpRequest] в начале темы сообщения до 2 июня 2008.

Этот документ создан рабочей группой Web API, подразделением Rich Web Clients Activity в Зоне Взаимодействия W3C. Изменения, сделанные в этом документе, могут быть найдены на публичном CVS сервере W3C.

Публикация рабочего проекта не предполагает его передачу сообществу. Эта рабочая версия документа может быть обновлена или заменена другим документом в любое время, поэтому не рекомендуется ссылаться на этот документ.

Этот документ создан согласно Патентной Политике W3C от 5 февраля 2004. W3C поддерживает Публичный список открытых патентов, сделанный совместно с членами группы; эта страница также включает инструкции по раскрытию патентов. Лица, имеющие актуальную информацию, в которой содержатся Essential Claim(s) должны раскрыть информации согласно разделу 6 Патентной Политики W3C.

Содержание

• 1. Введение
• 2. Соответствие требованиям
  • 2.1 Зависимости
  • 2.2 Терминология
  • 2.3 Расширяемость
• 3. Соображения безопасности
• 4. Объект XMLHttpRequest
  • 4.1 События объекта XMLHttpRequest
  • 4.2 Исключения объекта XMLHttpRequest
• Нет в данной спецификации
• Ссылки
• Благодарности

1. Введение

Этот раздел ненормативный.

Объект XMLHttpRequest реализует интерфейс, который позволяет скриптам использовать функциональность HTTP-клиента, такую как отправка данных форм и загрузка данных с сервера.

Название объекта - XMLHttpRequest, дано для совместимости с Web, но каждая часть его имени может вводить в заблуждение. Во-первых, объект поддерживает любой текстовый формат, включая XML. Во-вторых, он может быть использован для создания как HTTP, так и HTTPS запросов (некоторые реализации поддерживают дополнительные протоколы, однако данная спецификация не предусматривает такую функциональность). Наконец, объект поддерживает HTTP "запросы" в широком смысле; а именно все действия, составляющие HTTP запросы или ответы для определенных HTTP методов.

Простой пример кода действия над данными из XML файла, полученного по сети:

function test(data) {
 // работа с данными
}

function handler() {
 if(this.readyState == 4 && this.status == 200) {
  // пока все идет нормально
  if(this.responseXML != null && this.responseXML.getElementById('test').firstChild.data)
	 // успешно!
   test(this.responseXML.getElementById('test').firstChild.data);
  else
   test(null);
 } else if (this.readyState == 4 && this.status != 200) {
  // получена неверная страница или сетевая ошибка
  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() {
  // в случае сетевых ошибок достоверный результат может быть не возвращен
  if(this.readyState == 4)
   returnStatus(this.status);
 }
 client.open("HEAD", address);
 client.send();
}

2. Соответствие требованиям

В данной спецификации все нормативно, за исключением диаграмм, примеров, примечаний и разделов, помеченных как ненормативные.

Ключевые слова должен, не должен, следует и может в этом документе должны интерпретироваться согласно RFC 2119. [RFC2119]

Эта спецификация определяет следующие классы продуктов:

Стандартизированный пользовательский агент

Чтобы считаться стандартизированным, пользовательский агент должен вести себя так, как описано в этой спецификации.

Если пользовательский агент не XML стандартизированный пользовательский агент, то тело XML ответа должно быть (всегда) установлено в null.

Пользовательские агенты могут реализовывать алгоритмы данные в этой спецификации любым способом, если результаты работы не будут отличаться от описанных в спецификации.

Эта спецификация использует оба термина "стандартизированный пользовательский агент" и "пользовательский агент" для ссылок на этот класс продуктов.

XML стандартизированный пользовательский агент

XML стандартизированный пользовательский агент должен быть стандартизированным пользовательским агентом и должен быть стандартизированным обработчиком XML, который сообщает о нарушениях разметки. [XML] [XMLNS]

2.1 Зависимости

Эта спецификация опирается на некоторые базовые спецификации.

DOM

Стандартизированный пользовательский агент должен поддерживать часть функциональности (определенную в Событиях DOM и Ядре Dom), на которую опирается данная спецификация. [Событиях DOM2] [Ядро DOM3]

HTML 5

Определение объекта Window и определение кодировки символов для text/html ресурсов в данной спецификации зависят от HTML 5. Стандартизированный пользовательский агент должен поддерживать эти возможности. [HTML5]

Черновик Объект Window 1.0 не объявлен нормативным, так как он больше не поддерживается, и HTML 5 определяет объект Window более детально. Эта спецификация уже зависит от HTML 5, поэтому здесь больше нечего добавить.

HTTP

Стандартизированный пользовательский агент должен поддерживать одну из версий HTTP протокола. Ему следует поддерживать HTTP методы, указанные в вызове методов (Method) и как минимум должен поддерживать следующие методы:

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

Остальные требования касательно HTTP указаны в соответствующей спецификации. [RFC2616]

2.2 Терминология

Говорят о регистро-независимом совпадении строк s1 и s2, если после преобразования диапазона символов A-Z в диапазон a-z обе строки идентичны.

Два URI имеют общее начало если после их приведения к базовому виду согласно разделу 5.3.3 RFC 3987, компоненты хост и порт одинаковы. Если любой из URI не имеет компонента хост, то URI не могут рассматриваться как имеющие общее начало. [RFC3987]

Термины начало и атрибут обработчика событий DOM определены в спецификации HTML 5. [HTML5]

2.3 Расширяемость

Расширение API, определенного данной спецификацией как таковое отсутствует. Пользовательским агентам, рабочим группам и остальным заинтересованным сторонам следует обсуждать расширение API на соответствующем публичном форуме, предпочтительно public-webapi@w3.org.

3. Соображения безопасности

Кроме требований указанные в этой спецификации, реализации могут, на свое усмотрение, не выводить некоторые заголовки, например HttpOnly cookies.

4. Объект XMLHttpRequest

Объект XMLHttpRequest может быть использован скриптами для программного способа соединения с их исходными серверами по протоколу HTTP.

Объекты, реализующие интерфейс XMLHttpRequest должны также реализовывать интерфейс EventTarget. [События DOM2]

Объекты реализующие интерфейс Window должны обеспечивать работу конструктора XMLHttpRequest() [HTML5]

В ECMAScript это может выглядеть следующим образом:

var client = new XMLHttpRequest();

Когда вызван конструктор XMLHttpRequest(), в созданном объекте сохраняется постоянный указатель на связанный объект Document. Это указатель на Document Связанный объект Document возвращается из атрибута document объекта, для которого был вызван конструктор XMLHttpRequest() (объект Window). Указатель может стать "null", если объект уничтожен.

Реализации могут различными способами выполнять эти действия, если результаты работы будут идентичны результатам, приведенным в данном руководстве.

Если iframe - объект Window, то client будет иметь указатель на iframe.document в следующем примере:

var client = new iframe.XMLHttpRequest()

interface XMLHttpRequest {
  // обработчик событий
  attribute EventListener onreadystatechange;

  // состояние
  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;
  readonly attribute unsigned short readyState;

  // запрос
  void open(in DOMString method, in DOMString url);
  void open(in DOMString method, in DOMString url, in boolean async);
  void open(in DOMString method, in DOMString url, in boolean async, in DOMString user);
  void open(in DOMString method, in DOMString url, in boolean async, in DOMString user, in DOMString password);
  void setRequestHeader(in DOMString header, in DOMString value);
  void send();
  void send(in DOMString data);
  void send(in Document data);
  void abort();

  // ответ
  DOMString getAllResponseHeaders();
  DOMString getResponseHeader(in DOMString header);
  readonly attribute DOMString responseText;
  readonly attribute Document responseXML;
  readonly attribute unsigned short status;
  readonly attribute DOMString statusText;
};

Объект XMLHttpRequest может находиться в пяти состояниях: UNSENT (НЕ ПОСЛАН), OPENED (ОТКРЫТ), HEADERS_RECEIVED (ЗАГОЛОВКИ ПОЛУЧЕНЫ), LOADING (ЗАГРУЗКА) и DONE (ЗАВЕРШЕНО). Текущее состояние можно узнать с помощью атрибута readyState. Описанные ниже методы позволяют определить момент, когда происходит смена состояния.

Когда объект XMLHttpRequest только что инициализирован, он должен быть в состоянии UNSENT. Это состояние представлено константой UNSENT со значением 0.

Состояние OPENED объект получает, когда был успешно вызван метод open(). Пока объект в этом состоянии, заголовки запроса могут быть установлены методом setRequestHeader() и запрос может быть сделан методом send(). Это состояние представлено константой OPENED со значением 1.

У состояния OPENED имеется связанный с ним флаг send() который может принимать значения "true" или "false". Начальное значение флага send() - "false".

Состояние HEADERS_RECEIVED - это состояние объекта, когда все заголовки получены. Это состояние представлено константой HEADERS_RECEIVED со значением 2.

Состояние LOADING - это состояние объекта, когда начата загрузка тела ответа. Это состояние представлено константой LOADING со значением 3.

Состояние DONE - это состояние объекта, когда либо завершена загрузка данных, либо что-то пошло не так в процессе их передачи (например бесконечные перенаправления). Это состояние представлено константой DONE со значением 4.

У состояния DONE есть связанный с ним флаг ошибки (error flag) который может принимать значения "true" или "false". Начальное значение флага ошибки - "false".

Тело ответа - это или фрагмент тела, уже полученный на данный момент (состояние LOADING), или окончательное тело (состояние DONE). Если тела нет , то тело ответа установлено (response entity body) в "null".

Тело текстового ответа (text response entity body) - это DOMString, представляющая тело ответа. Тело текстового ответа - это величина, возвращаемая следующим алгоритмом:

1. Если тело ответа "null" - вернуть пустую строку и закончить выполнение этих шагов.

2. Пусть charset (кодировка символов) будет "null".

3. Если заголовок Content-Type не установлен или заголовок Content-Type содержит MIME-тип text/xml, application/xml или заканчивается на +xml (игнорируя любые параметры) - использовать правила для определения кодировки символов, установленные в спецификации XML. Пусть charset будет определенной кодировкой.

4. Если заголовок Content-Type содержит MIME-тип text/html - использовать правила для определения кодировки символов, установленные в спецификации HTML 5. Пусть charset будет определенной кодировкой. [HTML5]

5. Если MIME-тип, определенный в заголовке Content-Type содержит параметр charset и charset установлена в "null" - пусть charset будет равна значению этого параметра.

   Алгоритм, описанный в спецификациях XML и HTML, таким же образом рассматривает заголовок Content-Type.

6. Если charset "null", тогда, для каждой строки в следующей таблице, начиная с первой и далее по ходу, проверятся совпадение первых bytes с байтами, указанными в первом столбце. В случае совпадения, charset устанавливается из второго столбца. Если совпадений нет, charset остается "null".

   Байты в шестнадцатеричной записи	Описание
   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. Если charset "null" - пусть charset будет UTF-8.

8. Возвращается результат декодирования тела ответа с использованием charset. Заменяются байты и их последовательности, которые являются некорректными согласно charset с одиночным U+FFFD символом.

Авторы одобряют простое кодирование различных ресурсов в кодировке UTF-8.

Тело XML ответа - это либо Document, представляющий тело ответа, либо null. Тело XML ответа - это величина, возвращаемая следующим алгоритмом:

1. Если тело ответа "null" - прекратить выполнение этих шагов и вернуть null.

2. Если заголовок Content-Type установлен и он не содержит MIME-тип (игнорируя любые параметры) text/xml, application/xml или заканчивающийся на +xml - прекратить выполнение этих шагов и вернуть null. (Не заканчивать выполнение этих шагов, если заголовка Content-Type нет вообще.)

3. Произвести разбор тела ответа в дерево документа согласно спецификации XML. Пусть результат будет parsed document (разобранным документом). Если это не удается сделать (неподдерживаемая кодировка символов, ошибка пространства имен, и так далее) - закончить эти шаги и вернуть null. [XML] [XMLNS]

   Скрипты в результирующем дереве документы не будут выполнены, ресурсы не будут загружены и связанная XSLT не будет применена.

4. Вернуть объект реализующий интерфейс Document, представленный в parsed document (разобранном документе).

onreadystatechange, тип EventListener

Это атрибут обработчика прерываний DOM и он должен вызываться каждый раз, когда событие readystatechange происходит с объектом.

readyState, тип unsigned short, readonly (только чтение)

При запросе, этот атрибут должен возвращать константу, соответствующую текущему состоянию объекта.

open(method, url, async, user, password), method (метод)

При вызове, пользовательский агент должен выполнять следующие шаги:

1. Присвоить переменной method (внутренней) значение аргумента method.

2. Если значение переменной method не удовлетворяет правилам вызова методов, описанным в разделе 5.1.1 RFC 2616 - сгенерировать исключение SYNTAX_ERR и прекратить выполнение этих шагов. [RFC2616]

3. Если переменная method регистро-независимо совпадает с CONNECT, DELETE, GET, HEAD, OPTIONS POST, PUT, TRACE, или TRACK - пусть значение переменной method будет именем совпавшего метода в верхнем регистре.

4. Если переменная method содержит CONNECT, TRACE, или TRACK - пользовательскому агенту следует сгенерировать исключение SECURITY_ERR и прекратить выполнение этих шагов.

5. Если у аргумента url есть идентификатор фрагмента (#), отбросить его и присвоить переменной url результат этой операции.

6. Если переменная url - относительная ссылка - определить полный путь, используя атрибут baseURI указателя на объект Document. В случае неудачи сгенерировать исключение SYNTAX_ERR и прекратить выполнение этих шагов.

7. Если переменная url содержит неподдерживаемую схему - сгенерировать исключение NOT_SUPPORTED_ERR и прекратить выполнение этих шагов.

8. Если поле "user:password" не подходит для получения userinfo согласно соответствующей схеме (раздел 3.2.1 RFC 3986), а переменная url содержит это поле - сгенерировать исключение SYNTAX_ERR и прекратить выполнение этих шагов. [RFC3986]

9. Если переменная url содержит поле "user:password" - присвоить переменной user часть с именем пользователя и переменной password часть с паролем.

10. Если переменная url содержит только поле "user" - присвоить переменной user часть с именем пользователя.

11. Если переменная url не имеет общее начало с источником объекта Document, то пользовательскому агенту следует сгенерировать исключение SECURITY_ERR и прекратить выполнение этих шагов.

12. Присвоить переменной async значение аргумента async, или, если аргумент был опущен, значение true.

13. Если аргумент user не был пропущен, и его синтаксис не совпадает с нужным для подходящей схемы аутентификации - сгенерировать исключение SYNTAX_ERR и прекратить выполнение этих шагов.

14. Если аргумент user не был пропущен и он не равен null - присвоить переменной user значение аргумента user в кодировке, указанной соответствующей схемой аутентификации или UTF-8, если схема не определяет кодировку.

    Эти шаги переопределяют любого пользователя, если он был уставлен как аргумент url.

15. Если аргумент user не был пропущен и он равен null - уничтожить переменную user.

16. Если аргумент password не был пропущен и его синтаксис не совпадает с нужным для подходящей схемы аутентификации - сгенерировать исключение SYNTAX_ERR и прекратить выполнение этих шагов.

17. Если аргумент password не был пропущен и он не равен null - присвоить переменной password значение аргумента password в кодировке, указанной соответствующей схемой аутентификации или UTF-8, если схема не определяет кодировку.

18. Если аргумент password не был пропущен и он равен password - уничтожить переменную password.

19. Прекратить выполнение метода send(), установить тело ответа в "null" и очистить список заголовков запроса.

20. Пользовательскому агенту следует остановить всю сетевую активность, за которую отвечает объект.

21. Переключить состояние объекта в OPENED, установить флаг send() в "false" и одновременно вызвать событие readystatechange и вернуть вызов метода.

Наиболее вероятно, что в следующей версии этой спецификации будут определены запросы между сайтами (cross-site requests).

setRequestHeader(header, value), метод

Каждый запрос имеет список заголовков запроса и их значений. Метод setRequestHeader() может быть использован для управления этими величинами и установки новых заголовков.

Если переданный заголовок уже есть в списке заголовков запроса, метод setRequestHeader() просто добавляет к нему новое значение.

При вызове, пользовательский агент должен выполнять следующие шаги:

1. Если состояние объекта не OPENED - сгенерировать исключение INVALID_STATE_ERR и прекратить выполнение этих шагов.

2. Если флаг send() установлен в "true" - сгенерировать исключение INVALID_STATE_ERR и прекратить выполнение этих шагов.

3. Если аргумент header не соответствует формату field-name, определенному в разделе 4.2 RFC 2616 или содержит null - сгенерировать исключение SYNTAX_ERR и прекратить выполнение этих шагов. [RFC2616]

4. Если аргумент value равен null - прекратить выполнение этих шагов. (Не генерировать исключение.)

5. Если аргумент value не соответствует формату field-value, определенному в разделе 4.2 RFC 2616 - сгенерировать исключение SYNTAX_ERR и прекратить выполнение этих шагов. [RFC2616]

6. Из соображений безопасности, выполнение этих шагов следует прекратить, если аргумент header регистро-независимо совпадает с одним из следующих заголовков:

   • Accept-Charset
   • Accept-Encoding
   • Connection
   • Content-Length
   • Content-Transfer-Encoding
   • Date
   • Expect
   • Host
   • Keep-Alive
   • Referer
   • TE
   • Trailer
   • Transfer-Encoding
   • Upgrade
   • Via

7. Также, из соображений безопасности, выполнение этих шагов следует прекратить, если начало аргумента header регистро-независимо совпадает с Proxy- или Sec-.

8. Если аргумента header нет в списке заголовков запроса - добавить аргумент header с соответствующим ему значением value в список и прекратить выполнение этих шагов.

9. Если аргумент header присутствует в списке заголовков запроса - либо использовать несколько заголовков, либо совместить значения или использовать эти методы в совокупности (раздел 4.2, RFC 2616). [RFC2616]

См. также метод send() касательно использования пользовательским агентом заголовков для кэширования, аутентификации, прокси и cookies.

// Результатом выполнения данного скрипта
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send();

// ...будет отправка следующего заголовка:
...
X-Test: one, two
...

send(data), метод

Метод send() инициирует запрос, а его опциональный аргумент представляет собой содержание запроса.

Авторам настоятельно рекомендуется убедиться, что они указали заголовок Content-Type посредством метода setRequestHeader() перед вызовом метода send() со значением аргумента не равным null

При вызове, пользовательский агент должен выполнять следующие шаги (если не указано иначе). Выполнение алгоритма может быть прервано, если вызван метод open() или abort(). Когда выполнение алгоритма send() отменено, пользовательский агент должен прервать выполнение алгоритма после выполнения текущего шага.

Следующий алгоритм не может быть прерван скриптом, если значение async установлено в false. Он может быть прерван, только если значение async установлено в true и только после того, как вызов метода send() завершился.

1. Если состояние объекта не OPENED - сгенерировать исключение INVALID_STATE_ERR и прекратить выполнение этих шагов.

2. Если флаг send() установлен в "true" - сгенерировать исключение INVALID_STATE_ERR и прекратить выполнение этих шагов.

3. Если значение переменной async равно true - установить флаг send() в "true".

4. Если значение переменной method равняется GET - действовать так же, как в случае когда аргумент data равняется null.

   Если аргумент data не опущен и не равен null использовать его в качестве тела соблюдая правила описанные в разделе 7.2 RFC 2616: [RFC2616]

   data это DOMString

   Закодировать data, используя UTF-8 для передачи.

   Если заголовок Content-Type установлен с помощью setRequestHeader() - установить параметр charset заголовка в UTF-8.

   data это Document

   Сериализовать data в пространство имен размеченного XML документа и закодированный в соответствии с кодировкой переданной data.inputEncoding, при значении отличном от null, либо UTF-8. Или, если это не удается, потому что Document не может быть сериализован, действовать как если data равняется null.

   Если не было создано заголовка Content-Type с помощью setRequestHeader(), добавить заголовок Content-Type к списку заголовков запроса со значением application/xml;charset=charset, где charset - кодировка использованная для закодирования документа.

   Последующее внесение изменений в Document не влияет на передаваемые данные.

   data это не DOMString или Document

   Применить механизмы приведения к строке языка принимающей стороны к data и считать результат, как если data это DOMString. Или, если это не удается, действовать, как если аргумент data равен null.

   Если аргумент data был опущен, или равен null, тело запроса не будет ничего содержать (тело не будет использовано при запросе).

5. Сделать запрос к адресу из переменной url, используя HTTP метод в переменной method, имя пользователя в переменной user (если задано) и пароль в переменной password (если задано), учитывая тело, список заголовков запроса и правила, перечисленные после этого списка шагов.

6. Одновременно вызвать событие readystatechange .

   Состояние объекта не изменяется. Событие отправляется из исторических соображений.

7. Если значение переменной async равно true - завершить вызов метода send(). (Не прерывая выполнение алгоритма.)

8. При скачивании ресурса должны соблюдаться следующие правила.

   Если ответ - это HTTP перенаправление

   Если перенаправление не противоречит безопасности (например, общее начало) или предосторожностям против бесконечного зацикливания и способ поддерживается, прозрачно перейти по ссылке и к началу данного шага (шаг 8).

   HTTP налагает требования на пользовательский агент касательно сохранения метода и тела запроса при перенаправлении, а также требует уведомлять пользователей о различных типах автоматического перенаправления.

   Иначе, выполнить следующую последовательность шагов:

   1. Установить тело ответа в "null", флаг ошибки в "true" и сбросить список заголовков запроса.

   2. Одновременно поменять состояние на DONE.

   3. Если значение переменной async равно false сгенерировать исключение NETWORK_ERR и прекратить выполнение всего алгоритма.

   4. Одновременно вызвать событие readystatechange .

   5. Закончить работу общего алгоритма.

   Возможно, будущая версия объекта XMLHttpRequest в этом месте будет вызывать событие error.

   Если пользователь отменяет закачку

   Выполнить следующую последовательность шагов:

   1. Установить тело ответа в "null", флаг ошибки в "true" и сбросить список заголовков запроса.

   2. Одновременно поменять состояние на DONE.

   3. Если значение переменной async равно false сгенерировать исключение ABORT_ERR и прекратить выполнение всего алгоритма.

   4. Одновременно вызвать событие readystatechange .

   5. Закончить работу общего алгоритма.

   Возможно, будущая версия объекта XMLHttpRequest в этом месте будет вызывать событие abort.

   В случае ошибок сети

   В случае ошибок DNS, или других типов ошибок сети, выполнить следующую последовательность шагов. За исключением HTTP ответов, которые указывают на какой либо тип ошибки, как например HTTP статус код 410.

   1. Установить тело ответа в "null", флаг ошибки в "true" и сбросить список заголовков запроса.

   2. Одновременно переключить состояние в DONE.

   3. Если значение переменной async равно false сгенерировать исключение NETWORK_ERR и прекратить выполнение всего алгоритма.

   4. Одновременно вызвать событие readystatechange.

   5. Закончить работу общего алгоритма.

   Возможно, будущая версия объекта XMLHttpRequest в этом месте будет вызывать событие error.

   Когда все HTTP заголовки получены

   Когда все HTTP заголовки получены, перед получением тела сообщения (если есть), выполнить следующие шаги:

   1. Одновременно переключить состояние в HEADERS_RECEIVED.

   2. Одновременно вызвать событие readystatechange.

   Когда первый байт (или больше) тела ответа получен(ы)

   Если тела ответа не существует

   1. Одновременно переключить состояние в LOADING.

   2. Одновременно вызвать событие readystatechange.

   Наконец, когда весь ресурс был скачан, перейти к следующему шагу.

9. Когда запрос успешно выполнен и ресурс загружен, одновременно переключить состояние в DONE, затем вызвать событие readystatechange, и завершить вызов метода send() в случае, если значение переменной async было установлено в false.

Если пользовательский агент позволяет использование прокси, ему следует в соответствии с этим изменить запрос; др.сл., соединиться с прокси вместо сервера, модифицировать Request-Line и отправить заголовки Proxy-Authorization как указано.

Если пользовательский агент позволяет использование прокси, ему следует в соответствии с этим изменить запрос; др.сл., соединиться с прокси вместо сервера, модифицировать Request-Line и отправить заголовки Proxy-Authorization как указано.

Если пользовательский агент поддерживает HTTP аутентификацию, ему следует считать запросы исходящие от этого объекта частью защищенного пространства, которое включает запрошенные URI, отправлять заголовки Authorization и правильно обрабатывать запросы 401 Unauthorized. Если аутентификация не удалась, пользовательским агентам следует запрашивать у пользователя идентификационные данные. [RFC2617]

Если пользовательский агент поддерживает HTTP Управление Состоянием, ему следует сохранять, удалять и отправлять cookies(полученные из заголовков ответа Set-Cookie и Set-Cookie2, и отправленные заголовком Cookie). [RFC2965]

Если пользовательский агент обеспечивает функционирование HTTP кэша, ему следует учитывать заголовки запроса Cache-Control устанавливаемые скриптом (например, Cache-Control: no-cache не кэшируется). Он не должен автоматически отправлять заголовки запроса Cache-Control или Pragma, пока пользователь не запросит такого действия (например, намеренно перезагружая страницу). Ответы 304 Not Modified, являющиеся результатом сгенерированного пользовательским агентом запроса, должны быть представлены как ответы 200 OK с соответствующим содержанием. Пользовательский агент должен позволять скриптам отменять автоматическую проверку кэша устанавливая заголовки запроса (например, If-None-Match, If-Modified-Since) при которых ответы 304 Not Modified должны быть пропущены. [RFC2616]

Если пользовательский агент обеспечивает взаимодействие с серверным механизмом обмена информацией (content-negotiation), ему следует соответственно установить заголовки Accept-Encoding и Accept-Charset; он не должен автоматически устанавливать заголовок Accept. Если заголовок Accept-Language не установлен посредством метода setRequestHeader(), пользовательскому агенту следует его предоставить. Содержимое ответов на подобные запросы должно быть автоматически перекодировано из исходной кодировки. [RFC2616]

abort(), метод

При вызове, пользовательский агент должен выполнять следующие шаги (если не указано иначе):

1. Прекратить выполнение алгоритма send(), установить тело ответа в "null", флаг ошибки в "true" и удалить все зарегистрированные заголовки запроса.

2. Пользовательскому агенту следует прекратить любую сетевую активность подконтрольную данному объекту.

3. Если состояние объекта UNSENT, OPENED и флаг send() установлен в "false", или состояние DONE - перейти к следующему шагу.

   Иначе, переключить состояние в DONE, установить флаг send() в "false" и одновременно вызвать событие readystatechange .

4. Переключить состояние в UNSENT. (Не вызывать событие readystatechange.)

   Возможно, будущая версия объекта XMLHttpRequest в этом месте будет вызывать событие abort.

getAllResponseHeaders(), метод

При вызове, пользовательский агент должен выполнять следующие шаги:

1. Если состояние UNSENT или OPENED - сгенерировать исключение INVALID_STATE_ERR и прекратить выполнение этих шагов.

2. Если флаг ошибки установлен в "true" - вернуть пустую строку и прекратить выполнение этих шагов.

3. Вернуть все HTTP заголовки в виде одной строки, где каждая строка заголовка отделена парой символов U+000D (CR) U+000A (LF) за исключением строки статуса.

// Данный скрипт:
var client = new XMLHttpRequest();
client.open("GET", "test.txt", true);
client.send();
client.onreadystatechange = function() {
 if(this.readyState == 3) {
  print(this.getAllResponseHeaders());
 }
}

// ...должен вывести что-то похожее на следующий текст:
Date: Sun, 24 Oct 2004 04:58:38 GMT
Server: Apache/1.3.31 (Unix)
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8

getResponseHeader(header), метод

При вызове метода пользовательский агент должен выполнять следующие шаги:

1. Если состояние UNSENT или OPENED - сгенерировать исключение INVALID_STATE_ERR и прекратить выполнение этих шагов.

2. Если аргумент header не совпадает с выводом field-name - вернуть null и прекратить выполнение этих шагов.

3. Если флаг ошибки равен "true" - вернуть null и прекратить выполнение этих шагов.

4. Если аргумент header регистро-независимо совпадает с несколькими HTTP заголовками последнего отправленного запроса, вернуть значения этих заголовков в виде одной объединенной строки, отделенными друг от друга символами U+002C и U+0020 и прекратить выполнение этих шагов.

5. Если аргумент header регистро-независимо совпадает с одним HTTP заголовком последнего отправленного запроса, вернуть значение этого заголовка и прекратить выполнение этих шагов.

6. Вернуть null.

// Данный скрипт:
var client = new XMLHttpRequest();
client.open("GET", "test.txt", true);
client.send();
client.onreadystatechange = function() {
 if(this.readyState == 3) {
  print(client.getResponseHeader("Content-Type"));
 }
}

// ...должен вывести что-то похожее на следующий текст:
text/plain; charset=utf-8

responseText, тип DOMString, readonly (только чтение)

При запросе, пользовательский агент должен выполнять следующие шаги:

1. Если состояние не LOADING или DONE - вернуть пустую строку и прекратить выполнение этих шагов.

2. Вернуть тело текстового ответа.

responseXML, тип Document, readonly (только чтение)

При запросе, пользовательский агент должен выполнять следующие шаги:

1. Если состояние не равно DONE - вернуть null и прекратить выполнение этих шагов.

2. Вернуть тело XML ответа.

status, тип unsigned short, readonly (только чтение)

При запросе, если возможно, пользовательский агент должен вернуть код ответа HTTP (status code), посланный сервером (обычно 200 для успешного запроса). Иначе, если код недоступен, пользовательский агент должен сгенерировать исключение INVALID_STATE_ERR.

statusText, тип DOMString, readonly (только чтение)

При запросе, если возможно, пользовательский агент должен вернуть текст состояния (status text) HTTP, посланный сервером (появляется после кода ответа). Иначе, пользовательский агент должен сгенерировать исключение INVALID_STATE_ERR.

4.1 События объекта XMLHttpRequest

Этот раздел описывает различные события, которые могут отправляться объектам, реализующим интерфейс XMLHttpRequest. В данной версии спецификации определено только одно событие.

readystatechange

Когда пользовательский агент отправляет событие readystatechange (как описано выше), оно не должно задержаться, не должно иметь возможность отмены и должно реализовывать интерфейс Event. Его атрибут namespaceURI должен быть null. [События DOM2]

4.2 Исключения объекта XMLHttpRequest

Некоторые алгоритмы в этой спецификации могут вызывать исключения. Все эти исключения являются частью группы ExceptionCode и используют объект DOMException, который определен в DOM Level 3 Core. Эта спецификация расширяет группу ExceptionCode несколькими новыми константами, которые перечислены ниже. [DOM3Core]

const unsigned short SECURITY_ERR = 18;
const unsigned short NETWORK_ERR = 101;
const unsigned short ABORT_ERR = 102;

Исключение SECURITY_ERR возбуждается в случае попытки выполнения операции или получения доступа к данным с возможным риском для безопасности или нарушением политики безопасности пользовательского агента.

Ожидается, что исключение SECURITY_ERR будет включено в обновление спецификации DOM Level 3 Core с таким же описанием и значением величины. До тех пор, пока это не произойдет, оно будет определено здесь для использования разработчиками. (Именно поэтому значение константы сильно отличается от значений других исключений.)

Исключение NETWORK_ERR возникает в случае сетевых ошибок при синхронных запросах.

Исключение ABORT_ERR возникает когда пользователь обрывает соединение при синхронном запросе.

Нет в данной спецификации

Этот раздел ненормативный.

Эта спецификация не включает следующие части, которые будут рассматриваться для включения в будущие версии этой спецификации:

• Событие load и атрибут onload;
• Событие error и атрибут onerror;
• Событие progress и атрибут onprogress;
• Событие abort и атрибут onabort;
• Были предложены timers, поэтому возможен атрибут ontimeout;
• Свойство для отключения редиректов;
• responseXML для документов text/html;
• Cross-site (межсайтовый) XMLHttpRequest;
• Взаимодействие responseBody с байтовыми потоками;
• overrideMimeType для исправления MIME-типов;
• getRequestHeader() и removeRequestHeader().

Ссылки

[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. W3C, April 2004.

[ECMAScript]

ECMAScript Language Specification, Third Edition. ECMA, December 1999.

[HTML5]

HTML 5 (work in progress), I. Hickson, D. Hyatt, editors. W3C, 2008.

HTML 5 (work in progress), 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, editors. W3C, September 2006.

[XMLNS]

Namespaces in XML (Second Edition), T. Bray, D. Hollander, A. Layman, R. Tobin, editors. W3C, August 2006.