# jQuery.ajaxTransport()

## jQuery.ajaxTransport ( dataType, handler(options, originalOptions, jqXHR) ) Returns: undefined version added: 1.5

- dataType
  Type: String
  A string identifying the data type to use

- handler(options, originalOptions, jqXHR)
  Type: Function
  A handler to return the new transport object to use with the data type provided in the first argument.

Description: Creates an object that handles the actual transmission of Ajax data.

A transport is an object that provides two methods, `send` and `abort`, that are used internally by `$.ajax()` to issue requests. A transport is the most advanced way to enhance `$.ajax()` and should be used only as a last resort when prefilters and converters are insufficient.

Since each request requires its own transport object instance, transports cannot be registered directly. Therefore, you should provide a function that returns a transport instead.

Transports factories are registered using `$.ajaxTransport()`. A typical registration looks like this:

    $.ajaxTransport(function( options, originalOptions, jqXHR ) {
      if( /* transportCanHandleRequest */ ) {
        return {
          send: function( headers, completeCallback ) {
            // Send code
          },
          abort: function() {
            // Abort code
          }
        };
      }
    });

where:

- `options` are the request options
- `originalOptions` are the options as provided to the ajax method, unmodified and, thus, without defaults from ajaxSettings
- `jqXHR` is the jqXHR object of the request
- `headers` is an object of (key-value) request headers that the transport can transmit if it supports it
- `completeCallback` is the callback used to notify ajax of the completion of the request

`completeCallback` has the following signature:

    function( status, statusText, responses, headers ) {}

where:

- `status` is the HTTP status code of the response, like 200 for a typical success, or 404 for when the resource is not found.
- `statusText` is the statusText of the response.
- `responses` (Optional) is An object containing dataType/value that contains the response in all the formats the transport could provide (for instance, a native XMLHttpRequest object would set reponses to `{ xml: XMLData, text: textData }` for a response that is an XML document)
- `headers` (Optional) is a string containing all the response headers if the transport has access to them (akin to what `XMLHttpRequest.getAllResponseHeaders()` would provide).

Just like prefilters, a transport's factory function can be attached to a specific dataType:

    $.ajaxTransport( "script", function( options, originalOptions, jqXHR ) {
      // Will only be called for script requests
    });

The following example shows how a minimal image transport could be implemented:

    $.ajaxTransport( "image", function( s ) {
      if ( s.type === "GET" && s.async ) {
        var image;
        return {
          send: function( _ , callback ) {
            image = new Image();
            function done( status ) {
              if ( image ) {
                var statusText = ( status === 200 ) ? "success" : "error",
                  tmp = image;
                image = image.onreadystatechange = image.onerror = image.onload = null;
                callback( status, statusText, { image: tmp } );
              }
            }
            image.onreadystatechange = image.onload = function() {
              done( 200 );
            };
            image.onerror = function() {
              done( 404 );
            };
            image.src = s.url;
          },
          abort: function() {
            if ( image ) {
              image = image.onreadystatechange = image.onerror = image.onload = null;
            }
          }
        };
      }
    });

#### Handling Custom Data Types

The jQuery Ajax implementation comes with a set of standard dataTypes, such as text, json, xml, and html.

Use the `converters` option in `$.ajaxSetup()` to augment or modify the data type conversion strategies used by `$.ajax()`.

The unminified jQuery source itself includes a list of default converters, which effectively illustrates how they can be used:

    // List of data converters
    // 1) Key format is "source_type destination_type"
    //    (a single space in-between)
    // 2) The catchall symbol "*" can be used for source_type
    converters: {
      // Convert anything to text
      "* text": window.String,
      // Text to html (true = no transformation)
      "text html": true,
      // Evaluate text as a json expression
      "text json": jQuery.parseJSON,
      // Parse text as xml
      "text xml": jQuery.parseXML
    }

When you specify a `converters` option globally in `$.ajaxSetup()` or per call in `$.ajax()`, the object will map onto the default converters, overwriting those you specify and leaving the others intact.

For example, the jQuery source uses `$.ajaxSetup()` to add a converter for "text script":

    jQuery.ajaxSetup({
      accepts: {
        script: "text/javascript, application/javascript"
      },
      contents: {
        script: /javascript/
      },
      converters: {
        "text script": jQuery.globalEval
      }
    });