WinJS.xhr function (Windows)

http://msdn.microsoft.com/zh-cn/library/windows/apps/xaml/br229787.aspx

Wraps calls to XMLHttpRequest in a promise.

You can use this function in Windows Store apps built for Windows using JavaScript for cross-domain requests and intranet requests if you set the capabilities of your app to allow these operations. For more information about setting capabilities, see App capability declarations.

Warning  It is now possible to use XMLHttpRequest to upload or download objects greater than a few MB, such as Blob objects and FormData objects, which may take a long time to complete. Since Windows Store apps using JavaScript may be terminated at any time, you should consider using the Windows Runtime background transfer APIs for these operations. For more information about uploading and downloading content, see Quickstart: Uploading a file and Quickstart: Downloading a file. For a general discussion of background transfer, see Transferring data in the background.

Syntax

JavaScript

WinJS.xhr(options).done(  );

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 thebstrMethod 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.
  • ms-stream: The type of response is msStream, and responseText andresponseXML 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 theXMLHttpRequest.setRequestHeader method. See the XMLHttpRequest documentation for more details.
• data: Optional. An object containing data that is passed directly to theXMLHttpRequest.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.

• To see how to set a timeout for WinJS.xhr, see Setting timeout values with WinJS.xhr.

• To see how to handle errors with WinJS.xhr, see How to handle errors with promises.

• To see how to cancel the download operation with WinJS.xhr, see How to cancel a promise.

• To see how to ensure that WinJS.xhr resends your requests, see How to ensure that WinJS.xhr resends requests .

Examples

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

JavaScript

WinJS.xhr(options).done( 

 function completed(request) {
            // handle completed download.
        }, 

 function error(request) {
            // handle error conditions.
        }, 

 function progress(request) {
            // report on progress of download.
        } 

 });

The following code shows how to use WinJS.xhr to get a web page and then report when it succeeds. Since it uses the done method, the function throws an error if the call fails.

JavaScript

...

"divResult">Result

...

var resDiv = document.getElementByIdx_x_x_x("divResult"); 

 WinJS.xhr({ url: "http://www.microsoft.com" }).done( 

 function fulfilled(result) { 

     if (result.status === 200) { 

         resDiv.style.backgroundColor = "lightGreen"; 

         resDiv.innerText = "Success"; 

      } 

 });