LocalConnection  - AS3

Указывает объект, для которого вызываются методы ответного вызова. Объект по умолчанию: this (создаваемое локальное подключение). Если в свойстве client указать другой объект, методы обратного вызова будут вызываться на этом другом объекте.

Строка, представляющая домен расположения текущего файла.

В содержимом, выполняющемся в изолированной программной среде безопасности application в Adobe AIR (содержимое, установленное с приложением AIR), среда выполнения использует строку app#, за которой следует идентификатор приложения AIR (определенный в файле дескриптора приложения), вместо обозначения супердомена. Например, connectionName для приложения с идентификатором com.example.air.MyApp connectionName преобразуется в app#com.example.air.MyApp:connectionName.

В возвращенной строке SWF-файлов, опубликованных для проигрывателя Flash Player 9 или более поздних версий, в точности указывается домен файла, включая субдомены. Например, если файл размещен на сайте 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 и более ранних версиях все объекты LocalConnection в ОС Mac OS X имеют глобальную область действия. Всегда устанавливайте этому свойству значение true, если не требуется обеспечить совместимость с более ранними версиями. В будущих версиях значение по умолчанию для данного свойства может измениться на true.

Значением по умолчанию является false.

Свойству isSupported задается значение true, если текущая платформа поддерживает класс LocalConnection, в противном случае задается значение false.

Создает объект LocalConnection. С помощью объектов LocalConnection можно обеспечить обмен данными между различными файлами, запущенными на одном и том же клиентском компьютере.

Связанные элементы API

Задает один или несколько доменов, которые могут направлять вызовы LocalConnection к данному экземпляру LocalConnection.

Данный метод нельзя использовать в целях предоставления файлам, размещенным по незащищенным протоколам, доступа к файлам, размещенным с помощью защищенного протокола (HTTPS). Вместо этого используйте метод allowInsecureDomain().

Этот метод можно использовать для того, чтобы дочерний файл из другого домена мог осуществлять вызовы LocalConnection, направленные родительскому файлу, при этом не будет известен конечный домен, который будет источником дочернего файла. Это может случиться, например, при использовании перенаправлений для балансировки нагрузки или серверов независимых производителей. В этой ситуации можно с помощью свойства url, используемого с нагрузкой объекта LoaderInfo, получить домен для использования с методом allowDomain(). Например, рассмотрим ситуацию использования объекта Loader для загрузки дочернего файла. Как только файл будет загружен, можно будет просмотреть свойство contentLoaderInfo.url объекта Loader и извлечь домен из строки полного URL-адреса. При этом необходимо дождаться полной загрузки файла, так как свойство contentLoaderInfo.url будет иметь свое конечное правильное значение только после завершения загрузки файла.

Также может возникнуть и противоположная ситуация: создан дочерний файл, которому необходимо принимать вызовы LocalConnection от родительского файла, но домен родительского объекта неизвестен. В этой ситуации реализация данного метода подразумевает следующую проверку: совпадает ли аргумент домена с доменом свойства loaderInfo.url в загруженном файле. Здесь также необходимо извлечь домен из полного URL-адреса в свойстве loaderInfo.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() дополнительно разрешает SWF-файлам, поступившим не по протоколу HTTPS, отправлять вызовы LocalConnection в адрес файлов, полученных по протоколу HTTPS. Это различие имеет значение только в том случае, если метод allowInsecureDomain() вызывается из файла, который был загружен по протоколу HTTPS. Метод allowInsecureDomain() следует вызывать даже в том случае, если происходит пересечение границ HTTPS/HTTPS в рамках одного домена. По умолчанию вызовы LocalConnection, направленные от файлов, поступивших не по протоколу HTTPS, к файлам, загруженным с помощью протокола HTTPS, всегда запрещены даже в рамках одного и того же домена.

Не рекомендуется вызывать метод allowInsecureDomain(), так как он может нарушить безопасность, обеспечиваемую протоколом HTTPS. При загрузке файла по протоколу HTTPS у вас должна присутствовать обоснованная уверенность в том, что в процессе доставки по сети на данный файл не будет оказываться никакого вредного воздействия. Если вы позднее разрешите файлу, поступившему не по протоколу HTTPS, делать вызовы LocalConnection в отношении файла, загруженного с помощью HTTPS, то тем самым вы будете принимать вызовы от файла, который мог в процессе доставки подвергнуться вмешательству. Это, как правило, требует особой осторожности, так как нельзя быть полностью уверенным в подлинности вызовов LocalConnection, поступающих вашему файлу по протоколу HTTPS.

По умолчанию файлы, размещенные с помощью протокола HTTPS, доступны только для любых других файлов, размещенных посредством того же протокола (HTTPS). Такая реализация позволяет сохранить целостность, обеспечиваемую протоколом HTTPS.

Не рекомендуется использовать этот метод для переназначения характеристик по умолчанию, так как это может ослабить систему защиты протокола HTTPS. Тем не менее, это может потребоваться, например, если вам необходимо разрешить HTTP-файлам, опубликованным для Flash Player 6 и более ранних версий, доступ к HTTPS-файлам, опубликованным для Flash Player 9 и более поздних версий.

Дополнительные сведения о безопасности см. в разделе центра разработчиков Flash Player Безопасность.

Параметры

Связанные элементы API

Закрывает (отключает) объект LocalConnection. Запустите данную команду, если больше не требуется, чтобы объект принимал команды, например при необходимости инициировать команду connect() с помощью того же самого параметра connectionName в другом SWF-файле.

Связанные элементы 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.)

В содержимом, выполняющемся в изолированной программной среде безопасности application в Adobe AIR (содержимое, установленное с приложением AIR), среда выполнения использует строку app#, за которой следует идентификатор приложения AIR (определенный в файле дескриптора приложения), вместо обозначения супердомена. Например, connectionName для приложения с идентификатором com.example.air.MyApp connectionName преобразуется в app#com.example.air.MyApp:connectionName.

Вдобавок, по умолчанию проигрыватель Flash Player позволяет принимающему объекту LocalConnection принимать команды только от отправляющих объектов LocalConnection, имя подключения которых также преобразовывается в значение "superdomain:connectionName". Таким образом файлам, размещенным в одном домене, становится проще взаимодействовать друг с другом.

Если вы реализуете механизм взаимодействия только между файлами в рамках одного домена, укажите строку для connectionName, которая не будет начинаться с символа подчеркивания (_) и не будет определять имя домена (например, myDomain:connectionName). Используйте ту же самую строку в методе connect(connectionName).

При реализации механизма взаимодействия файлов в разных доменах определение строки для параметра connectionName, в начале которой стоит символ подчеркивания (_), обеспечивает большую междоменную мобильность файла с принимающим объектом LocalConnection. Далее представлены два возможных варианта:

• Если строка для 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() в принимающем файле. Можно запретить использование файлом этого метода путем установки параметра allowNetworking для тегов object и embed на странице HTML, содержащей SWF-содержимое. Однако в Adobe AIR эти ограничения по безопасности не распространяются на содержимое в изолированной программной среде безопасности application (содержимое, установленное с приложением AIR).

Дополнительные сведения о безопасности см. в разделе центра разработчиков Flash Player Безопасность.

Параметры

Связанные элементы API

Вызывает метод с именем methodName для подключения, открытого методом connect (connectionName) (в принимающем объекте LocalConnection). Объект, используемый с методом send() называется отправляющим объектом LocalConnection. SWF-файлы, содержащие отправляющие и принимающие объекты, должны запускаться на одном и том же клиентском компьютере.

Объем данных, которые можно передать как параметры для этой команды, ограничен 40 килобайтами. Если при наличии правильного синтаксиса метод send() отображает ошибку ArgumentError, попробуйте разделить запросы send() на несколько команд (объем каждой не должен превышать 40 КБ).

Как уже было сказано в описании метода connect(), текущий супердомен добавляется к строке connectionName по умолчанию. При реализации механизма обмена данными между разными доменами необходимо определить параметр connectionName как в отправляющем, так и в принимающем объекте LocalConnection так, чтобы к строке connectionName не добавлялся текущий супердомен. Это можно выполнить одним из следующих способов:

• Используйте символ подчеркивания (_) в начале параметра connectionName отправляющих и принимающих объектов LocalConnection. С помощью метода LocalConnection.allowDomain() укажите в файле, содержащем принимающий объект, что будут приниматься подключения с любого домена. Данная реализация позволяет хранить отправляющие и принимающие файлы в любом домене.
• Добавьте супердомен в параметр connectionName в отправляющем объекте LocalConnection — например myDomain.com:myConnectionName. В принимающем объекте с помощью метода LocalConnection.allowDomain() укажите, что подключения из указанного супердомена будут приняты (в данном случае, myDomain.com) или что будут приняты подключения из любого домена.

Примечание. Не следует указывать супердомен в параметре connectionName принимающего объекта LocalConnection — это можно делать только в отправляющем объекте LocalConnection.

При использовании данного метода необходимо продумать модель безопасности проигрывателя Flash Player. По умолчанию объект LocalConnection связан с изолированной программной средой создавшего его файла, при этом вызовы объектов LocalConnection между доменов запрещены, если только вы не вызываете метод LocalConnection.allowDomain() в принимающем файле. В случае с SWF-содержимым, выполняющимся в обозревателе, можно запретить файлу использовать этот метод, задав параметр allowNetworking для тегов object и embed HTML-страницы с SWF-содержимым. Однако в Adobe AIR эти ограничения по безопасности не распространяются на содержимое в изолированной программной среде безопасности application (содержимое, установленное с приложением AIR).

Дополнительные сведения о безопасности см. в разделе центра разработчиков Flash Player Безопасность.

Параметры

Связанные элементы API

Отправляется, когда исключение создается асинхронным образом, то есть в коде, изначально имеющем асинхронную природу.

Это событие имеет следующие свойства:

Отправляется, если путем вызова метода LocalConnection.send() предпринимается попытка отправить данные в другую изолированную среду.

Это событие имеет следующие свойства:

Связанные элементы API

Отправляется, когда объект LocalConnection сообщает о своем состоянии. При успешном вызове LocalConnection.send() свойство level объекта события status получает значение status. В противном случае свойство level имеет значение error. Если принимающий файл отказывает в подключении, сбой вызова может произойти без оповещения отправляющего файла.

Это событие имеет следующие свойства:

Связанные элементы API

В SWF-файле LocalConnectionSenderExample создается экземпляр LocalConnection. При нажатии на кнопку с помощью метода call() вызывается метод с именем lcHandler в SWF-файле с именем подключения myConnection, при этом в качестве параметра передается содержимое TextField.

В SWF-файле LocalConnectionReceiverExample создается экземпляр LocalConnection, а затем с помощью вызванного метода connect() данный SWF-файл определяется как получатель сообщений, адресованных подключению myConnection. Вдобавок, в данный класс входит публичный метод lcHandler(), который вызывается SWF-файлом LocalConnectionSenderExample. При вызове этого метода текст, переданный в качестве параметра, прикрепляется к полю TextField в компоненте Stage.

Примечание. Чтобы протестировать этот пример, необходимо одновременно загрузить на одном компьютере оба 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);
        }
    }
}