{"name":"jQuery.ajaxTransport","type":"method","title":"jQuery.ajaxTransport()","deprecated":null,"removed":null,"desc":"Creates an object that handles the actual transmission of Ajax data.","categories":["ajax/low-level-interface","version/1.5"],"entries":[{"return":"undefined","signatures":{"added":"1.5","argument":[{"desc":"A string identifying the data type to use","name":"dataType","type":"String"},{"desc":"A handler to return the new transport object to use with the data type provided in the first argument.","name":"handler(options, originalOptions, jqXHR)","type":"Function"}]},"examples":null,"longdesc":"\n    <p>A transport is an object that provides two methods, <code>send</code> and <code>abort</code>, that are used internally by <code>$.ajax()</code> to issue requests. A transport is the most advanced way to enhance <code>$.ajax()</code> and should be used only as a last resort when prefilters and converters are insufficient.</p>\n    <p>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.</p>\n    <p>Transports factories are registered using <code>$.ajaxTransport()</code>. A typical registration looks like this:</p>\n    <pre><code>\n$.ajaxTransport(function( options, originalOptions, jqXHR ) {\n  if( /* transportCanHandleRequest */ ) {\n    return {\n      send: function( headers, completeCallback ) {\n        // Send code\n      },\n      abort: function() {\n        // Abort code\n      }\n    };\n  }\n});\n    </code></pre>\n    <p>where:</p>\n    <ul>\n      <li><code>options</code> are the request options</li>\n      <li><code>originalOptions</code> are the options as provided to the ajax method, unmodified and, thus, without defaults from ajaxSettings</li>\n      <li><code>jqXHR</code> is the jqXHR object of the request</li>\n      <li><code>headers</code> is an object of (key-value) request headers that the transport can transmit if it supports it</li>\n      <li><code>completeCallback</code> is the callback used to notify ajax of the completion of the request</li>\n    </ul>\n    <p><code>completeCallback</code> has the following signature:</p>\n    <pre><code>\nfunction( status, statusText, responses, headers ) {}\n    </code></pre>\n    <p>where:</p>\n    <ul>\n      <li><code>status</code> is the HTTP status code of the response, like  200 for a typical success, or 404 for when the resource is not found.</li>\n      <li><code>statusText</code> is the statusText of the response.</li>\n      <li><code>responses</code> (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 <code>{ xml: XMLData, text: textData }</code> for a response that is an XML document)</li>\n      <li><code>headers</code> (Optional) is a string containing all the response headers if the transport has access to them (akin to what <code>XMLHttpRequest.getAllResponseHeaders()</code> would provide).</li>\n    </ul>\n    <p>Just like prefilters, a transport's factory function can be attached to a specific dataType:</p>\n    <pre><code>\n$.ajaxTransport( \"script\", function( options, originalOptions, jqXHR ) {\n  // Will only be called for script requests\n});\n    </code></pre>\n    <p>The following example shows how a minimal image transport could be implemented:</p>\n    <pre><code>\n$.ajaxTransport( \"image\", function( s ) {\n  if ( s.type === \"GET\" &amp;&amp; s.async ) {\n    var image;\n    return {\n      send: function( _ , callback ) {\n        image = new Image();\n        function done( status ) {\n          if ( image ) {\n            var statusText = ( status === 200 ) ? \"success\" : \"error\",\n              tmp = image;\n            image = image.onreadystatechange = image.onerror = image.onload = null;\n            callback( status, statusText, { image: tmp } );\n          }\n        }\n        image.onreadystatechange = image.onload = function() {\n          done( 200 );\n        };\n        image.onerror = function() {\n          done( 404 );\n        };\n        image.src = s.url;\n      },\n      abort: function() {\n        if ( image ) {\n          image = image.onreadystatechange = image.onerror = image.onload = null;\n        }\n      }\n    };\n  }\n});\n    </code></pre>\n    <h4 id=\"handling-custom-data-types\">Handling Custom Data Types</h4>\n    <p>The jQuery Ajax implementation comes with a set of standard dataTypes, such as text, json, xml, and html.</p>\n    <p>Use the <code>converters</code> option in <code><a href=\"/jQuery.ajaxSetup/\">$.ajaxSetup()</a></code> to augment or modify the data type conversion strategies used by <code>$.ajax()</code>.</p>\n    <p> The unminified jQuery source itself includes a list of default converters, which effectively illustrates how they can be used: </p>\n    <pre><code>\n// List of data converters\n// 1) Key format is \"source_type destination_type\"\n//    (a single space in-between)\n// 2) The catchall symbol \"*\" can be used for source_type\nconverters: {\n  // Convert anything to text\n  \"* text\": window.String,\n  // Text to html (true = no transformation)\n  \"text html\": true,\n  // Evaluate text as a json expression\n  \"text json\": jQuery.parseJSON,\n  // Parse text as xml\n  \"text xml\": jQuery.parseXML\n}\n    </code></pre>\n    <p>When you specify a <code>converters</code> option globally in <code>$.ajaxSetup()</code> or per call in <code>$.ajax()</code>, the object will map onto the default converters, overwriting those you specify and leaving the others intact.</p>\n    <p>For example, the jQuery source uses <code>$.ajaxSetup()</code> to  add a converter for \"text script\":</p>\n    <pre><code>\njQuery.ajaxSetup({\n  accepts: {\n    script: \"text/javascript, application/javascript\"\n  },\n  contents: {\n    script: /javascript/\n  },\n  converters: {\n    \"text script\": jQuery.globalEval\n  }\n});\n    </code></pre>\n  "}]}