window.runtime property | window.runtime.flash.net.NetConnection |
Inheritance | NetConnection EventDispatcher Object |
Runtime Versions: | AIR 1.0, |
NetConnection.connect()
to
establish the connection. Use the NetStream class to send streams of media and data over the connection.
For security information about loading content and data into Flash Player and AIR, see the following:
- To load content and data into Flash Player from a web server or from a local location, see Flash Player Developer Center: Security.
- To load content and data into Flash Player and AIR from Flash Media Server, see the Flash Media Server documentation.
- To load content and data into AIR, see the Adobe AIR Developer Center.
See also
Property | Defined By | ||
---|---|---|---|
client : Object
Indicates the object on which callback methods are invoked. | NetConnection | ||
connected : Boolean [read-only]
Indicates whether the application is connected to a server through
a persistent RTMP connection (true) or not (false). | NetConnection | ||
connectedProxyType : String [read-only]
The proxy type used to make a successful connection to Flash Media Server. | NetConnection | ||
constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | ||
defaultObjectEncoding : uint [static]
The default object encoding for NetConnection objects. | NetConnection | ||
farID : String [read-only]
The identifier of the Flash Media Server instance to which this Flash Player or Adobe AIR instance is connected. | NetConnection | ||
farNonce : String [read-only]
A value chosen substantially by Flash Media Server, unique to this connection. | NetConnection | ||
httpIdleTimeout : Number
The time, in milliseconds, to wait for an HTTP response. | NetConnection | ||
maxPeerConnections : uint
The total number of inbound and outbound peer connections that this instance of Flash Player or Adobe AIR allows. | NetConnection | ||
nearID : String [read-only]
The identifier of this Flash Player or Adobe AIR instance for this NetConnection instance. | NetConnection | ||
nearNonce : String [read-only]
A value chosen substantially by this Flash Player or Adobe AIR instance, unique to this connection. | NetConnection | ||
objectEncoding : uint
The object encoding for this NetConnection instance. | NetConnection | ||
protocol : String [read-only]
The protocol used to establish the connection. | NetConnection | ||
prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | ||
proxyType : String
Determines which fallback methods are tried if an
initial connection attempt to Flash Media Server fails. | NetConnection | ||
unconnectedPeerStreams : Array [read-only]
An object that holds all of the peer subscriber NetStream objects that are not associated with publishing NetStream objects. | NetConnection | ||
uri : String [read-only]
The URI passed to the NetConnection.connect() method. | NetConnection | ||
usingTLS : Boolean [read-only]
Indicates whether a secure connection was made using native Transport Layer Security (TLS)
rather than HTTPS. | NetConnection |
Method | Defined By | ||
---|---|---|---|
Creates a NetConnection object. | NetConnection | ||
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener
receives notification of an event. | EventDispatcher | ||
addHeader(operation:String, mustUnderstand:Boolean = false, param:Object = null):void
Adds a context header to the Action Message Format (AMF) packet structure. | NetConnection | ||
Calls a command or method on Flash Media Server or on an application server running Flash Remoting. | NetConnection | ||
close():void
Closes the connection that was opened locally or to the server and dispatches
a netStatus event
with a code property of NetConnection.Connect.Closed. | NetConnection | ||
connect(command:String, ... arguments):void
Creates a two-way connection to an application on Flash Media Server or to Flash Remoting, or creates a two-way network
endpoint for RTMFP peer-to-peer group communication. | NetConnection | ||
dispatchEvent(event:Event):Boolean
Dispatches an event into the event flow. | EventDispatcher | ||
hasEventListener(type:String):Boolean
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | ||
hasOwnProperty(name:String):Boolean
Indicates whether an object has a specified property defined. | Object | ||
isPrototypeOf(theClass:Object):Boolean
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
propertyIsEnumerable(name:String):Boolean
Indicates whether the specified property exists and is enumerable. | Object | ||
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object. | EventDispatcher | ||
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Sets the availability of a dynamic property for loop operations. | Object | ||
toLocaleString():String
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
toString():String
Returns the string representation of the specified object. | Object | ||
valueOf():Object
Returns the primitive value of the specified object. | Object | ||
willTrigger(type:String):Boolean
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher |
Event | Summary | Defined By | ||
---|---|---|---|---|
[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher | |||
Dispatched when an exception is thrown asynchronously — that is, from native asynchronous code. | NetConnection | |||
[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher | |||
Dispatched when an input or output error occurs that causes a network operation to fail. | NetConnection | |||
Dispatched when a NetConnection object is reporting its status or error condition. | NetConnection | |||
Dispatched if a call to NetConnection.call() attempts to connect to a server outside the caller's security sandbox. | NetConnection |
client | property |
client:Object
Runtime Versions: | AIR 1.0, |
Indicates the object on which callback methods are invoked. The default is
this NetConnection instance. If you set the client
property to another object,
callback methods will be invoked on that object.
Throws
TypeError — The client property must be set to a non-null object.
|
connected | property |
connected:Boolean
[read-only] Runtime Versions: | AIR 1.0, |
Indicates whether the application is connected to a server through
a persistent RTMP connection (true
) or not (false
).
When connected through HTTP, this property is false
, except
when connected to Flash Remoting services on an application server,
in which case it is true
.
connectedProxyType | property |
connectedProxyType:String
[read-only] Runtime Versions: | AIR 1.0, |
The proxy type used to make a successful connection to Flash Media Server. Possible values are:
"none"
, "HTTP"
, "HTTPS"
, or "CONNECT"
.
The value is "none"
if the connection is not tunneled or is a native SSL connection.
The value is "HTTP"
if the connection is tunneled over HTTP.
The value is "HTTPS"
if the connection is tunneled over HTTPS,
The value is "CONNECT"
if the connection is tunneled using the CONNECT method through a proxy server.
Throws
ArgumentError — An attempt was made to access this property when the NetConnection instance
was not connected.
|
defaultObjectEncoding | property |
defaultObjectEncoding:uint
Runtime Versions: | AIR 1.0, |
The default object encoding for NetConnection objects.
When an object is written to or read from binary data, the defaultObjectEncoding
property indicates which Action Message Format (AMF) version is used to serialize the data:
the ActionScript 3.0 format (ObjectEncoding.AMF3
)
or the ActionScript 1.0 and ActionScript 2.0 format (ObjectEncoding.AMF0
).
The default value is ObjectEncoding.AMF3
.
Changing NetConnection.defaultObjectEncoding
does not affect existing NetConnection instances; it affects only instances that
are created subsequently.
To set an object's encoding separately (rather than setting object encoding for the entire
application), set the objectEncoding
property of the NetConnection object instead.
For more detailed information, see the description of the objectEncoding
property.
See also
farID | property |
farID:String
[read-only] Runtime Versions: | 1.5 |
The identifier of the Flash Media Server instance to which this Flash Player or Adobe AIR instance is connected. This property is meaningful only for RTMFP connections. The value of this property is available only after an RTMFP connection is established.
See also
farNonce | property |
farNonce:String
[read-only] Runtime Versions: | 1.5 |
A value chosen substantially by Flash Media Server, unique to this connection. This value appears to the server
as its client.nearNonce
value. This value is defined only for RTMFP, RTMPE, and RTMPTE connections.
httpIdleTimeout | property |
httpIdleTimeout:Number
Runtime Versions: | 2.6 |
The time, in milliseconds, to wait for an HTTP response. The default value is zero.
- The
httpIdleTimeout
value is aNumber
. - When using an HTTP connection, a positive value indicates the number of milliseconds an inactive connection should remain open.
- A value of zero indicates that the default networking idle timeout value for the platform should be used.
- A negative value will result in a
RangeError
. - If the
httpIdleTimeout
value is exceeded, anetStatus
event is dispatched. - This property will only affect
NetConnection
objects created with HTTP connections.NetConnection
objects created with RTMP, RTMFP, or other HTTP channels remain unaffected by this property.
//Set the timeout to 5 seconds connection = new NetConnection(); connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler); connection.httpIdleTimeout = 5000;
NetConnection
may take more seconds to timeout than what is specified using the
httpIdleTimeout
value.
maxPeerConnections | property |
maxPeerConnections:uint
Runtime Versions: | 1.5 |
The total number of inbound and outbound peer connections that this instance of Flash Player or Adobe AIR allows. The default value is 8.
This value does not distinguish between publisher and subscriber connections. If this value is reduced while peer connections are present, the new value affects new incoming connections only. Existing connections are not dropped.
nearID | property |
nearID:String
[read-only] Runtime Versions: | 1.5 |
The identifier of this Flash Player or Adobe AIR instance for this NetConnection instance. This property is meaningful only for RTMFP connections.
Every NetConnection instance has a unique nearID
property. No Flash Player or Adobe AIR instance
or NetConnection instance has the same identifier.
Other Flash Player or Adobe AIR instances
use this identifier as the peerID
for new NetStream connections to this client.
Subsequently, this identifier is the farID
in any peer NetStream that connects to this instance.
See also
nearNonce | property |
nearNonce:String
[read-only] Runtime Versions: | 1.5 |
A value chosen substantially by this Flash Player or Adobe AIR instance, unique to this connection. This value appears to the server
as its client.farNonce
value. This value is defined only for RTMFP, RTMPE, and RTMPTE connections.
objectEncoding | property |
objectEncoding:uint
Runtime Versions: | AIR 1.0, |
The object encoding for this NetConnection instance.
When an object is written to or read from binary data, the defaultObjectEncoding
property indicates which Action Message Format (AMF) version is used to serialize the data: the ActionScript 3.0 format (ObjectEncoding.AMF3
)
or the ActionScript 1.0 and ActionScript 2.0 format (ObjectEncoding.AMF0
).
Set the objectEncoding
property to set an AMF version for a NetConnection instance.
It's important to understand this property if your application needs to communicate with servers released prior to Flash Player 9. The following three scenarios are possible:
- Connecting to a server that supports AMF3 (for example, Flex Data Services 2 or Flash Media Server 3).
The default value of
defaultObjectEncoding
isObjectEncoding.AMF3
. All NetConnection instances created in this file use AMF3 serialization, so you don't need to set theobjectEncoding
property. - Connecting to a server that doesn't support AMF3 (for example, Flash Media Server 2).
In this scenario, set the static
NetConnection.defaultObjectEncoding
property toObjectEncoding.AMF0
. All NetConnection instances created in this SWF file use AMF0 serialization. You don't need to set theobjectEncoding
property. - Connecting to multiple servers that use different encoding versions. Instead of
using
defaultObjectEncoding
, set the object encoding on a per-connection basis using theobjectEncoding
property for each connection. Set it toObjectEncoding.AMF0
to connect to servers that use AMF0 encoding, such as Flash Media Server 2, and set it toObjectEncoding.AMF3
to connect to servers that use AMF3 encoding, such as Flex Data Services 2.
Once a NetConnection instance is connected, its objectEncoding
property is read-only.
If you use the wrong encoding to connect to a server, the NetConnection object
dispatches the netStatus
event. The NetStatusEvent.info
property contains an information object with a code
property value of
NetConnection.Connect.Failed
, and a description explaining that the object
encoding is incorrect.
Throws
ReferenceError — An attempt was made to set the value of the objectEncoding
property while the NetConnection instance was connected.
| |
ArgumentError — This property was set to a value other than ObjectEncoding.AMF0
or ObjectEncoding.AMF3 .
|
See also
protocol | property |
protocol:String
[read-only] Runtime Versions: | 1.5 |
The protocol used to establish the connection. This property is relevant when using Flash Media Server. Possible values are as follows:
"rtmp"
: Real-Time Messaging Protocol (RTMP)"rtmpe"
: Encrypted RTMP"rtmpt"
: HTTP tunneling RTMP"rtmpte"
: HTTP tunneling encrypted RTMP"rtmps"
: HTTPS-based RTMP"rtmfp"
: Real-Time Media Flow Protocol (RTMFP)
Throws
ArgumentError — An attempt was made to access this property when the NetConnection instance
was not connected.
|
proxyType | property |
proxyType:String
Runtime Versions: | AIR 1.0, |
Determines which fallback methods are tried if an
initial connection attempt to Flash Media Server fails. Set the proxyType
property before
calling the NetConnection.connect()
method.
Acceptable values are "none"
, "HTTP"
, "CONNECT"
,
and "best"
.The default value is "none"
.
To use native SSL, set the property to "best"
. If the player cannot make a direct connection
to the server (over the default port of 443 or over another port that you specify)
and a proxy server is in place, the player tries to use the CONNECT method. If that attempt fails, the player tunnels over HTTPS.
If the property is set to "HTTP"
and a direct connection fails, HTTP tunneling is used.
If the property is set to "CONNECT"
and a direct connection fails,
the CONNECT
method of tunneling is used. If that fails, the connection does
not fall back to HTTP tunneling.
This property is applicable only when using RTMP, RTMPS, or RTMPT. The CONNECT
method is applicable only to users who are connected to the network by a proxy server.
unconnectedPeerStreams | property |
unconnectedPeerStreams:Array
[read-only] Runtime Versions: | 1.5 |
An object that holds all of the peer subscriber NetStream objects that are not associated with publishing NetStream objects.
Subscriber NetStream objects that are associated with publishing NetStream objects are in the NetStream.peerStreams
array.
uri | property |
uri:String
[read-only] Runtime Versions: | AIR 1.0, |
The URI passed to the NetConnection.connect() method.
If NetConnection.connect()
hasn't been called or if no URI was passed,
this property is undefined
.
usingTLS | property |
usingTLS:Boolean
[read-only] Runtime Versions: | AIR 1.0, |
Indicates whether a secure connection was made using native Transport Layer Security (TLS) rather than HTTPS. This property is valid only when a NetConnection object is connected.
Throws
ArgumentError — An attempt was made to access this property when the NetConnection instance
was not connected.
|
NetConnection | () | Constructor |
public function NetConnection()
Runtime Versions: | AIR 1.0, |
Creates a NetConnection object. Call the connect()
method to make a connection.
If an application needs to communicate with servers released prior
to Flash Player 9, set the NetConnection object's
objectEncoding
property.
The following code creates a NetConnection object:
var nc:NetConnection = new NetConnection();
See also
addHeader | () | method |
public function addHeader(operation:String, mustUnderstand:Boolean = false, param:Object = null):void
Runtime Versions: | AIR 1.0, |
Adds a context header to the Action Message Format (AMF) packet structure. This header is sent with
every future AMF packet. If you call NetConnection.addHeader()
using the same name, the new header replaces the existing header, and the new header
persists for the duration of the NetConnection object. You can remove a header by
calling NetConnection.addHeader()
with the name of the header to remove
an undefined object.
Parameters
operation:String — Identifies the header and the ActionScript object data associated with it.
| |
mustUnderstand:Boolean (default = false ) — A value of true indicates that the server must understand
and process this header before it handles any of the following headers or messages.
| |
param:Object (default = null ) — Any ActionScript object.
|
call | () | method |
public function call(command:String, responder:Responder, ... arguments):void
Runtime Versions: | AIR 1.0, |
Calls a command or method on Flash Media Server or on an application server running Flash Remoting.
Before calling NetConnection.call()
you must call NetConnection.connect()
to connect to the server. You must create a server-side function to pass to this method.
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.
Parameters
command:String — A method specified in the form [objectPath/]method . For example,
the someObject/doSomething command tells the remote server
to call the clientObject.someObject.doSomething() method, with all the optional
... arguments parameters. If the object path is missing,
clientObject.doSomething() is invoked on the remote server.
With Flash Media Server, | |
responder:Responder — An optional object that is used to handle return values from the server.
The Responder object can have two defined methods to handle the returned result:
result and status . If an error is returned as the result,
status is invoked; otherwise, result is invoked. The Responder object
can process errors related to specific operations, while the NetConnection object responds to
errors related to the connection status.
| |
... arguments — Optional arguments that can be of any ActionScript type,
including a reference to another ActionScript object. These arguments are passed
to the method specified in the command parameter when the method is executed on the
remote application server.
|
Events
securityError: — A call attempted
to communicate with a server outside the caller's security sandbox.
You can avoid this problem by using a policy file on the server. |
See also
close | () | method |
public function close():void
Runtime Versions: | AIR 1.0, |
Closes the connection that was opened locally or to the server and dispatches
a netStatus
event
with a code
property of NetConnection.Connect.Closed
.
This method disconnects all NetStream objects running over the connection.
Any queued data that has not been sent is discarded. (To terminate
local or server streams without closing the connection, use NetStream.close()
.)
If you close the connection and then want to create a new one,
you must create a new NetConnection object and call the connect()
method again.
The close()
method also disconnects all remote shared objects running
over this connection.
However, you don't need to recreate the shared object to reconnect. Instead, you can just
call SharedObject.connect()
to reestablish the connection to the shared object.
Also, any data in the shared object that was queued when you issued
NetConnection.close()
is sent after you reestablish a connection
to the shared object.
With Flash Media Server, the best development practice is to call close()
when the client no longer needs the connection to the server. Calling close()
is the fastest way to clean up unused connections. You can configure the server to close idle connections
automatically as a back-up measure. For more information, see
the Flash Media Server Configuration and Administration Guide.
See also
connect | () | method |
public function connect(command:String, ... arguments):void
Runtime Versions: | AIR 1.0, |
Creates a two-way connection to an application on Flash Media Server or to Flash Remoting, or creates a two-way network
endpoint for RTMFP peer-to-peer group communication. To report its status or an error condition, a
call to NetConnection.connect()
dispatches a netStatus
event.
Call NetConnection.connect()
to do the following:
- Pass "null" to play video and mp3 files from a local file system or from a web server.
- Pass an "http" URL to connect to an application server running Flash Remoting. Use the NetServices class to call functions on and return results from application servers over a NetConnection object. For more information, see the Flash Remoting documentation.
- Pass an "rtmp/e/s" URL to connect to a Flash Media Server application.
- Pass an "rtmfp" URL to create a two-way network endpoint for RTMFP client-server, peer-to-peer, and IP multicast communication.
- Pass the string "rtmfp:" to create a serverless two-way network endpoint for RTMFP IP multicast communication.
Consider the following security model:
- By default, AIR denies access between sandboxes. A website can enable access to a resource by using a URL policy file.
- Your application can deny access to a resource on the server. In a Flash Media Server application, use Server-Side ActionScript code to deny access. See the Flash Media Server documentation.
- You cannot call
NetConnection.connect()
if the calling file is in the local-with-file-system 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.
- To prevent a SWF file from calling this method, set the
allowNetworking
parameter of the theobject
andembed
tags in the HTML page that contains the SWF content.
However, in Adobe AIR, content in the application
security sandbox (content
installed with the AIR application) are not restricted by these security limitations.
For more information about security, see the Adobe Flash Player Developer Center: Security.
Parameters
command:String — Use one of the following values for the command parameter:
This connection type has the following limitations: Only peers on the same LAN can discover each other. Using IP multicast, Flash Player can receive streams, it cannot send them. Flash Player and AIR can send and receive streams in a peer-to-peer group, but the peers must be discovered on the same LAN using IP multicast. This technique cannot be used for one-to-one communication. | |
... arguments — Optional parameters of any type passed to the application
specified in command .
With Flash Media Server, the additional arguments are passed to the
application.onConnect() event handler in the application's server-side
code. You must define and handle the arguments in onConnect() .
|
Throws
ArgumentError — The URI passed to the command parameter is
improperly formatted.
| |
IOError — The connection failed. This can happen if you call connect()
from within a netStatus event handler, which is not allowed.
| |
SecurityError — Local-with-filesystem SWF files cannot communicate with the Internet.
You can avoid this problem by reclassifying the 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.
|
See also
asyncError | Event |
flash.events.AsyncErrorEvent
property AsyncErrorEvent.type =
flash.events.AsyncErrorEvent.ASYNC_ERROR
Runtime Versions: | AIR 1.0, |
Dispatched when an exception is thrown asynchronously — that is, from native asynchronous code.
TheAsyncErrorEvent.ASYNC_ERROR
constant defines the value of the
type
property of an asyncError
event object.
This event has the following properties:
Property | Value |
---|---|
bubbles | false
This property applies to ActionScript 3.0 display objects (in SWF files). |
cancelable | false ; there is no default
behavior to cancel. This property applies to display objects
in SWF content, which use the ActionScript 3.0 display architecture. |
currentTarget | The object that is actively processing the Event object with an event listener. This property applies to display objects in SWF content, which use the ActionScript 3.0 display architecture. |
target | The object dispatching the event. |
error | The error that triggered the event. |
ioError | Event |
flash.events.IOErrorEvent
property IOErrorEvent.type =
flash.events.IOErrorEvent.IO_ERROR
Runtime Versions: | AIR 1.0, |
Dispatched when an input or output error occurs that causes a network operation to fail.
Defines the value of thetype
property of an ioError
event object.
This event has the following properties:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
currentTarget | The object that is actively processing the Event object with an event listener. |
errorID | A reference number associated with the specific error (AIR only). |
target | The network object experiencing the input/output error. |
text | Text to be displayed as an error message. |
netStatus | Event |
flash.events.NetStatusEvent
property NetStatusEvent.type =
flash.events.NetStatusEvent.NET_STATUS
Runtime Versions: | AIR 1.0, |
Dispatched when a NetConnection object is reporting its status or error condition.
The netStatus
event contains an info
property,
which is an information object that contains specific information about the event,
such as whether a connection attempt succeeded or failed.
type
property of a netStatus
event object.
This event has the following properties:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
currentTarget | The object that is actively processing the Event object with an event listener. |
info | An object with properties that describe the object's status or error condition. |
target | The NetConnection or NetStream object reporting its status. |
See also
securityError | Event |
flash.events.SecurityErrorEvent
property SecurityErrorEvent.type =
flash.events.SecurityErrorEvent.SECURITY_ERROR
Runtime Versions: | AIR 1.0, |
Dispatched if a call to NetConnection.call() attempts to connect to a server outside the caller's security sandbox.
TheSecurityErrorEvent.SECURITY_ERROR
constant defines the value of the type
property of a securityError
event object.
This event has the following properties:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
currentTarget | The object that is actively processing the Event object with an event listener. |
target | The network object reporting the security error. |
text | Text to be displayed as an error message. |
See also
Thu Sep 29 2011, 02:34 AM -07:00