Package | flash.net |
Class | public final class URLRequest |
Inheritance | URLRequest Object |
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
load()
methods of the Loader, URLStream,
and URLLoader classes, and to other loading operations, to initiate URL downloads.
They are also passed to the upload()
and download()
methods
of the FileReference class.
A SWF file in the local-with-filesystem sandbox may not load data from, or provide data to, a resource that is in the network sandbox.
By default, the calling SWF file and the URL you load must be in the same domain. For example, a SWF file at www.adobe.com can load data only from sources that are also at www.adobe.com. To load data from a different domain, place a URL policy file on the server hosting the data.
However, in Adobe AIR, content in the application security sandbox (content installed with the AIR application) is not restricted by these security limitations. For content running in Adobe AIR, files in the application security sandbox can access URLs using any of the following URL schemes:
-
http
andhttps
-
file
-
app-storage
-
app
Content running in Adobe AIR that is not in the application security sandbox observes the same restrictions as content running in the browser (in Flash Player), and loading is governed by the content's domain and any permissions granted in URL policy files.
For more information related to security, see the following:
- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The "Understanding AIR Security" section of the "Getting started with Adobe AIR" chapter in the Developing AIR Applications book.
- The Flash Player Developer Center Topic: Security
See also
Property | Defined By | ||
---|---|---|---|
authenticate : Boolean
Specifies whether authentication requests should be handled (true
or not (false) for this request. | URLRequest | ||
cacheResponse : Boolean
Specifies whether successful response data should be cached for this request. | URLRequest | ||
constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | ||
contentType : String
The MIME content type of the content in the the data property. | URLRequest | ||
data : Object
An object containing data to be transmitted with the URL request. | URLRequest | ||
digest : String
A string that uniquely identifies the signed Adobe platform component to be stored
to (or retrieved from) the Flash Player cache. | URLRequest | ||
followRedirects : Boolean
Specifies whether redirects are to be followed (true)
or not (false). | URLRequest | ||
manageCookies : Boolean
Specifies whether the HTTP protocol stack should manage cookies for this
request. | URLRequest | ||
method : String
Controls the HTTP form submission method. | URLRequest | ||
prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | ||
requestHeaders : Array
The array of HTTP request headers to be appended to the
HTTP request. | URLRequest | ||
url : String
The URL to be requested. | URLRequest | ||
useCache : Boolean
Specifies whether the local cache should be consulted before this URLRequest
fetches data. | URLRequest | ||
userAgent : String
Specifies the user-agent string to be used in the HTTP request. | URLRequest |
Method | Defined By | ||
---|---|---|---|
URLRequest(url:String = null)
Creates a URLRequest object. | URLRequest | ||
Indicates whether an object has a specified property defined. | Object | ||
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
Sets the availability of a dynamic property for loop operations. | Object | ||
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
Returns the string representation of the specified object. | Object | ||
Returns the primitive value of the specified object. | Object |
authenticate | property |
authenticate:Boolean
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Specifies whether authentication requests should be handled (true
or not (false
) for this request. If false
, authentication
challenges return an HTTP error.
The supported authentication methods are:
- Windows—HTTP Basic/Digest, Windows Integrated Authentication (including NTLM and Kerberos), SSL Certificate Authentication.
- Mac—HTTP Basic/Digest, NTLM, SSL Certificate Authentication.
Note:The FileReference.upload()
,
FileReference.download()
, and HTMLLoader.load()
methods do not support the URLRequest.authenticate
property.
The default value is true.
Implementation
public function get authenticate():Boolean
public function set authenticate(value:Boolean):void
Throws
SecurityError — The caller is not in the AIR application security sandbox.
|
See also
cacheResponse | property |
cacheResponse:Boolean
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Specifies whether successful response data should be cached for this request.
When set to true
, the AIR application uses the operating system's
HTTP cache.
Note:The HTMLLoader.load()
method
does not support the URLRequest.cacheResponse
property.
The default value is true.
Implementation
public function get cacheResponse():Boolean
public function set cacheResponse(value:Boolean):void
Throws
SecurityError — The caller is not in the AIR application security sandbox.
|
See also
contentType | property |
contentType:String
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
The MIME content type of the content in the the data
property.
The default value is application/x-www-form-urlencoded
.
Note:The FileReference.upload()
,
FileReference.download()
, and HTMLLoader.load()
methods do not
support the URLRequest.contentType
property.
When sending a POST request, the values of the contentType
and data
properties must correspond properly. The value of the contentType
property instructs servers on how to interpret the value of the data
property.
- If the value of the
data
property is a URLVariables object, the value ofcontentType
must beapplication/x-www-form-urlencoded
. - If the value of the
data
property is any other type, the value ofcontentType
should indicate the type of the POST data that will be sent (which is the binary or string data contained in the value of thedata
property). - For
FileReference.upload()
, the Content-Type of the request is set automatically tomultipart/form-data
, and the value of thecontentType
property is ignored.
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.
Implementation
public function get contentType():String
public function set contentType(value:String):void
See also
data | property |
data:Object
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
An object containing data to be transmitted with the URL request.
This property is used in conjunction with the method
property.
When the value of method
is GET
,
the value of data
is appended to the value of URLRequest.url
,
using HTTP query-string syntax. When the method
value is POST
(or any value other than GET
), the value
of data
is transmitted in the body of the HTTP request.
The URLRequest API offers binary POST
support and support for URL-encoded variables,
as well as support for strings. The data object can be a ByteArray, URLVariables,
or String object.
The way in which the data is used depends on the type of object used:
- If the object is a ByteArray object, the binary
data of the ByteArray object is used as
POST
data. ForGET
, data of ByteArray type is not supported. Also, data of ByteArray type is not supported forFileReference.upload()
andFileReference.download()
. - If the object is a URLVariables object and the method is
POST
, the variables are encoded using x-www-form-urlencoded format and the resulting string is used asPOST
data. An exception is a call toFileReference.upload()
, in which the variables are sent as separate fields in amultipart/form-data
post. - If the object is a URLVariables object and the method is
GET
, the URLVariables object defines variables to be sent with the URLRequest object. - Otherwise, the object is converted to a string, and the string
is used as the
POST
orGET
data.
This data is not sent until a method, such as navigateToURL()
or FileReference.upload()
, uses the URLRequest object.
Note: The value of contentType
must correspond to the type of data
in the data
property. See the note in the description of the
contentType
property.
Implementation
public function get data():Object
public function set data(value:Object):void
See also
Example ( How to use this example )
Highlights of the example follow:
- The constructor function creates a URLRequest
instance named
request
, taking the URL of the remote application as a parameter. - A URLVariables object is created and two of its properties are assigned values.
- The URLVariables object is assigned to the
data
property of the URLRequest object. - The example calls
navigateToURL
, which opens a new browser window to the remote application's URL.
Note: To run the example, the remote application URL in the example must be replaced with a working URL. Additionally, you would need server code to process the information captured by Flash Player in the URLVariables object.
package { import flash.display.Sprite; import flash.net.navigateToURL; import flash.net.URLRequest; import flash.net.URLVariables; public class URLVariablesExample extends Sprite { public function URLVariablesExample() { var url:String = "http://www.[yourDomain].com/application.jsp"; var request:URLRequest = new URLRequest(url); var variables:URLVariables = new URLVariables(); variables.exampleSessionId = new Date().getTime(); variables.exampleUserLabel = "guest"; request.data = variables; navigateToURL(request); } } }
digest | property |
digest:String
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9.0.115.0 |
A string that uniquely identifies the signed Adobe platform component to be stored to (or retrieved from) the Flash Player cache. An Adobe platform component is a signed file (a SWZ file) that contains SWF content that is cached persistently on a user's machine. All SWZ files are signed by Adobe. A digest corresponds to a single cached file; if you change the file in any way, its digest will change in an unpredictable way. By using a digest, you can verify the cached file across multiple domains. Two files with the same digest are the same file, and two files with different digests are not the same file. A file cannot (practically) be created to "spoof" a digest and pretend to be another digest.
The digest is based on an SHA-256 message digest algorithm (64 characters long in hexadecimal format).
For example, the Flex SDK includes a SWZ for the Flex framework (and it
provides the digest string for that SWZ file). You can post this SWZ on your web server and load it
in your SWF file (using the load()
method of a URLLoader object). If the end user's
machine already has the matching SWZ file cached, the application uses the cached SWZ file.
(A SWZ file matches if its digest
matches the one you provide.) Otherwise, the
application downloads the SWZ file from the URL you specify.
Only set the digest
parameter in a URLRequest object
used in a call to the URLLoader.load()
method to load a SWZ file. If the digest
property of a a URLRequest object is set when it is used in other methods, the application throws an
IOError exception.
Implementation
public function get digest():String
public function set digest(value:String):void
Throws
ArgumentError — The digest provided does not match the digest of the file that is
extracted from the downloaded signed file or the signed file loaded out of the cache. The
application also throws this error if the provided digest is the wrong length or contains invalid
(nonhexadecimal) characters.
|
Example ( How to use this example )
loadBytes()
:
var myURLReq:URLRequest = new URLRequest(); myURLReq.url = "http://yourdomain/users/jdoe/test01/_rsc/Automated/AssetCaching_rsc/test01/rsl.swz"; myURLReq.digest = "3B0AA28C7A990385E044D80F5637FB036317BB41E044D80F5637FB036317BB41"; var myURLLoader:URLLoader = new URLLoader(); myURLLoader.dataFormat = URLLoaderDataFormat.BINARY; myURLLoader.addEventListener("complete", onC); myURLLoad.load(myURLReq); function onC(e) { var someLoader:Loader = new Loader(); addChild(someLoader); someLoader.loadBytes((ByteArray)(myURLLoad.data)); }
followRedirects | property |
followRedirects:Boolean
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Specifies whether redirects are to be followed (true
)
or not (false
).
Note:The FileReference.upload()
,
FileReference.download()
, and HTMLLoader.load()
methods do not
support the URLRequest.followRedirects
property.
The default value is true.
Implementation
public function get followRedirects():Boolean
public function set followRedirects(value:Boolean):void
Throws
SecurityError — The caller is not in the AIR application security sandbox.
|
See also
manageCookies | property |
manageCookies:Boolean
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Specifies whether the HTTP protocol stack should manage cookies for this
request. When true
, cookies are added to the request
and response cookies are remembered. If false
, cookies are
not added to the request and response cookies are not
remembered, but users can manage cookies themselves by direct header
manipulation.
On Mac OS, cookies are shared with Safari. To clear cookies on Mac OS:
- Open Safari.
- Select Safari > Preferences, and click the Security panel.
- Click the Show Cookies button.
- Click the Reomove All button.
To clear cookies on Windows:
- Open the Internet Properties control panel, and click the General tab.
- Click the Delete Cookies button.
The default value is true.
Implementation
public function get manageCookies():Boolean
public function set manageCookies(value:Boolean):void
Throws
SecurityError — The caller is not in the AIR application security sandbox.
|
See also
method | property |
method:String
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
Controls the HTTP form submission method.
For SWF content running in Flash Player
(in the browser), this property is limited to GET or
POST operations, and valid values are URLRequestMethod.GET
or URLRequestMethod.POST
.
For content running in Adobe AIR, you can use any string value if the content is in the application security sandbox. Otherwise, as with content running in Flash Player, you are restricted to using GET or POST operations.
For content running in Adobe AIR, 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.
Note:
If running in Flash Player and the referenced form has no body,
Flash Player automatically uses a GET operation, even if the method is set to
URLRequestMethod.POST
. For this reason, it is recommended to always include
a "dummy" body to ensure that the correct method is used.
The default value is URLRequestMethod.GET.
Implementation
public function get method():String
public function set method(value:String):void
Throws
ArgumentError — If the value parameter is not
URLRequestMethod.GET or URLRequestMethod.POST .
|
See also
Example ( How to use this example )
URLRequest.method
property to
URLRequestMethod.POST
.
Highlights of the example follow:
- The constructor function creates a URLRequest
instance named
request
, taking the URL of the remote application as a parameter. - A URLVariables object is created and two of its properties are assigned values.
- The URLVariables object is assigned to the
data
property of the URLRequest object. - The value of the
URLRequest.method
property is set toURLRequestMethod.POST
. - The example calls
navigateToURL
, which opens a new browser window to the remote application's URL.
Note: To run the example, the remote application URL in the example must be replaced with a working URL. Additionally, you would need server code to process the information captured by Flash Player in the URLVariables object.
package { import flash.display.Sprite; import flash.net.navigateToURL; import flash.net.URLRequest; import flash.net.URLRequestMethod; import flash.net.URLVariables; public class URLRequest_method extends Sprite { public function URLRequest_method() { var url:String = "http://www.[yourDomain].com/application.jsp"; var request:URLRequest = new URLRequest(url); var variables:URLVariables = new URLVariables(); variables.exampleSessionId = new Date().getTime(); variables.exampleUserLabel = "guest"; request.data = variables; request.method = URLRequestMethod.POST; navigateToURL(request); } } }
requestHeaders | property |
requestHeaders:Array
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
The array of HTTP request headers to be appended to the HTTP request. The array is composed of URLRequestHeader objects. Each object in the array must be a URLRequestHeader object that contains a name string and a value string, as follows:
var rhArray:Array = new Array(new URLRequestHeader("Content-Type", "text/html"));
Flash Player and the AIR runtime impose certain restrictions on request headers; for more information, see the URLRequestHeader class description.
Not all methods that accept URLRequest parameters support the requestHeaders
property,
consult the documentation for the method you are calling. For example, the FileReference.upload()
and FileReference.download()
methods do not
support the URLRequest.requestHeaders
property.
Due to browser limitations, custom HTTP request headers are only supported for POST
requests,
not for GET
requests.
Implementation
public function get requestHeaders():Array
public function set requestHeaders(value:Array):void
See also
url | property |
url:String
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
The URL to be requested.
Be sure to encode any characters that are either described as unsafe in the Uniform Resource Locator
specification (see http://www.faqs.org/rfcs/rfc1738.html) or that are reserved in the
URL scheme of the URLRequest object (when not used for their reserved purpose). For example,
use "%25"
for the percent (%) symbol and "%23"
for the number sign (#), as in
"http://www.example.com/orderForm.cfm?item=%23B-3&discount=50%25"
.
By default, the URL must be in the same domain as the calling file, unless the content is running in the Adobe AIR application security sandbox. If you need to load data from a different domain, put a URL policy file on the server that is hosting the data. For more information, see the description of the URLRequest class.
For content running in Adobe AIR, files in the application security sandobx — files installed with the AIR application — can access URLs using any of the following URL schemes:
http
andhttps
file
app-storage
app
Note: IPv6 (Internet Protocol version 6) is supported in AIR and in Flash Player 9.0.115.0 and later. IPv6 is a version of Internet Protocol that supports 128-bit addresses (an improvement on the earlier IPv4 protocol that supports 32-bit addresses). You might need to activate IPv6 on your networking interfaces. For more information, see the Help for the operating system hosting the data. If IPv6 is supported on the hosting system, you can specify numeric IPv6 literal addresses in URLs enclosed in brackets ([]), as in the following.
rtmp://[2001:db8:ccc3:ffff:0:444d:555e:666f]:1935/test
Implementation
public function get url():String
public function set url(value:String):void
useCache | property |
useCache:Boolean
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Specifies whether the local cache should be consulted before this URLRequest fetches data.
Note:The HTMLLoader.load()
method
does not support the URLRequest.useCache
property.
The default value is true.
Implementation
public function get useCache():Boolean
public function set useCache(value:Boolean):void
Throws
SecurityError — The caller is not in the AIR application security sandbox.
|
See also
userAgent | property |
userAgent:String
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Specifies the user-agent string to be used in the HTTP request.
The default value is the same user agent string that is used by Flash Player, which is different on Mac, Linux, and Windows.
Note: This property does not affect the user agent string when
the URLRequest object is used with the load()
method of an
HTMLLoader object. To set the user agent string for an HTMLLoader object,
set the userAgent
property of the HTMLLoader object or set
the static URLRequestDefaults.userAgent
property.
Implementation
public function get userAgent():String
public function set userAgent(value:String):void
Throws
SecurityError — The caller is not in the AIR application security sandbox.
|
See also
URLRequest | () | Constructor |
public function URLRequest(url:String = null)
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
Creates a URLRequest object.
If System.useCodePage
is true
, the request is encoded using the
system code page, rather than Unicode.
If System.useCodePage
is false
, the request is encoded using Unicode, rather than the
system code page.
url:String (default = null ) — The URL to be requested. You can set the URL later by using the url property.
|
See also
complete
event is dispatched and the data in the XML
file traces to the output. Additional event handlers capture other events, including error
events.
To run this example, place a file named XMLFile.xml in the same directory as your SWF file.
package { import flash.display.Sprite; import flash.events.*; import flash.net.*; public class URLRequestExample extends Sprite { public function URLRequestExample() { var loader:URLLoader = new URLLoader(); configureListeners(loader); var request:URLRequest = new URLRequest("XMLFile.xml"); try { loader.load(request); } catch (error:Error) { trace("Unable to load requested document."); } } private function configureListeners(dispatcher:IEventDispatcher):void { dispatcher.addEventListener(Event.COMPLETE, completeHandler); dispatcher.addEventListener(Event.OPEN, openHandler); dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler); dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler); dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler); dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler); } private function completeHandler(event:Event):void { var loader:URLLoader = URLLoader(event.target); trace("completeHandler: " + loader.data); } private function openHandler(event:Event):void { trace("openHandler: " + event); } private function progressHandler(event:ProgressEvent):void { trace("progressHandler loaded:" + event.bytesLoaded + " total: " + event.bytesTotal); } private function securityErrorHandler(event:SecurityErrorEvent):void { trace("securityErrorHandler: " + event); } private function httpStatusHandler(event:HTTPStatusEvent):void { trace("httpStatusHandler: " + event); } private function ioErrorHandler(event:IOErrorEvent):void { trace("ioErrorHandler: " + event); } } }
Fri Mar 19 2010, 02:45 AM -07:00