Editor:
Robin Berjon (Joost™) <robin@joost.com>
Revision:
0.9, last modified: 2008-01-16T14:34:21+01:00

Copyright © 2007. All rights reserved.

Abstract

This document specifies XMLHttpRequest as it is made available within the Joost™ client.

Any and all use of the Joost API is subject to the Joost API Terms of Use

The API may change and although we will try and keep these changes to a minimum, some API calls may be deprecated in the future.

Table of Contents

1. Overview

This API is the same as the one provided in most Web browsers and described in the XMLHttpRequest [XHR] specification but with a few minor modifications made either for security reasons or for convenience:

2. XMLHttpRequest

The API description below lists the methods and fields mostly in order to flag the points in which it differs from the original. For more details please refer to the full specification.

The XMLHttpRequest interface

interface XMLHttpRequest {

           attribute EventListener  onreadystatechange;
  readonly attribute Number         readyState;
  void               open(in String method, in String url)
                                        raises(Exception);
  void               open(in String method, in String url, in boolean async)
                                        raises(Exception);
  void               open(in String method, in String url, in boolean async, in String user)
                                        raises(Exception);
  void               open(in String method, in String url, in boolean async, in String user, in String password)
                                        raises(Exception);
  void               setRequestHeader(in String header, in String value)
                                        raises(Exception);
  void               overrideMimeType(in String mimeType);
  void               send();
  void               send(in Document data);
  void               send(in String data);
  void               abort();
  String             getAllResponseHeaders();
  String             getResponseHeader(in String header);
  readonly attribute String         responseText;
  readonly attribute Document       responseXML;
  readonly attribute Number         status;
  readonly attribute String         statusText;
};

Attributes

onreadystatechange of type EventListener

This attribute behaves exactly the same as the one in the original specification [XHR].

readyState of type Number, readonly

This attribute behaves exactly the same as the one in the original specification [XHR].

responseText of type String, readonly

This attribute behaves exactly the same as the one in the original specification [XHR].

responseXML of type Document, readonly

This attribute behaves exactly the same as the one in the original specification [XHR].

status of type Number, readonly

This attribute behaves exactly the same as the one in the original specification [XHR].

statusText of type String, readonly

This attribute behaves exactly the same as the one in the original specification [XHR].

Methods

abort

This method behaves exactly the same as the one found in the original specification [XHR].

No Parameters
No Return Value
No Exceptions
getAllResponseHeaders

This method behaves exactly the same as the one found in the original specification [XHR].

No Parameters
Return Value
All headers as a string.
No Exceptions
getResponseHeader

This method behaves exactly the same as the one found in the original specification [XHR].

Parameters
header of type String
The header to get.
Return Value
The header value.
No Exceptions
open

This method is different from the original specification [XHR] in the following regards:

  • If the value of async is set to a value other than true a SECURITY_ERR will be raised.
  • When url is a relative reference, or uses a scheme other than http, a SYNTAX_ERR will be raised.
  • Joost does not support the "user:password" format in the userinfo production defined in section 3.2.1 of [RFC3986] and will throw a SYNTAX_ERR when encountering it.
  • The following methods are supported: GET, POST, HEAD, PUT, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, MKREDIRECTREF, and UPDATEREDIRECTREF. Any other method causes a SECURITY_ERR exception to be raised.
Parameters
method of type String
The HTTP method to use for the request.
url of type String
The URL to request. Relative URLs are not accepted.
async of type boolean, optional
Whether the request is to be made asynchronously or not. The only accepted value is true, which is also the default.
user of type String, optional
The user to use for authentication.
password of type String, optional
The password to use for authentication.
No Return Value
Exceptions
Exception

Either of SECURITY_ERR or SYNTAX_ERR may be raised.

overrideMimeType

This method is not in the original specification [XHR], but is supported in several browser implementations.

It will cause Joost to use the given media type instead of the one sent with the response. This can be useful in order to obtain XML out of misconfigured servers.

Parameters
mimeType of type String
The desired media type.
No Return Value
No Exceptions
send

This method behaves exactly the same as the one found in the original specification [XHR].

The only part that distinguishes it from the send() method used in Gecko is that it accepts the absence of an argument as equivalent to null.

Parameters
data of varying types (see IDL) , optional
The data to send.
No Return Value
No Exceptions
setRequestHeader

This method is different from the original specification [XHR] in the following regards:

Parameters
header of type String
The header to set for the request.
value of type String
The value of the header to set for the request.
No Return Value
Exceptions
Exception

Either of INVALID_STATE_ERR or SYNTAX_ERR may be raised.

3. References

RFC3986
Uniform Resource Identifier (URI): Generic Syntax, M. Berners-Lee, R. Fielding, and L. Masinter.
XHR
The XMLHttpRequest Object, Anne van Kesteren <annevk@opera.com>.