LocalConnection  - AS3

表示对其调用回调方法的对象。默认对象为 this，将创建本地连接。您可以将设置 client 属性设置为另一个对象，并对此对象调用回调方法。

一个字符串，它表示当前 文件所在位置的域。

在运行于 Adobe AIR 的 application 安全沙箱的内容（使用 AIR 应用程序安装的内容）中，运行时将使用字符串 app# 后跟 AIR 应用程序的应用程序 ID（在应用程序描述符文件中定义）来代替该超级域。例如，应用程序 ID 为 com.example.air.MyApp connectionName 的应用程序的 connectionName 将解析为 "app#com.example.air.MyApp:connectionName"。

在为 Flash Player 9 或更高版本发布的 SWF 文件中，返回的字符串就是文件所在的域并包括子域。例如，如果 文件位于 www.adobe.com，则此命令将返回 "www.adobe.com"。

如果当前文件是在 Flash Player 中运行并驻留在客户端计算机上的本地文件，则此命令将返回“localhost”。

此属性最常见的用法是，将发送方 LocalConnection 对象的域名作为要在接收方 LocalConnection 对象中调用的方法的参数包括在内，或者与 LocalConnection.allowDomain() 一起使用以接受来自指定域的命令。如果仅启用位于同一个域的 LocalConnection 对象之间的通信，则可能不需要使用此属性。

相关 API 元素

指示 LocalConnection 对象是仅限当前用户访问 (true) 还是计算机上的所有用户全都可以访问它 (false)。此属性只影响在 Mac OS X 中运行的内容；其它平台忽略此参数。Windows 和 Linux 操作系统上的连接授权始终是每用户授权。

在 Flash Player 10.0.22 和 AIR 1.5.1 以及它们的早期版本中，Mac OS X 上的所有 LocalConnection 对象都具有全局作用域。始终将此属性设置为 true，除非您需要保留与早期版本的兼容性。在将来发布的版本中，此属性的默认值可能更改为 true。

默认值为 false。

如果当前平台支持 LocalConnection 类，则 isSupported 属性设置为 true，否则，设置为 false。

创建 LocalConnection 对象。可以使用 LocalConnection 对象启用在同一客户端计算机上运行的不同文件之间的通信。

相关 API 元素

指定一个或多个可以将 LocalConnection 调用发送到此 LocalConnection 实例的域。

您无法使用此方法允许使用安全协议 (HTTPS) 承载的文件由使用非安全协议承载的文件进行访问；必须改用 allowInsecureDomain() 方法。

您可能想要使用此方法，以便在不知道来自于不同域的子级文件究竟来自哪个最终域的情况下，使该子级文件能够对父级文件进行 LocalConnection 调用。例如，当您使用负载平衡重定向或第三方服务器时就可能发生这种情况。在这种情况下，您可以使用用于加载的 LoaderInfo 对象的 url 属性，以获取要与 allowDomain() 方法配合使用的域。例如，如果使用 Loader 对象加载子级文件，则您可以在文件加载后检查 Loader 对象的 contentLoaderInfo.url 属性，并从完整的 URL 字符串中解析出域。如果您这样做的话，请务必等待文件加载完毕，因为只有在该文件完全加载后，contentLoaderInfo.url 属性才会具有其最终的正确值。

也可能出现相反的情况：您可能创建了一个子级文件，用以接受来自父级的 LocalConnection 调用，但却不知道其父级的域。在这种情况下，可以通过检查域参数是否与已加载的 文件中 loaderInfo.url 属性的域相匹配来实现此方法。同样，您必须从 loaderInfo.url 的完整 URL 中解析出该域。在这种情况下，您不必等待父级 文件加载；加载子级时，父级已经加载完毕。

使用此方法时，请考虑 Flash Player 安全模型。默认情况下，LocalConnection 对象与创建它的 文件的沙箱相关联，并且不允许对 LocalConnection 对象进行跨域调用，除非在接收方 文件中调用 LocalConnection.allowDomain() 方法。但在 Adobe AIR 中，application 安全沙箱中的内容（使用 AIR 应用程序安装的内容）不受这些安全限制的约束。

有关安全性的详细信息，请参阅 Flash Player 开发人员中心主题：安全性。

注意：allowDomain() 方法的格式已更改，与其在 ActionScript 1.0 和 2.0 中的格式不同。在这两个早期版本中，allowDomain 是可以实现的回调方法。在 ActionScript 3.0 中，allowDomain() 是调用的 LocalConnection 的内置方法。由于这种更改，allowDomain() 的用法与 flash.system.Security.allowDomain() 基本相同。

参数

相关 API 元素

指定一个或多个可以将 LocalConnection 调用发送到此 LocalConnection 对象的域。

allowInsecureDomain() 方法的用法与 allowDomain() 方法相似，不同之处是 allowInsecureDomain() 方法允许非 HTTPS 来源的文件将 LocalConnection 调用发送至 HTTPS 来源的 SWF 文件。仅当您在使用 HTTPS 加载的文件中调用 allowInsecureDomain() 方法时，才能体现这种不同。即使在同一个域中跨越非 HTTPS/HTTPS 边界，也必须调用 allowInsecureDomain() 方法；默认情况下，即使在同一个域中，也不允许从非 HTTPS 文件到 HTTPS 文件进行 LocalConnection 调用。

不建议调用 allowInsecureDomain()，因为这可能会削弱 HTTPS 提供的安全性。通过 HTTPS 加载文件时，您可以确信在通过网络传输文件时，文件不会被篡改。如果随后允许非 HTTPS 文件对 HTTPS 文件进行 LocalConnection 调用，则要接受来自可能在传输过程中已被篡改的 文件的调用。这通常需要格外小心，因为您无法确保到达 HTTPS 文件的 LocalConnection 调用的真实性。

默认情况下，使用 HTTPS 协议承载的文件只能被其他使用 HTTPS 协议承载的文件访问。这种实现保持了 HTTPS 协议所提供的完整性。

不建议使用此方法覆盖默认行为，因为这样做会削弱 HTTPS 安全性。但在某些情况下您可能需要这样做；例如，需要允许从为 Flash Player 6 或更早版本发布的 HTTP SWF 文件访问为 Flash Player 9 或更高版本发布的 HTTPS SWF 文件。

有关安全性的详细信息，请参阅 Flash Player 开发人员中心主题：安全性。

参数

相关 API 元素

关闭（断开连接）LocalConnection 对象。在您不再需要该对象来接受命令时（例如，当您要在另一个 SWF 文件中使用相同的 connectionName 参数发出 connect() 命令时）发出此命令。

相关 API 元素

准备 LocalConnection 对象以接收从 send() 命令（从发送方 LocalConnection 对象）发送的命令。同 connect() 方法一起使用的对象被称为接收方 LocalConnection 对象。接收方和发送方对象必须运行于同一台客户端计算机上。

要避免出现竞争状况，请在调用附加到接收方 LocalConnection 对象的方法之前先定义这些方法，如 LocalConnection 类示例所示。

默认情况下，connectionName 将解析为值“superdomain:connectionName”，其中 superdomain 是包含 connect() 命令的文件的超级域。例如，如果包含接收方 LocalConnection 对象的 文件位于 www.someDomain.com，则 connectionName 解析为 "someDomain.com:connectionName"。（如果 Flash Player 中运行的文件位于客户端计算机上，则分配给 superdomain 的值为“localhost”。）

在运行于 Adobe AIR 的 application 安全沙箱的内容（使用 AIR 应用程序安装的内容）中，运行时将使用字符串 app# 后跟 AIR 应用程序的应用程序 ID（在应用程序描述符文件中定义）来代替该超级域。例如，应用程序 ID 为 com.example.air.MyApp connectionName 的应用程序的 connectionName 将解析为 "app#com.example.air.MyApp:connectionName"。

此外，在默认情况下，Flash Player 只允许接收方 LocalConnection 对象从连接名称也解析为值 "superdomain:connectionName" 的发送方 LocalConnection 对象接受命令。这样，Flash Player 就使得位于同一个域中的文件可以很容易地相互通信。

如果您仅在同一个域中的 文件之间实现通讯，请为 connectionName 指定一个不以下划线 (_) 开头且不指定域名的字符串（例如 "myDomain:connectionName"）。在 connect(connectionName) 方法中使用同一个字符串。

如果要使位于不同域中的 文件之间实现通信，则为 connectionName 指定一个以下划线 (_) 开头的字符串，这样就会使具有接收方 LocalConnection 对象的 文件在域之间具有更好的可移植性。下面是两种可能的情形：

• 如果 connectionName 字符串不以下划线 (_) 开头，则会添加一个超级域前缀和一个冒号（例如“myDomain:connectionName”）。虽然这可以确保您的连接不会与其他域中具有同一名称的连接相互冲突，但任何发送方 LocalConnection 对象都必须指定此超级域（例如 "myDomain:connectionName"）。如果具有接收方 LocalConnection 对象的 文件被移动到另一个域中，则播放器会更改该前缀，以反映新的超级域（例如 "anotherDomain:connectionName"）。所有发送方 LocalConnection 对象必须进行手动编辑，以指向这个新超级域。
• 如果 connectionName 字符串以下划线开头（例如“_connectionName”），则不会向该字符串添加前缀。这意味着接收方和发送方 LocalConnection 对象都将使用相同的 connectionName 字符串。如果接收方对象使用 allowDomain() 来指定可以接受来自任何域的连接，则具有接收方 LocalConnection 对象的 文件可以移动到另一个域，而无需更改任何发送方 LocalConnection 对象。

有关详细信息，请参阅类概述中的讨论和 send() 中对 connectionName 的讨论以及 allowDomain() 和 domain 条目。

注意：冒号用作一种特殊字符，以分隔 connectionName 超级域和字符串。包含冒号的 connectionName 字符串无效。

使用此方法时，请考虑 Flash Player 安全模型。默认情况下，LocalConnection 对象与创建它的 文件的沙箱相关联，并且不允许对 LocalConnection 对象进行跨域调用，除非在接收方 文件中调用 LocalConnection.allowDomain() 方法。可以在包含 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，防止 SWF 文件使用此方法。但在 Adobe AIR 中，application 安全沙箱中的内容（使用 AIR 应用程序安装的内容）不受这些安全限制的约束。

有关安全性的详细信息，请参阅 Flash Player 开发人员中心主题：安全性。

参数

相关 API 元素

在使用 connect(connectionName) 方法打开的连接（位于接收方 LocalConnection 对象 中）上调用 methodName 方法。同 send() 方法一起使用的对象被称为发送方 LocalConnection 对象。包含发送方对象的 SWF 文件和包含接收方对象的 SWF 文件必须在同一台客户端计算机上运行。

您能够以参数形式传递给此命令的数据量限制为 40 千字节。如果 send() 引发 ArgumentError，但是您的语法是正确的，请尝试将 send() 请求分为多个命令，每个命令的数据量不超过 40K。

如 connect() 条目中所述，默认情况下，会将当前超级域添加到 connectionName。如果您要在不同的域之间实现通讯，则在发送方和接收方 LocalConnection 对象中都需要定义 connectionName，这样当前超级域就不会添加到 connectionName。您可以使用以下两种方法中的一种实现这一目的：

• 在发送方 LocalConnection 对象和接收方 LocalConnection 对象中 connectionName 的开头使用下划线 (_)。在包含接收方对象的 文件中，使用 LocalConnection.allowDomain() 指定将接受来自任何域的连接。这一实现使您可以在任何域中存储发送方 文件和接收方 SWF 文件。
• 在发送方 LocalConnection 对象中包含 connectionName 中的超级域，例如 myDomain.com:myConnectionName。在接收方对象中，使用 LocalConnection.allowDomain() 指定将接受来自指定超级域的连接（本例中为 myDomain.com），或者接受来自任何域的连接。

注意：不能在接收方 LocalConnection 对象的 connectionName 中指定超级域，只能在发送方 LocalConnection 对象中指定。

使用此方法时，请考虑 Flash Player 安全模型。默认情况下，LocalConnection 对象与创建它的 文件的沙箱相关联，并且不允许对 LocalConnection 对象进行跨域调用，除非在接收方 文件中调用 LocalConnection.allowDomain() 方法。对于在浏览器中运行的 SWF 内容，通过在包含 SWF 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，可以防止文件使用此方法。但在 Adobe AIR 中，application 安全沙箱中的内容（使用 AIR 应用程序安装的内容）不受这些安全限制的约束。

有关安全性的详细信息，请参阅 Flash Player 开发人员中心主题：安全性。

参数

相关 API 元素

在异步引发异常（即来自本机异步代码）时调度。

此事件具有以下属性：

若对 LocalConnection.send() 的调用尝试向另一个安全沙箱发送数据，则进行调度。

此事件具有以下属性：

相关 API 元素

在 LocalConnection 对象报告其状态时调度。如果 LocalConnection.send() 成功，则 status 事件对象的 level 属性的值为 "status"；如果调用失败，则 level 属性为 "error"。如果接收方 文件拒绝连接，则调用失败，并且不会通知发送方 文件。

此事件具有以下属性：

相关 API 元素

在 LocalConnectionSenderExample SWF 文件中，将创建 LocalConnection 实例，并且当按下按钮时使用 call() 方法通过名为“myConnection”的连接调用 SWF 文件中名为 lcHandler 的方法，调用时将 TextField 的内容作为参数传递。

在 LocalConnectionReceiverExample SWF 文件中，将创建 LocalConnection 实例并调用 connect() 方法，将此 SWF 文件指定为发送到名为“myConnection”的连接的消息的接收方。此外，此类还包括一个名为 lcHandler() 的公共方法，此方法就是 LocalConnectionSenderExample SWF 文件调用的方法。调用时，作为参数传入的文本将被追加到舞台的 TextField 中。

注意：为了测试此示例，必须将两个 SWF 文件同时加载到同一台计算机上。

// Code in LocalConnectionSenderExample.as
package {
    import flash.display.Sprite;
    import flash.events.MouseEvent;
    import flash.net.LocalConnection;
    import flash.text.TextField;
    import flash.text.TextFieldType;
    import flash.events.StatusEvent;
    import flash.text.TextFieldAutoSize;

    public class LocalConnectionSenderExample extends Sprite {
        private var conn:LocalConnection;
        
        // UI elements
        private var messageLabel:TextField;
        private var message:TextField;
        private var sendBtn:Sprite;
        
        public function LocalConnectionSenderExample() {
            buildUI();
            sendBtn.addEventListener(MouseEvent.CLICK, sendMessage);
            conn = new LocalConnection();
            conn.addEventListener(StatusEvent.STATUS, onStatus);
        }
        
        private function sendMessage(event:MouseEvent):void {
            conn.send("myConnection", "lcHandler", message.text);
        }
        
        private function onStatus(event:StatusEvent):void {
            switch (event.level) {
                case "status":
                    trace("LocalConnection.send() succeeded");
                    break;
                case "error":
                    trace("LocalConnection.send() failed");
                    break;
            }
        }
        
        private function buildUI():void {
            const hPadding:uint = 5;
            // messageLabel
            messageLabel = new TextField();
            messageLabel.x = 10;
            messageLabel.y = 10;
            messageLabel.text = "Text to send:";
            messageLabel.autoSize = TextFieldAutoSize.LEFT;
            addChild(messageLabel);
            
            // message
            message = new TextField();
            message.x = messageLabel.x + messageLabel.width + hPadding;
            message.y = 10;
            message.width = 120;
            message.height = 20;
            message.background = true;
            message.border = true;
            message.type = TextFieldType.INPUT;
            addChild(message);
            
            // sendBtn
            sendBtn = new Sprite();
            sendBtn.x = message.x + message.width + hPadding;
            sendBtn.y = 10;
            var sendLbl:TextField = new TextField();
            sendLbl.x = 1 + hPadding;
            sendLbl.y = 1;
            sendLbl.selectable = false;
            sendLbl.autoSize = TextFieldAutoSize.LEFT;
            sendLbl.text = "Send";
            sendBtn.addChild(sendLbl);
            sendBtn.graphics.lineStyle(1);
            sendBtn.graphics.beginFill(0xcccccc);
            sendBtn.graphics.drawRoundRect(0, 0, (sendLbl.width + 2 + hPadding + hPadding), (sendLbl.height + 2), 5, 5);
            sendBtn.graphics.endFill();
            addChild(sendBtn);
        }
    }
}