Web Gadget SDK Web Gadget SDK
[Back to Web Gadget API Reference]
Web.Network Class
Provides methods to create network proxied network requests so that cross-domain calls can be made.
createBatch Method
Creates and returns a batch network request object.
Syntax
Web.Network.createBatch(enumPriority, objContext);
Parameters
Parameter Description
enumPriority Optional. The priority of the request. If not specified, images default to low and all other resources default to medium. Supported values are:
  • Web.Utility.Prioritizer.Priorities.High
  • Web.Utility.Prioritizer.Priorities.Medium
  • Web.Utility.Prioritizer.Priorities.Low
  • Web.Utility.Prioritizer.Priorities.Lowest
objContext Optional. An object (of any type) passed to the callback after the resource is retrieved. This is useful for passing state through the request.
Return Value
A batch request network object. To batch up network requests, call add() method on the returned object with the appropriate parameters. When you are ready to issue the batch request, call execute() on the returned object. You may also call abort() on the returned object to abort the outstanding network request.
Example
The following sample shows how to create and issue a batch network request.
var batchReq = Web.Network.createBatch(Web.Utility.Prioritizer.Priorities.Medium);
batchReq.add( enumNetworkType, strUrl, objContext, strPostArgs, objHeader, enumFlags);
batchReq.execute(fnCallback);
...
batchReq.abort();
createRequest Method
Creates and returns a network request object.
Syntax
var netReq = Web.Network.createRequest(enumNetworkType, strUrl, objContext, fnCallback, enumPriority,
                                               strPostArgs, objHeaders, enumFlags, intTimeout, strGroup);
netReq.execute();
Parameters
Parameter Description
enumNetworkType Specifies the type of resource being requested. The supported types are:
  • Web.Network.Type.CSS
  • Web.Network.Type.Image
  • Web.Network.Type.Script
  • Web.Network.Type.XML
  • Web.Network.Type.XMLGet
  • Web.Network.Type.XMLPost

CSS is special in that the stylesheet is added to the page when requested. This is due to the browser implementation.
strUrl The URL of the resource requested.
objContext Optional. An object (of any type) passed to the callback after the resource is retrieved. This is useful for passing state through the request.
fnCallback Optional. The function to call after the resource is retrieved. If null is specified, the resource will be downloaded but you will receive no notification as to when this occurs.
enumPriority Optional. The priority of the request. If not specified, images default to low and all other resources default to medium. Supported values are:
  • Web.Utility.Prioritizer.Priorities.High
  • Web.Utility.Prioritizer.Priorities.Medium
  • Web.Utility.Prioritizer.Priorities.Low
  • Web.Utility.Prioritizer.Priorities.Lowest
strPostArgs Optional. Specifies the postString that is provided to the send() method for xml requests. This argument is ignored for other request types.
objHeaders Optional. An associative array of headers to be specified for resources of type XMLPost.
enumFlags Optional. Flags that modify how the outgoing request is managed. These flags can be OR'ed together:
  • Web.Network.Flags.SERIALIZE
  • Web.Network.Flags.DUPLICATE

By default, all requests can be run in parallel. In addition to parallel requests, you can force a request to be serialized. Only one serialized request will occur at a time (although parallel requests may be running simultaneously). When there are items in the serialized stack and no serialized requests are executing, it is guaranteed the next open slot (takes precedence over the parallel stack).

By default, any requests that completely match an existing request (including the callback) will not be executed. If a new request matches an existing request but has a different callback, we will only make a single request and handle the multiple callbacks when the item is returned.

If you want to force a unique request, specify the DUPLICATE flag. This flag will guarantee that the request will not be combined with an existing request.

intTimeout Optional. This argument specifies the longest duration a request should execute before considered timing out. Typically you can rely on the browser to timeout a request and that will be handled appropriately. However, you can specify a fixed limit if desired.
strGroup Optional. This argument allows you to group independent requests. You can later call Web.Network.AbortGroup(strGroup) to abort any executing and pending requests in the specified group. This is useful to simulate the traditional web-page navigation model where navigating away from the page preempts requests. You can use this to support similar functionality within a web-page (e.g,. user switches views and you want to stop requests for the prior view).
Return Value
A network request object. To issue the network request, call execute() on the returned object. Call abort() on the returned object for aborting the outstanding request.
Example - RSS Proxy
In this example, we are creating a request for a RSS feed. We specify that the request should use the RSS proxy service to bypass cross-domain restriction. We also specify that we only want 5 items to be returned.
var r = Web.Network.createRequest(Web.Network.Type.XML, "http://msdn.microsoft.com/rss.xml", {proxy:"rss", numItems:5}, CallbackFn);
r.execute();

function CallbackFn(response)
{
    // Check response code to make sure it was successful
    if ( response.status == 200 )
    {
        var rss = Start.Util.ParseRssResponse(response);

        if (rss.channels.length > 0)
        {
            var channel = rss.channels[0];
            for (var i = 0; i < channel.items.length; ++i)
            {
                var title = channel.items[i].title;
                var link = channel.items[i].link;
                var description = channel.items[i].description;

                        // do something useful with this
                ...
            }
        }
    }
}
Example - Generic Proxy
In this example, we illustrate how to consume general XML data. You should use the "generic" proxy in this case.
var r = Web.Network.createRequest(Web.Network.Type.XML, "http://somedomain.com/SomeXml.xml", {proxy:"generic"}, CallbackFn);
r.execute();

function CallbackFn(response)
{
    // Check response code to make sure it was successful
    if ( response.status == 200 )
    {
        // make sure you have the proper casing in the line below.
        // IE6 will also tolerate response.responseXml, but it will not work in other browsers.
        var root = response.responseXML.documentElement;

        if (root)
        {
                    for (var i = 0; i < root.childNodes.length; ++i)
            {
                            switch(root.childNodes[i].nodeName)
                { 
                    // do something useful with this
                    ....
                           }
            }
        }
    }
   
}
Example - Bypassing Proxy
In this example, we show how to make a direct network request without a proxy. Note that you should almost never do this, unless you are making a request to the same domain that your Gadget is loaded from. Note that the domain your Gadget is loaded from is not the same domain that your manifest and JavaScript files reside at. All 3rd party Gadgets are actually loaded from the gadgets.start.com domain.
var r = Web.Network.createRequest(Web.Network.Type.XML, "http://SomeDomain/SomeResource", {proxy:"none"}, CallbackFn);
r.execute();
Example - Consuming a Web Service
In this example, we show how to consume a web service using the Web.Network.createRequest method.
function TrackPackage(trackNum)
{

    // In the code below, we are calling a web service with the following function prototype:
    // public TrackingResponse GetTrackingInfo(string trackingNumber)

    var url = "http://SomeDomain.com/WebServices/SomeService.asmx";
    var aObjHeaders = new Array();
    aObjHeaders["SOAPAction"] = "http://tempuri.org/GetTrackingInfo";
    aObjHeaders["Content-Type"] = "text/xml";

    var strPostArgs = new Web.StringBuilder();
    strPostArgs.append("<?xml version=\"1.0\" encoding=\"utf-8\"?>");
    strPostArgs.append("<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" ");
    strPostArgs.append("xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">");
    strPostArgs.append("<soap:Body>");
    strPostArgs.append("<GetTrackingInfo xmlns=\"http://tempuri.org\">");
    strPostArgs.append("<trackingNumber>");
    strPostArgs.append(trackNum.toString());
    strPostArgs.append("</trackingNumber>");
    strPostArgs.append("</GetTrackingInfo>");
    strPostArgs.append("</soap:Body>");
    strPostArgs.append("</soap:Envelope>");

    var r = Web.Network.createRequest( Web.Network.Type.XMLPost,                     // Network type
                                                        url,                                          // URL of web service
                                                        null,                                         // Object passed to callback
                                                        CallbackFn,                                   // Callback function
                                                        Web.Utility.Prioritizer.Priorities.Medium,    // Priority
                                                        strPostArgs.toString(),                                         // HTTP Post string
                                                        aObjHeaders );                                // Array of headers

    r.execute();
}
©2006 Microsoft Corporation.