LocalConnection  - AS3

コールバックメソッドが呼び出されるオブジェクトを示します。デフォルトのオブジェクトは、作成されるローカル接続 this です。client プロパティを別のオブジェクトに設定すると、その別のオブジェクトでコールバックメソッドを呼び出すことができます。

現在のファイルが存在するドメインを表すストリングです。

Adobe AIR のアプリケーションセキュリティサンドボックスで実行されているコンテンツ（AIR アプリケーションと共にインストールされたコンテンツ）では、スーパードメインの代わりに、app# + AIR アプリケーションのアプリケーション ID（アプリケーション記述ファイルで定義）が使用されます。 例えば、アプリケーション ID が com.example.air.MyApp のアプリケーションでは、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 呼び出しを送信できる 1 つ以上のドメインを指定します。

このメソッドを使用して、セキュアでないプロトコルでホストされているファイルから、セキュアなプロトコル（HTTPS）を使用してホストされているファイルへのアクセスを許可することはできません。この場合は、allowInsecureDomain() メソッドを使用してくだい。

場合によっては、このメソッドを使用して、ドメインの異なる子ファイルから親ファイルへの LocalConnection 呼び出しを、子ファイルの最終的なドメインが不明な状態でも実行できるようにしたいことがあります。 例えば、ロードバランシングリダイレクトやサードパーティー製サーバーを使用する場合などです。このような場合、ロードに使用される LoaderInfo オブジェクトの url プロパティを使用すれば、allowDomain() メソッドで使用するドメインを取得できます。例えば、Loader オブジェクトを使用して子ファイルをロードする場合は、ファイルがロードされた後、Loader オブジェクトの contentLoaderInfo.url プロパティをチェックすることにより、完全な URL ストリングから子 SWF ファイルのドメインを解析できます。この場合、ファイルがロードされるまで待つようにしてください。ファイルが完全にロードされるまで、contentLoaderInfo.url プロパティが最終的な正しい値に設定されないためです。

また、これとは反対に、ドメインの不明な親からの LocalConnection 呼び出しを子ファイルに受け入れさせたい場合もあります。この場合は、ドメインパラメーターが、ロードされたファイルの loaderInfo.url プロパティのドメインに一致するかどうかをチェックすることにより、このメソッドを実装できます。この場合も、loaderInfo.url に含まれている完全な URL からドメインを解析する必要があります。この状況では、親ファイルがロードされるまで待つ必要はありません。親 SWF ファイルは子 SWF ファイルがロードされた時点で既にロードされているからです。

このメソッドを使用するときは、Flash Player セキュリティモデルを考慮してください。デフォルトでは、LocalConnection オブジェクトはそれを作成したファイルのサンドボックスに関連付けられ、LocalConnection オブジェクトのクロスドメイン呼び出しは、受信側ファイルで LocalConnection.allowDomain() メソッドが呼び出されていない限り許可されません。ただし、Adobe AIR では、アプリケーションセキュリティサンドボックス内のコンテンツ（AIR アプリケーションと共にインストールされたコンテンツ）は、これらのセキュリティ制限による制限を受けません。

セキュリティについて詳しくは、Flash Player デベロッパーセンターのトピック：セキュリティを参照してください。

注意：allowDomain() メソッドは、ActionScript 1.0 および 2.0 での形式から変更されています。これらの以前のバージョンでは、allowDomain は実装するコールバックメソッドでした。ActionScript 3.0 では、allowDomain() は LocalConnection のビルトインメソッドとして呼び出されます。変更された allowDomain() は flash.system.Security.allowDomain() とほぼ同じように作用します。

パラメーター

関連する API エレメント

この LocalConnection オブジェクトに LocalConnection 呼び出しを送信できる 1 つ以上のドメインを指定します。

allowInsecureDomain() メソッドは allowDomain() メソッドと同じように作用しますが、allowInsecureDomain() メソッドは、HTTPS 以外でロードされたファイルが HTTPS でロードされた SWF ファイルに LocalConnection 呼び出しを送信することも許可する点が異なります。この違いは、HTTPS を使用してロードされたファイルから allowInsecureDomain() メソッドを呼び出す場合にのみ意味があります。同じドメイン内の非 HTTPS と HTTPS の境界を越える場合でも、allowInsecureDomain() メソッドを呼び出す必要があります。デフォルトでは、同じドメイン内でも 非 HTTPS ファイルから HTTPS ファイルへの LocalConnection 呼び出しは許可されません。

allowInsecureDomain() を呼び出すことは、HTTPS によるセキュリティが損なわれる恐れがあるので、お勧めできません。HTTPS によってファイルをロードする場合は、ほぼ確実に、ファイルがネットワークでの配信中に不正操作を受けることはありません。 非 HTTPS ファイルから HTTPS ファイルへの LocalConnection 呼び出しを許可した場合、配信中に不正操作された可能性のあるファイルからの呼び出しを受け入れることになります。この場合は、HTTPS ファイルに送られてきた LocalConnection 呼び出しの正当性を信頼できないので、一般に特別な警戒を必要とします。

デフォルトでは、HTTPS プロトコルを使用してホストされたファイルは、HTTPS プロトコルを使用してホストされた他のファイルにのみアクセスできます。 この実装方法により、HTTPS プロトコルが提供する整合性が保たれます。

このメソッドでデフォルトの動作を変更することはお勧めできません。デフォルトの動作を変更すると、HTTPS のセキュリティが損なわれます。ただし、デフォルトの動作を変更せざるをえない場合もあります。例えば、Flash Player 9 以降用にパブリッシュされた HTTPS SWF ファイルに対して、Flash Player 6 以前のバージョン用にパブリッシュされた HTTP SWF ファイルからのアクセスを許可しなければならない場合などです。

セキュリティについて詳しくは、Flash Player デベロッパーセンターのトピック：セキュリティを参照してください。

パラメーター

関連する API エレメント

LocalConnection オブジェクトを閉じます（切断します）。このコマンドは、LocalConnection オブジェクトがもうコマンドを受け入れないようにする場合に実行します。例えば、connect() コマンドを、別の SWF ファイルで同じ connectionName パラメーターを使用して実行する場合などです。

関連する API エレメント

send() コマンド（送信側 LocalConnection オブジェクト）から送信されたコマンドを受け入れるように LocalConnection オブジェクトを準備します。 connect() メソッドで使用されるオブジェクトは、受信側 LocalConnection オブジェクトと呼ばれます。受信側と送信側のオブジェクトは、同じクライアントコンピューター上で実行されている必要があります。

競合状況を避けるため、このメソッドを呼び出す前に、受信側の LocalConnection オブジェクトに関連付けられるメソッドを定義します（LocalConnection クラスの例を参照）。

デフォルトでは、connectionName 引数は "superdomain:connectionName" の値に解決されます。ここで superdomain は、connect() コマンドを含むファイルのスーパードメインを表します。 例えば、受信側 LocalConnection オブジェクトを含むファイルが www.someDomain.com に配置されている場合、connectionName は "someDomain.com:connectionName" に解決されます。（Flash Player で実行されているファイルがクライアントコンピューターに配置されている場合、superdomain には "localhost" が割り当てられます。）

Adobe AIR のアプリケーションセキュリティサンドボックスで実行されているコンテンツ（AIR アプリケーションと共にインストールされたコンテンツ）では、スーパードメインの代わりに、app# + AIR アプリケーションのアプリケーション ID（アプリケーション記述ファイルで定義）が使用されます。 例えば、アプリケーション ID が com.example.air.MyApp のアプリケーションでは、connectionName は "app#com.example.air.MyApp:connectionName" に解決されます。

またデフォルトでは、受信側 LocalConnection オブジェクトは、接続名が "superdomain:connectionName" の値に解決される送信側 LocalConnection オブジェクトからのコマンドだけを受け入れます。このため、同じドメインに置かれているファイル間の通信は簡単です。

同じドメインのファイル間のみの通信を実装する場合は、先頭がアンダースコア（_）でなくドメイン名を含まないストリングを connectionName に指定します（"myDomain:connectionName" など）。connect(connectionName) メソッドと同じストリングを使用してください。

異なるドメイン内のファイル間の通信を実装する場合は、アンダースコア（_）で始まるストリングを connectionName に指定すると、受信側 LocalConnection オブジェクトを含むファイルをドメイン間で移植しやすくなります。考えられる 2 つの状況を次に示します。

• connectionName のストリングがアンダースコア（_）で始まっていない場合は、"myDomain:connectionName" のように、スーパードメインとコロンが前に追加されます。 これにより、他のドメインの同じ名前を持つ接続との競合は回避できますが、送信側 LocalConnection オブジェクトでも必ずこのスーパードメインを指定する必要があります（"myDomain:connectionName" など）。受信側 LocalConnection オブジェクトを含むファイルが別のドメインに移動された場合は、"anotherDomain:connectionName" のように、新しいスーパードメインに応じて接頭辞が変更されます。すべての送信側 LocalConnection オブジェクトは、新しいスーパードメインを参照するように手動で編集する必要があります。
• connectionName のストリングがアンダースコア（_）で始まっている場合（"_connectionName" など）は、ストリングに接頭辞は追加されません。 つまり、受信側と送信側の LocalConnection オブジェクトは、connectionName にまったく同じストリングを使用します。受信側オブジェクトが allowDomain() を使用し、すべてのドメインからの通信を受け入れるように指定した場合は、送信側 LocalConnection オブジェクトを変更せずに、受信側 LocalConnection オブジェクトを含むファイルを別のドメインに移動させることができます。

詳細については、クラスの概要の説明、connectionName（send()）の説明、および allowDomain() エントリと domain エントリを参照してください。

注意：コロンは、connectionName のストリングとスーパードメインを区切る特殊文字として使用されます。connectionName にコロンを含むストリングを指定するのは無効です。

このメソッドを使用するときは、Flash Player セキュリティモデルを考慮してください。 デフォルトでは、LocalConnection オブジェクトはそれを作成したファイルのサンドボックスに関連付けられ、LocalConnection オブジェクトのクロスドメイン呼び出しは、受信側ファイルで LocalConnection.allowDomain() メソッドが呼び出されていない限り許可されません。ファイルがこのメソッドを使用しないようにするには、SWF コンテンツを含む HTML ページに allowNetworking パラメーター（object タグおよび embed タグ）を設定します。ただし、Adobe AIR では、application セキュリティサンドボックス内のコンテンツ（AIR アプリケーションと共にインストールされたコンテンツ）は、これらのセキュリティ制限による制限を受けません。

セキュリティについて詳しくは、Flash Player デベロッパーセンターのトピック：セキュリティを参照してください。

パラメーター

関連する API エレメント

connect(connectionName) メソッド（受信側 LocalConnection オブジェクト）で確立した接続を使用して、methodName で指定されたメソッドを呼び出します。send() メソッドで使用されるオブジェクトは、送信側 LocalConnection オブジェクトと呼ばれます。送信側オブジェクトと受信側オブジェクトを含む SWF ファイルは、同じクライアントコンピューター上で実行されている必要があります。

このコマンドにパラメーターとして渡すことができるデータの量は 40 KB に制限されます。シンタックスが正しいにもかかわらず、send() が ArgumentError をスローする場合は、send() 要求を複数のコマンドに分割してそれぞれのデータを 40 KB より小さくしてみてください。

connect() の項目で説明したように、connectionName にはデフォルトで現在のスーパードメインが追加されます。 異なるドメイン間の通信を実装する場合は、送信側と受信側の両方の LocalConnection オブジェクトの connectionName を、現在のスーパードメインが connectionName に追加されないように定義する必要があります。 これには、次の 2 つの方法があります。

• 送信側と受信側の両方の LocalConnection オブジェクトで、connectionName の先頭にアンダースコア（_）を使用します。受信側オブジェクトを含むファイルでは、LocalConnection.allowDomain() を使用して、どのドメインからの接続も受け入れるように指定します。この方法では、送信側と受信側のファイルを任意のドメインに配置できます。
• 送信側 LocalConnection オブジェクトの connectionName にスーパードメインを含めます。例えば、myDomain.com:myConnectionName と指定します。受信側オブジェクトでは、LocalConnection.allowDomain() を使用して、指定したスーパードメイン（この例では myDomain.com）からの接続を受け入れるか、またはすべてのドメインからの接続を受け入れるように指定します。

注意：受信側 LocalConnection オブジェクトの connectionName ではスーパードメインを指定できません。スーパードメインを指定できるのは送信側 LocalConnection オブジェクトだけです。

このメソッドを使用するときは、Flash Player セキュリティモデルを考慮してください。 デフォルトでは、LocalConnection オブジェクトはそれを作成したファイルのサンドボックスに関連付けられ、LocalConnection オブジェクトのクロスドメイン呼び出しは、受信側ファイルで LocalConnection.allowDomain() メソッドが呼び出されていない限り許可されません。ブラウザーで実行されている SWF コンテンツで、ファイルがこのメソッドを使用しないようにするには、SWF コンテンツを含む HTML ページに allowNetworking パラメーター（object タグおよび embed タグ）を設定します。 ただし、Adobe AIR では、アプリケーションセキュリティサンドボックス内のコンテンツ（AIR アプリケーションと共にインストールされたコンテンツ）は、これらのセキュリティ制限による制限を受けません。

セキュリティについて詳しくは、Flash Player デベロッパーセンターのトピック：セキュリティを参照してください。

パラメーター

関連する API エレメント

非同期形式で、つまりネイティブ非同期コードから例外がスローされると送出されます。

このイベントには、次のプロパティがあります。

LocalConnection.send() の呼び出しで、異なるセキュリティサンドボックスにデータを送信しようとすると送出されます。

このイベントには、次のプロパティがあります。

関連する API エレメント

LocalConnection オブジェクトがステータスを報告するときに送出されます。LocalConnection.send() が正常に実行された場合、status イベントオブジェクトの level プロパティの値は "status" になります。また、呼び出しに失敗した場合、level プロパティの値は "error" になります。受信側ファイルで接続が拒否されると、送信側ファイルへの通知なしで呼び出しが失敗する可能性があります。

このイベントには、次のプロパティがあります。

関連する API エレメント

LocalConnectionSenderExample SWF ファイルでは LocalConnection インスタンスが作成され、ボタンが押されると call() メソッドを使用して SWF ファイル内の lcHandler というメソッドが呼び出されます。このとき接続名 "myConnection" が使用され、パラメーターとして 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);
        }
    }
}