LocalConnection  - AS3

Wskazuje obiekt, w ramach którego są uaktywniane metody wywołań zwrotnych. Domyślnym obiektem jest to (this) tworzone połączenie lokalne. Właściwość client można ustawić na inny obiekt i metody wywołania zwrotnego będą wywoływane na rzecz tego innego obiektu.

Ciąg reprezentujący domenę bieżącego pliku.

Jeśli treść działająca w obszarze izolowanym zabezpieczeń application środowiska Adobe AIR (treść instalowana z aplikacją AIR), środowisko wykonawcze zamiast naddomeny wpisuje ciąg znaków app#, po którym następuje identyfikator aplikacji AIR (zdefiniowany w pliku deskryptora aplikacji). Na przykład wartość connectionName dla aplikacji o identyfikatorze com.example.air.MyApp connectionName jest tłumaczona na"app#com.example.air.MyApp:connectionName".

W plikach SWF opublikowanych dla programu Flash Player 9 lub późniejszych wersji zwrócony ciąg znaków jest dokładną domeną pliku, włącznie z poddomenami. Na przykład, jeśli plik jest umieszczony na stronie www.adobe.com, to polecenie zwróci "www.adobe.com".

Jeśli bieżący plik jest plikiem lokalnym znajdującym się na komputerze klienckim i działającym w programie Flash Player, to polecenie zwraca "localhost".

Najpowszechniejszymi sposobami na korzystanie z tej właściwości są dołączenie nazwy domeny wysyłającego obiektu LocalConnection jako parametru dla metody, która zostanie wywołana w odbierającym obiekcie LocalConnection object lub użycie jej w metodzie LocalConnection.allowDomain() w celu zaakceptowania poleceń z określonej domeny. Jeśli umożliwi się komunikację jedynie pomiędzy obiektami LocalConnection znajdującymi się w tej samej domenie, prawdopodobnie nie będzie potrzeby korzystania z tej właściwości.

Powiązane elementy interfejsu API

Określa, czy zasięg obiektu LocalConnection jest ograniczony do bieżącego użytkownika (true), czy też obiekt ten jest globalnie dostępny dla wszystkich użytkowników komputera (false). Ta właściwość ma wpływ wyłącznie na treść działającą w systemie Mac OS X; pozostałe platformy ignorują ten parametr. Połączenia w systemach operacyjnych Windows i Linux są zawsze przypisane do konkretnego użytkownika.

W programie Flash Player 10.0.22 i wcześniejszych wersjach oraz w środowisku AIR 1.5.1 i wcześniejszych wersjach wszystkie obiekty LocalConnection w systemie Mac OS X mają zasięg globalny. Tę właściwość należy zawsze ustawiać na true, chyba że konieczne jest zachowanie zgodności z wcześniejszymi wersjami. W przyszłych wersjach domyślna wartość tej właściwości może zostać zmieniona na true.

Wartością domyślną jest false.

Właściwość isSupported ma wartość true, jeśli na bieżącej platformie jest obsługiwana klasa LocalConnection; w przeciwnym razie ma wartość false.

Tworzy nowy obiekt LocalConnection. Obiekty LocalConnection umożliwiają komunikację pomiędzy dwoma plikami, które są uruchomione na tym samym komputerze klienckim.

Powiązane elementy interfejsu API

Pozwala określić domenę lub domeny z możliwością wysyłania wywołań LocalConnection do tego wystąpienia klasy LocalConnection.

Nie można skorzystać z tej metody, aby zezwolić plikom, udostępnianym za pomocą bezpiecznego protokołu (HTTPS), na dostęp z plików udostępnianych przez protokoły bez zabezpieczeń; zamiast tego należy skorzystać z metody allowInsecureDomain().

Tej metody można użyć, aby podrzędny plik z innej domeny mógł dokonywać wywołań LocalConnection do nadrzędnego pliku, nie znając ostatecznej domeny, z której pochodzi plik podrzędny Taka sytuacja ma miejsce np. w momencie korzystania z przekierowań równoważących obciążenie lub serwerów innych firm. W tej sytuacji można skorzystać z właściwości url obiektu LoaderInfo, użytej podczas ładowania, aby otrzymać domenę dla metody allowDomain(). Na przykład, jeśli obiekt Loader zostanie użyty w celu załadowania podrzędnego pliku, po jego załadowaniu można zweryfikować właściwość contentLoaderInfo.url obiektu Loader i wydzielić domenę z pełnego ciągu znaków adresu URL. Po wykonaniu tych czynności należy zaczekać, aż plik zostanie załadowany, ponieważ właściwość contentLoaderInfo.url nie posiada ostatecznej, prawidłowej wartości do czasu całkowitego załadowania.

Może się zdarzyć także sytuacja odwrotna: tworzenie podrzędnego pliku, który będzie akceptował wywołania LocalConnection z jego pliku nadrzędnego, ale nie będzie miał wiedzy na temat domeny własnego pliku nadrzędnego. W tej sytuacji należy zaimplementować tę metodę sprawdzając, czy argument domeny jest zgodny z domeną właściwości loaderInfo.url w załadowanym pliku Ponownie należy wydzielić domenę z pełnego adresu URL z właściwości loaderInfo.url. W tej sytuacji nie ma konieczności czekania na załadowanie nadrzędnego pliku; nadrzędny plik zostanie załadowany zanim załadowany zostanie plik podrzędny.

Korzystając z tej metody, należy wziąć pod uwagę model zabezpieczeń programu Flash Player. Domyślnie obiekt LocalConnection jest skojarzony z obszarem izolowanym pliku, który go utworzył i międzydomenowe wywołania obiektów LocalConnection są niedozwolone, do momentu wywołania w pliku odbierającym metody LocalConnection.allowDomain(). Jednak w aplikacji Adobe AIR zawartość obszaru izolowanego application (zawartość instalowana razem z aplikacją AIR) nie jest ograniczana przez te reguły zabezpieczeń.

Więcej informacji na temat zabezpieczeń zawiera odpowiedni temat w Centrum programistów programu Flash Player w kategorii Bezpieczeństwo.

Uwaga: Postać metody allowDomain() uległa zmianie w porównaniu z tą, jaką miała w ActionScript 1.0 i 2.0. W tych wcześniejszych wersjach metoda allowDomain była metodą wywołania zwrotnego implementowaną przez użytkownika. W ActionScript 3.0 metoda allowDomain() jest metodą wbudowaną LocalConnection, kóry jest wywoływany. Z tą zmianą metoda allowDomain() działa w sposób zbliżony do metody flash.system.Security.allowDomain().

Parametry

Powiązane elementy interfejsu API

Pozwala określić domenę lub domeny, które mogą wysyłać wywołania typu LocalConnection do tego obiektu LocalConnection.

Metoda allowInsecureDomain() działa podobnie jak metoda allowDomain(), za wyjątkiem tego, że metoda allowInsecureDomain() dodatkowo zezwala plikom, które nie są udostępniane za pomocą HTTPS, aby wywołania LocalConnection były wysyłane do plików SWF, które są udostępniane za pomocą HTTPS. Ta różnica jest znacząca jedynie wtedy, gdy metoda allowInsecureDomain() wywoływana jest z pliku, który został załadowany za pomocą HTTPS. Metodę allowInsecureDomain() należy wywołać nawet wtedy, gdy napotkana obwiednia jest inna niż HTTPS/HTTPS w tej samej domenie; domyślnie na wywołania LocalConnection z plików nieudostępnianych za pomocą HTTPS do plików udostępnianych za pomocą HTTPS nigdy nie ma zezwolenia, nawet wewnątrz tej samej domeny.

Wywoływanie metody allowInsecureDomain() nie jest zalecane, ponieważ może to narażać bezpieczeństwo oferowane przez protokół HTTPS. Podczas ładowania pliku za pomocą HTTPS można być pewnym, że plik nie zostanie naruszony w czasie dostarczania przez sieć. Jeśli plikom nieudostępnianym za pomocą HTTPS zezwoli się na wywołania LocalConnection do plików udostępnianych za pomocą HTTPS, zaakceptowane zostaną wywołania z pliku, które mogły w rzeczywistości zostać naruszone podczas dostarczania. Wymaga to zazwyczaj dodatkowej czujności, ponieważ nie można ufać autentyczności wywołań LocalConnection, które dostarczane są do pliku udostępnianego za pomocą HTTPS.

Domyślnie do plików udostępnianych za pomocą protokołu HTTPS dostęp mogą uzyskać jedynie inne pliki udostępniane za pomocą protokołu HTTPS. Ta implementacja zachowuje integralność zapewnianą przez protokół HTTPS.

Korzystanie z tej metody w celu nadpisania domyślnego zachowania nie jest zalecane, ponieważ naraża to zabezpieczenia HTTPS. Jednak może zaistnieć potrzeba jej użycia, na przykład, jeśli potrzebne jest zezwolenie na dostęp do plików SWF HTTPS opublikowanych dla programu Flash Player 9 lub późniejszych wersji z plików SWF HTTP opublikowanych dla programu Flash Player 6 lub wcześniejszych wersji.

Więcej informacji na temat zabezpieczeń zawiera odpowiedni temat w Centrum programistów programu Flash Player w kategorii Bezpieczeństwo.

Parametry

Powiązane elementy interfejsu API

Zamyka obiekt LocalConnection (co skutkuje rozłączeniem). To polecenie należy wydać, jeśli nie ma już dłużej potrzeby, aby obiekt przyjmował polecenia — na przykład, jeśli wydawane jest polecenie connect() z użyciem takiego samego parametru connectionName w innym pliku SWF.

Powiązane elementy interfejsu API

Przygotowuje obiekt LocalConnection do odbierania poleceń wysyłanych za pośrednictwem polecenia send() (z wysyłającego obiektu LocalConnection). Obiekt używany w metodzie connect() nazywany jest odbierającym obiektem LocalConnection. Obiekty wysyłający i odbierający muszą być uruchomione na tym samym komputerze klienckim.

Aby uniknąć sytuacji wyścigu, należy zdefiniować metody dołączane do odbierającego obiektu LocalConnection przed wywołaniem tej metody tak, jak pokazano w przykładzie klasy LocalConnection.

Domyślnie argument connectionName jest tłumaczony na wartość " superdomain :connectionName" , gdzie superdomain jest naddomeną pliku zawierającego polecenie connect(). Na przykład, jeśli plik zawierający obiekt LocalConnection jest umieszczony w www.someDomain.com, parametr connectionName dzieli się na "someDomain.com:connectionName". (Jeśli plik jest umieszczony na komputerze klienckim, wartością właściwości superdomain jest "localhost").

Jeśli treść działająca w obszarze izolowanym zabezpieczeń application środowiska Adobe AIR (treść instalowana z aplikacją AIR), środowisko wykonawcze zamiast naddomeny wpisuje ciąg znaków app#, po którym następuje identyfikator aplikacji AIR (zdefiniowany w pliku deskryptora aplikacji). Na przykład wartość connectionName dla aplikacji o identyfikatorze com.example.air.MyApp connectionName jest tłumaczona na"app#com.example.air.MyApp:connectionName".

Domyślnie program Flash Player zezwala również obiektowi odbierającemu LocalConnection na przyjmowanie poleceń tylko od obiektu LocalConnection, którego nazwa połączenia również daje się podzielić na wartości "naddomena:nazwaPołączenia". W ten sposób program Flash Player ułatwia plikom umieszczonym w tej samej domenie komunikowanie się między sobą.

Implementując komunikację pomiędzy plikami z tej samej domeny, należy określić ciąg znaków dla parametru connectionName, który nie rozpoczyna się znakiem podkreślenia (_) i nie precyzuje nazwy domeny (np. "myDomain:connectionName"). Użyj tej samego ciągu znaków w metodzie connect(connectionName).

Implementując komunikację pomiędzy plikami z różnych domen, należy określić ciąg znaków dla parametru connectionName, który rozpoczyna się znakiem podkreślenia (_) czyniąc tym samym plik z obiektem odbierającym LocalConnection bardziej przenośnym pomiędzy domenami. Istnieją dwa możliwe przypadki:

• Jeśli ciąg znaków dla parametru connectionName nie zawiera znaku podkreślenia (_), dodawany jest przedrostek w postaci naddomeny i dwukropka (np. "myDomain:connectionName"). Chociaż ta metoda zapewnia, że połączenie użytkownika nie wejdzie w konflikt z połączeniami o tej samej nazwie z pozostałych domen, dla obiektów wysyłających LocalConnection należy określić tę samą naddomenę (np. "mojaDomena:nazwaPołączenia"). Jeśli plik z odbierającym obiektem LocalConnection zostanie przeniesiony do innej domeny, odtwarzacz zmieni prefiks tak, aby odzwierciedlał nową naddomenę (np. "anotherDomain:connectionName"). Wszystkie wysyłające obiekty LocalConnection należy edytować ręcznie tak, aby wskazywały na nową naddomenę.
• Jeśli ciąg znaków connectionName rozpoczyna się od znaku podkreślenia (na przykład "_connectionName"), a przedrostek nie jest dodawany do ciągu znaków. Oznacz to, że wysyłające i odbierające obiekty LocalConnection korzystają z takich samych ciągów znaków dla parametru connectionName. Jeśli obiekt odbierający korzysta z metody allowDomain() w celu wyszczególnienia, że połączenia ze wszystkich domen będą akceptowane, plik z obiektem odbierającym LocalConnection może zostać przeniesiony do innej domeny bez zmieniania jakiegokolwiek obiektu wysyłającego LocalConnection.

Aby uzyskać więcej informacji, zobacz omówienie w opisie klasy oraz omówienie parametru connectionName w metodzie send(), a także wpisy dotyczące metody allowDomain() i domain.

Uwaga: Dwukropki są używane jako znaki specjalne w celu rozdzielenia naddomeny od ciągu znaków parametru connectionName. Ciąg znaków parametru connectionName, który zawiera znak dwukropka jest nieprawidłowy.

Korzystając z tej metody, należy wziąć pod uwagę następujący model zabezpieczeń programu Flash Player. Domyślnie obiekt LocalConnection jest skojarzony z obszarem izolowanym pliku, który go utworzył, i międzydomenowe wywołania obiektów LocalConnection są niedozwolone, do momentu wywołania w pliku odbierającym metody LocalConnection.allowDomain(). Istnieje możliwość zablokowania pliku przed korzystaniem z tej metody, ustawiając parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej treść SWF. Jednak w aplikacji Adobe AIR zawartość obszaru izolowanego application (zawartość instalowana razem z aplikacją AIR) nie jest ograniczana przez te reguły zabezpieczeń.

Więcej informacji na temat zabezpieczeń zawiera odpowiedni temat w Centrum programistów programu Flash Player w kategorii Bezpieczeństwo.

Parametry

Powiązane elementy interfejsu API

Wywołuje metodę o nazwie methodName w połączeniu otwartym za pomocą metody connect(connectionName) (w odbierającym obiekcie LocalConnection). Obiekt używany w metodzie send() nazywany jest wysyłającym obiektem LocalConnection. Pliki SWF, które zawierająobiekty wysyłające i odbierające muszą być uruchomione na tym samym komputerze klienckim.

Istnieje ograniczenie do 40 kilobajtów dla danych przekazywanych jako parametr do tej metody. Jeśli metoda send() zgłasza błąd ArgumentError mimo, że składnia jest poprawna, należy spróbować rozdzielić żądania send() na wiele poleceń, z których każde obsłuży mniej niż 40 KB danych.

Tak jak wspomniano w omówieniu metody connect(), domyślnie do nazwy connectionName dodawana jest bieżąca naddomena. Implementując komunikację pomiędzy różnymi domenami, należy zdefiniować parametr connectionName w obu, wysyłających i odbierających, obiektach LocalConnection w taki sposób, by bieżąca naddomena nie była dodawana do parametru connectionName. Można tego dokonać w jeden z następujących sposobów:

• Użyj znaku podkreślenia (_) na początku parametru connectionName w obu obiektach LocalConnection — wysyłającym i odbierającym. W pliku zawierającym obiekt odbierający, użyj metody LocalConnection.allowDomain() w celu wyszczególnienia, że połączenia ze wszystkich domen będą akceptowane. Ta implementacja pozwala na przechowywanie wysyłających i odbierających plików w każdej domenie.
• Dołącz naddomenę w parametrze connectionName w obiekcie wysyłającym LocalConnection — na przykład myDomain.com:myConnectionName. W obiekcie odbierającym skorzystaj z metody LocalConnection.allowDomain() w celu wyszczególnienia, że akceptowane będą połączenia z określonej naddomeny (w tym przypadku, myDomain.com) lub akceptowane będą połączenia ze wszystkich domen.

Uwaga: Nie należy określać naddomeny w parametrze connectionName dla odbierającego obiektu LocalConnection — można to zrobić jedynie w obiekcie wysyłającym LocalConnection.

Korzystając z tej metody, należy wziąć pod uwagę następujący model zabezpieczeń programu Flash Player. Domyślnie obiekt LocalConnection jest skojarzony z obszarem izolowanym pliku, który go utworzył, i międzydomenowe wywołania obiektów LocalConnection są niedozwolone, do momentu wywołania w pliku odbierającym metody LocalConnection.allowDomain(). W przypadku treści SWF działającej w przeglądarce istnieje możliwość zapobieżenia użyciu tej metody w pliku; należy w tym celu ustawić parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej treść SWF. Jednak w aplikacji Adobe AIR zawartość obszaru izolowanego application (zawartość instalowana razem z aplikacją AIR) nie jest ograniczana przez te reguły zabezpieczeń.

Więcej informacji na temat zabezpieczeń zawiera odpowiedni temat w Centrum programistów programu Flash Player w kategorii Bezpieczeństwo.

Parametry

Powiązane elementy interfejsu API

Wywoływana w przypadku asynchronicznego zgłoszenia wyjątku — pochodzącego z macierzystego kodu asynchronicznego.

To zdarzenie ma następujące właściwości:

Wywoływana, jeśli wywołanie metody LocalConnection.send() skutkuje próbą wysłania danych do innego obszaru izolowanego.

To zdarzenie ma następujące właściwości:

Powiązane elementy interfejsu API

Dysponowana, gdy obiekt LocalConnection zgłasza swój stan. Jeśli metoda LocalConnection.send() zakończy się powodzeniem, wartością właściwościlevel obiektu zdarzenia status jest "status"; jeśli wywołanie zakończy się niepowodzeniem właściwość level ma wartość "error". Jeśli odbierający plik odrzuci połączenie, wywołanie może zakończyć się niepowodzeniem bez powiadomienia dla pliku wysyłającego

To zdarzenie ma następujące właściwości:

Powiązane elementy interfejsu API

W pliku SWF LocalConnectionSenderExample tworzona jest instancja LocalConnection i kiedy zostanie naciśnięty przycisk, metoda call() zostanie użyta w celu wywołania metody o nazwie lcHandler w pliku SWF, którego nazwa połączenia to "myConnection," przekazując treść pola TextField jako parametr.

W pliku SWF LocalConnectionReceiverExample tworzona jest instancja LocalConnection i wywoływana jest metoda connect() w celu wskazania tego pliku SWF jako odbiorcy komunikatów, które są adresowane do połączenia o nazwie „myConnection”. Poza tym ta klasa zawiera metodę publiczną o nazwie lcHandler(); ta metoda jest tą, która wywoływana jest przez plik SWF LocalConnectionSenderExample. W czasie momencie·tekst, który jest przekazywany jako parametr, jest dołączany do pola·TextField na stole montażowym.

Uwaga: Aby przetestować ten przykład, oba pliki SWF muszą być ładowane na tym samym komputerze jednocześnie.

// 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);
        }
    }
}