flash.net.NetConnection (JavaScript)

	Property	Defined By
		client : Object Indicates the object on which callback methods should be 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] If a successful connection is made, indicates the method that was used to make it: a direct connection, the CONNECT method, or HTTP tunneling.	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
		objectEncoding : uint The object encoding for this NetConnection instance.	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 the server fails.	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
		NetConnection() 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
		call(command:String, responder:Responder, ... arguments):void Invokes 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 bidirectional connection between a Flash Player or AIR an AIR application and a Flash Media Server application.	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
		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

Summary	Defined By
activate	Dispatched when Flash Player or an AIR application gains operating system focus and becomes active.	EventDispatcher
asyncError	Dispatched when an exception is thrown asynchronously — that is, from native asynchronous code.	NetConnection
deactivate	Dispatched when Flash Player or an AIR application loses operating system focus and is becoming inactive.	EventDispatcher
ioError	Dispatched when an input or output error occurs that causes a network operation to fail.	NetConnection
netStatus	Dispatched when a NetConnection object is reporting its status or error condition.	NetConnection
securityError	Dispatched if a call to NetConnection.call() attempts to connect to a server outside the caller's security sandbox.	NetConnection

Property Detail

client

property

client:Object [read-write]

Indicates the object on which callback methods should be 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]

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]

If a successful connection is made, indicates the method that was used to make it: a direct connection, the CONNECT method, or HTTP tunneling. Possible values are "none", "HTTP", "HTTPS", and "CONNECT". This property is valid only when a NetConnection object is connected. This property is used in Flex applications and Flash Media Server applications. This property is applicable only when RTMP, RTMPS, or RTMPT is used. The CONNECT method is applicable only to users who are connected to the network by a proxy server.

You can read this property to determine which method of connection was used. This property returns "none" if a direct connection was made, "HTTP" if HTTP tunneling was used, "HTTPS" if secure HTTPS tunneling was used, and "CONNECT" if the proxy CONNECT method was used.

Throws

ArgumentError — An attempt was made to access this property when the NetConnection instance was not connected.

defaultObjectEncoding

property

defaultObjectEncoding:uint [read-write]

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.

objectEncoding

property

objectEncoding:uint [read-write]

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 should be 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 is ObjectEncoding.AMF3. All NetConnection instances created in this file use AMF3 serialization, so you don't need to set the objectEncoding 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 to ObjectEncoding.AMF0. All NetConnection instances created in this SWF file use AMF0 serialization. You don't need to set the objectEncoding property.
Connecting to multiple servers that use different encoding versions. Instead of using defaultObjectEncoding, set the object encoding on a per-connection basis using the objectEncoding property for each connection. Set it to ObjectEncoding.AMF0 to connect to servers that use AMF0 encoding, such as Flash Media Server 2, and set it to ObjectEncoding.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

defaultObjectEncoding
ObjectEncoding

proxyType

property

proxyType:String [read-write]

Determines which fallback methods are tried if an initial connection attempt to the server fails. You must set the proxyType property before calling the NetConnection.connect() method.

Acceptable values are "none", "HTTP", "CONNECT", and "best".

The default value for this property is "none"; if you do not change this value, the application uses HTTPS tunneling for RTMPS. If the property is set to "best", the client attempts to connect using native SSL. If the connection fails, other connection methods are attempted. 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 will 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.

uri

property

uri:String [read-only]

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]

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.

Constructor Detail

NetConnection

()

Constructor

function NetConnection()

Creates a NetConnection object. Call connect() to make a connection.

If an application needs to communicate with servers released prior to Flash Player 9, you might need to set the NetConnection object's objectEncoding property.

See also

NetConnection.connect()
objectEncoding

Method Detail

addHeader

()

method

function addHeader(operation:String, mustUnderstand:Boolean = false, param:Object = null):void

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

function call(command:String, responder:Responder, ... arguments):void

Invokes 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.

Parameters

	`command:String` — A method specified in the form `[objectPath/]method`. For example, the `someObject/doSomething` command tells the remote server to invoke 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, `command` is the name of a function defined in an application's server-side script. You do not need to use an object path before `command` if the server-side script is placed at the root level of the application directory.

	`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:SecurityErrorEvent — 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.

()

method

function 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.

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() will be 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

NetStream
NetStatusEvent.info

connect

()

method

function connect(command:String, ... arguments):void

Creates a bidirectional connection between an AIR application and a Flash Media Server application. A NetConnection object is like a pipe between the client and the server. Use NetStream objects to send streams through the pipe. For information about codecs and file formats supported by Flash Media Server, see the Flash Media Server documentation.

Without Flash Media Server, call NetConnection.connect() to play video and MP3 files from a local file system or from a web server. For information about supported codecs and file formats, see http://www.adobe.com/go/hardware_scaling_en.

Creates a bidirectional connection between an AIR application and an application server running the Flash Remoting service. 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.

When using this method, consider the following security model:

By default, AIR denies access between sandboxes. A website can enable access to a resource by using a cross-domain policy file.
Your application can deny access to a resource on the server. In a Flash Media Server application, you need to add server-side code to deny access. See the Flash Media Server documentation for details.
You cannot use NetConnection.connect() if the calling file is in the local-with-file-system sandbox.

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, see the following:

The Flash Player 9 Security white paper

Parameters

command:String — Set this parameter to null if you are connecting to a video file on the local computer. If you are connecting to a server, set this parameter to the URI of the application that contains the video file on the server. Use the following syntax (items in brackets are optional):

protocol:[//host][:port]/appname[/instanceName]

To connect to Flash Media Server, use rtmp, rtmpe, rtmps, rtmpt, or rtmpte as the protocol. If the connection is successful, a netStatus event with a code property of NetConnection.Connect.Success is returned. See the NetStatusEvent.info property for a list of all event codes returned in response to calling connect().

If the file is served from the same host where the server is installed, you can omit the host parameter. If you omit the instanceName parameter, AIR connects to the application's default instance.

... arguments — Optional parameters of any type to be 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 might 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.

See also

NetStream
NetStatusEvent.info

Event Detail

asyncError

Event

Event Object Type: flash.events.AsyncErrorEvent
AsyncErrorEvent.type property = flash.events.AsyncErrorEvent.ASYNC_ERROR

Dispatched when an exception is thrown asynchronously — that is, from native asynchronous code.

The AsyncErrorEvent.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`	This property applies to display objects in SWF content, which use the ActionScript 3.0 display architecture.
`error`	The error that triggered the event.

ioError

Event

Event Object Type: flash.events.IOErrorEvent
IOErrorEvent.type property = flash.events.IOErrorEvent.IO_ERROR

Dispatched when an input or output error occurs that causes a network operation to fail.

Defines the value of the type 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.
`target`	The network object experiencing the input/output error.
`text`	Text to be displayed as an error message.

netStatus

Event

Event Object Type: flash.events.NetStatusEvent
NetStatusEvent.type property = flash.events.NetStatusEvent.NET_STATUS

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.

Defines the value of the 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

NetStatusEvent.info

securityError

Event

Event Object Type: flash.events.SecurityErrorEvent
SecurityErrorEvent.type property = flash.events.SecurityErrorEvent.SECURITY_ERROR

Dispatched if a call to NetConnection.call() attempts to connect to a server outside the caller's security sandbox.

The SecurityErrorEvent.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

NetConnection.call()

Current page: http://livedocs.adobe.com/labs/air/1/jslr/flash/net/NetConnection.html

JavaScript Language Reference for Adobe AIR	All Packages \| All Classes \| Language Elements \| Index \| Appendixes \| Conventions \| Frames No Frames
NetConnection	Properties \| Methods \| Events

window.runtime property	window.runtime.flash.net.NetConnection
Inheritance	NetConnection EventDispatcher Object