WinJS.Namespace.xhr function

  • Article

Wraps calls to XMLHttpRequest in a promise.

You can use this function in Windows apps using JavaScript for cross-domain requests and intranet requests if you set the capabilities of your app to allow these operations. .

Tip  

 

Syntax

WinJS.Namespace.xhr(options).done( /* Your success and error handlers */ );

Parameters

  • options
    Type: Object

    The options that are applied to the XMLHttpRequest object, as follows:

    • type: Optional. A string that specifies the HTTP method used to open the connection, such as GET, POST, or HEAD. This parameter is not case-sensitive. If the type is not specified, the default is GET”. For more details, see the XMLHttpRequest.open documentation for the bstrMethod parameter.
    • url: Required. A string that specifies either the absolute or relative URL of the XML data or server-side XML Web services.
    • user: Optional. A string that specifies the name of the user for authentication. If this parameter is empty or missing, and the site requires authentication, the component displays a logon window.
    • password: Optional. A string that specifies the password for authentication. This parameter is ignored if the user parameter is empty or missing.
    • responseType: Optional. A string that specifies the type of the expected response from a GET request. The types are:

      • text (the default): The type of response and responseText is String.

      • arraybuffer: The type of response is an ArrayBuffer. This type is used to represent binary content as an array of type Int8 or Int64, or of another integer or float type. (See Typed Arrays for more information about the different typed arrays currently supported in JavaScript.) responseText and responseXML are undefined.

      • blob: The type of response is a Blob. This is used to represent binary content as a single binary entity. responseText and responseXML are undefined.

      • document: The type of response is an XML Document Object Model (XML DOM) object. This is used to represent XML content, that is, content that has a MIME type of "text/xml". If the MIME type is anything other than "text/xml", the responseXML is of the same type, and responseText is undefined.

      • json: The type of response is String. This is used to represent JSON strings. responseText is also of type String, and responseXML is undefined.

        Note  As of Windows 10, when responseType is set to json, the responseText is not accessible and the response is a JavaScript object. Behavior on Windows 8.1 and earlier remains as described above.

         

      • ms-stream: The type of response is msStream, and responseText and responseXML are undefined. This response type is not defined in the W3C specification, but it is supported to make it easier to handle streaming data. For more information, see XMLHttpRequest enhancements.

    • headers: Optional. An object whose property names are used as header names and property values are used as header values, passed to the XMLHttpRequest.setRequestHeader method. See the XMLHttpRequest documentation for more details.
    • data: Required. An object containing data that is passed directly to the XMLHttpRequest.send method. See the XMLHttpRequest documentation for more details.
    • customRequestInitializer: Optional. A function that you can use to do preprocessing on the XMLHttpRequest.

Return value

Type: Promise**

A promise that returns the XMLHttpRequest object when it completes.

Remarks

For general information about how to use WinJS.xhr, see Quickstart: Connecting to a web service with WinJS.xhr and Quickstart: using promises.

Examples

The following code shows how to use the completed, error, and progress methods with this function.

WinJS.xhr(options).done(
        function completed(request) {
            // handle completed download.
        }, 
        function error(request) {
            // handle error conditions.
        }, 
        function progress(request) {
            // report on progress of download.
        });

Downloading an RSS feed The following code shows how to use WinJS.xhr to get an RSS feed from a blog and display the title of the blog in the app. Since it uses the done method, the function throws an error if the call fails.

In a Blank app in Visual Studio, add the following code to the default.html page.

<div id='divResult'>No results yet.</div>

In the JavaScript file associated with the HTML page (js/default.js), replace the existing code with the following:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (args) {

        // Change RSS feed URL as you need to.
        var resDiv = document.getElementById("divResult"),
            rssURL = "https://blogs.windows.com/windows/b/appbuilder/rss.aspx";

        // Call WinJS.xhr to retrieve an XML feed from the Web.
        WinJS.xhr({
            url: rssURL,
            responseType: "document"
        }).done(

            // When the result has completed, check the status.
            function completed(result) {
                if (result.status === 200) {

                    // Get the XML document from the results. 
                    var xmlDocument = result.responseXML,
                         title = xmlDocument.getElementsByTagName('title')[0];

                    // Update the HTML in the app.
                    resDiv.style.backgroundColor = "lightGreen";
                    resDiv.innerText = "Downloaded RSS feed from the " + title.textContent + " blog.";
                }
            });
    };

    app.start();
})();

Requirements

Minimum WinJS version

WinJS 1.0

Namespace

WinJS.Namespace

See also

Quickstart: Connecting to a web service with WinJS.xhr

XMLHttpRequest