flash.net - Details Adobe® AIR® API Reference for HTML Developers

The flash.net package contains the navigateToURL() and sendToURL() functions. You can access these in JavaScript as window.runtime.navigateToURL() and window.runtime.sendToURL() (or as air.navigateToURL() and air.sendToURL() if you use the AIRAliases.js file).

Public Methods

	Function		Defined By

		navigateToURL(request:URLRequest, window:String = null):void Opens or replaces a window in the application that contains the Flash Player container (usually a browser).	flash.net

		sendToURL(request:URLRequest):void Sends a URL request to a server, but ignores any response.	flash.net

Function detail

navigateToURL

()

function

public function navigateToURL(request:URLRequest, window:String = null):void

Runtime Versions:

AIR 1.0,

Opens a URL in the default application for handling the URI scheme. For example, the default system web browser opens for the http: and https: URI schemes.

Important Security Note

Developers often pass URL values to the navigateToURL() function that were obtained from external sources such as FlashVars. Attackers may try to manipulate these external sources to perform attacks such as cross-site scripting. In AIR, attackers could attempt to open other applications. Therefore, developers should validate all URLs before passing them to this function.

Good data validation for URLs can mean different things depending on the usage of the URL within the overall application. The most common data validation techniques include validating that the URL is of the appropriate scheme. For instance, unintentionally allowing javascript: URLs may result in cross-site scripting. Validating that the URL is a within your domain can ensure that the SWF file can't be used as an open-redirector by people who conduct phishing attacks. For additional security, you may also choose to validate the path of the URL and to validate that the URL conforms to the RFC guidelines

In AIR 3 and later, any URI scheme can be used in the ZURL to be launched. If a suitable application is registered with the operating system to handle the URI scheme, then that application is launched. Only AIR content running in the application security sandbox can use arbitrary URI schemes. Content running in other sandboxes can only navigate to file:, mailto:, http: and https: URLs.

Parameters

request:URLRequest — A URLRequest object that specifies the URL to navigate to.

When using the navigateToURL() function, the runtime treats a URLRequest that uses the POST method (one that has its method property set to URLRequestMethod.POST) as using the GET method.

window:String (default = null) — The browser window or HTML frame in which to display the document indicated by the request parameter. You can enter the name of a specific window or use one of the following values:

"_self" specifies the current frame in the current window.
"_blank" specifies a new window.
"_parent" specifies the parent of the current frame.
"_top" specifies the top-level frame in the current window.

If you do not specify a value for this parameter, a new empty window is created. In the stand-alone player, you can either specify a new ("_blank") window or a named window. The other values don't apply.

Throws

	`IOError` — The `digest` property of the `request` object is not `null`. You should only set the `digest` property of a URLRequest object for use calling the `URLLoader.load()` method when loading a SWZ file (an Adobe platform component).

	`SecurityError` — In Flash Player (and in non-application sandbox content in Adobe AIR), this error is thrown in the following situations: Local untrusted SWF files may not communicate with the Internet. You can avoid this situation by reclassifying this SWF file as local-with-networking or trusted. A navigate operation attempted to evaluate a scripting pseudo-URL, but the containing document (usually an HTML document in a browser) is from a sandbox to which you do not have access. You can avoid this situation by specifying `allowScriptAccess="always"` in the containing document. You cannot navigate the special windows `"_self"`, `"_top"`, or `"_parent"` if your SWF file is contained by an HTML page that has set the `allowScriptAccess` to `"none"`, or to `"sameDomain"` when the domains of the HTML file and the SWF file do not match. You cannot navigate a window with a nondefault name from within a SWF file that is in the local-with-filesystem sandbox. You cannot connect to commonly reserved ports. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.

	`Error` — If the method is not called in response to a user action, such as a mouse event or keypress event. This requirement only applies to content in Flash Player and to non-application sandbox content in Adobe AIR.

Example ( How to use this example )

The following example opens the URL http://www.adobe.com in a new browser window and passes data about a user session, captured in a URLVariables object, to the web server.

<html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function init() {
            var url = "http://www.adobe.com";
            var variables = new air.URLVariables();
            variables.exampleSessionId = new Date().getTime();
            variables.exampleUserLabel = "Your Name";
            var request = new air.URLRequest(url);
            request.data = variables;
            try {            
                air.navigateToURL(request);
            }
            catch (e) {
                // handle error here
            }
        }
      </script>
    </head>
    <body onload='init()'>
    </body>
</html>

sendToURL

()

function

public function sendToURL(request:URLRequest):void

Runtime Versions:

AIR 1.0,

Sends a URL request to a server, but ignores any response.

To examine the server response, use the URLLoader.load() method instead.

You cannot connect to commonly reserved ports. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.

You can prevent a SWF file from using this method by setting the allowNetworking parameter of the the object and embed tags in the HTML page that contains the SWF content.

In Flash Player 10 and later, if you use a multipart Content-Type (for example "multipart/form-data") that contains an upload (indicated by a "filename" parameter in a "content-disposition" header within the POST body), the POST operation is subject to the security rules applied to uploads:

The POST operation must be performed in response to a user-initiated action, such as a mouse click or key press.
If the POST operation is cross-domain (the POST target is not on the same server as the SWF file that is sending the POST request), the target server must provide a URL policy file that permits cross-domain access.

Also, for any multipart Content-Type, the syntax must be valid (according to the RFC2046 standards). If the syntax appears to be invalid, the POST operation is subject to the security rules applied to uploads.

For more information related to security, see the Flash Player Developer Center Topic: Security.

Parameters

request:URLRequest — A URLRequest object specifying the URL to send data to.

Throws

	`SecurityError` — Local untrusted SWF files cannot communicate with the Internet. You can avoid this situation by reclassifying this SWF file as local-with-networking or trusted.

	`SecurityError` — You cannot connect to commonly reserved ports. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.

Example ( How to use this example )

The following example passes data about a user session, captured in a URLVariables object, to the application at http://www.yourDomain.com/application.jsp.

 <html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function init() {
            var url = "http://www.yourDomain.com/application.jsp";
            var variables = new air.URLVariables();
            variables.sessionId = new Date().getTime();
            variables.userLabel = "Your Name";

            var request = new air.URLRequest(url);
            request.data = variables;
            air.trace("air.sendToURL: " + request.url + "?" + request.data);
            try {
                air.sendToURL(request);
            }
            catch (e) {
                // handle error here
            }
        }
      </script>
    </head>
    <body onload='init()'>
    </body>
</html>

[an error occurred while processing this directive][an error occurred while processing this directive]

Legal Notices | Online Privacy Policy