LocalConnection  - AS3

Indica o objeto no qual os métodos de retorno de chamada são invocados. O objeto padrão é this, a conexão local que está sendo criada. É possível definir a propriedade client como outro objeto e os métodos de retorno de chamada são invocados nesse outro objeto.

Uma string que representa o domínio da localização do arquivo atual.

No conteúdo em execução na área de segurança application no Adobe AIR (conteúdo instalado com o AIR), o tempo de execução usa a string app#seguida pela ID do aplicativo para o AIR (definido no arquivo descritivo) no lugar do superdomínio. Por exemplo, um connectionName para um aplicativo com a ID com.example.air.MyApp connectionName resolve para "app#com.example.air.MyApp:connectionName".

Em arquivos SWF publicados para o Flash Player 9 ou posterior, a string retornada é o domínio exato do arquivo, incluindo subdomínios. Por exemplo, se o arquivo estiver localizado em www.adobe.com, esse comando retornará "www.adobe.com".

Se o arquivo atual for um arquivo local que reside no computador cliente em execução no Flash Player, esse comando retornará "localhost".

As maneiras mais comuns de usar essa propriedade são incluir o nome de domínio do objeto LocalConnection de envio como um parâmetro no método que você planeja invocar no objeto LocalConnection de recebimento ou usá-lo com LocalConnection.allowDomain() para aceitar comandos de um domínio especificado. Se você estiver ativando a comunicação apenas entre objetos LocalConnection localizados no mesmo domínio, provavelmente não precisará usar essa propriedade.

Elementos da API relacionados

Indica se o objeto LocalConnection está no escopo do usuário atual (true) ou é globalmente acessível a todos os usuários do computador (false). Esta propriedade só afeta a execução de conteúdo no Mac OS X; outras plataformas ignoram este parâmetro. As conexões em sistemas operacionais Windows e Linux são sempre por usuário.

No Flash Player 10.0.22 e versões anteriores e no AIR 1.5.1 e versões anteriores, todos os objetos LocalConnection no Mac OS X têm um alcance global. Sempre estabeleça esta propriedade como true, a menos que você tenha de preservar a compatibilidade com versões anteriores. Em futuros lançamentos, o valor padrão desta propriedade poderia modificar-se para true.

O valor padrão é false.

A propriedade isSupported será definida como true se a classe LocalConnection for suportada na plataforma atual; de outra maneira, ela será definida como false.

Cria um objeto LocalConnection. É possível usar objetos LocalConnection para permitir a comunicação entre diferentes arquivos em execução no mesmo computador cliente.

Elementos da API relacionados

Especifica um ou mais domínios que podem enviar chamadas LocalConnection a esta ocorrência de LocalConnection.

Esse método não pode ser usado para permitir que arquivos hospedados com o uso de um protocolo seguro (HTTPS) tenham acesso a partir de arquivos hospedados em protocolos não seguros. Para tanto, use o método allowInsecureDomain().

Convém usar esse método para que um arquivo filho de um domínio diferente possa fazer chamadas LocalConnection locais ao arquivo pai, sem conhecer o domínio final a partir do qual o arquivo filho surgirá. Isso pode acontecer, por exemplo, quando você usa redirecionamentos de balanceamento de carga ou servidores terceirizados. Nessa situação, você pode usar a propriedade url do objeto LoaderInfo usado com o carregamento, para obter o domínio a ser usado com o método allowDomain(). Por exemplo, se você usar um objeto Loader para carregar um arquivo filho, quando o arquivo estiver carregado, será possível verificar a propriedade contentLoaderInfo.url desse objeto Loader e analisar o domínio fora da string URL completa. Se você não fizer isso, certifique-se de aguardar a conclusão do carregamento do arquivo, uma vez que a propriedade contentLoaderInfo.url apenas terá seu valor final correto quando o arquivo estiver totalmente carregado.

A situação oposta também pode ocorrer: você pode criar um objeto filho que deseja aceitar chamadas LocalConnection a partir do seu pai, mas que não conhece o domínio desse pai. Nessa situação, implemente esse método verificando se o argumento de domínio corresponde ao domínio da propriedade loaderInfo.url no arquivo carregado. Mais uma vez, é necessário analisar o domínio fora da URL completa a partir de loaderInfo.url. Nessa situação, não é necessário aguardar o carregamento do arquivo pai; o pai já terá sido carregado na ocasião em que o filho for carregado.

Ao usar esse método, considere o modelo de segurança do Flash Player. Por padrão, um objeto LocalConnection é associado à caixa de proteção do arquivo que o criou e chamadas entre domínios a objetos LocalConnection não são permitidas, a não ser que você chame o método LocalConnection.allowDomain() no arquivo de recebimento. Contudo, no Adobe AIR, o conteúdo na caixa de proteção de segurança application (conteúdo instalado com o Adobe AIR) não é restringido por essas limitações de segurança.

Para obter mais informações relacionadas à segurança, consulte o tópico do Centro dos desenvolvedores do Flash Player Security.

Observação: A forma do método allowDomain() foi alterado a partir do ActionScript 1.0 e 2.0. Nessas versões anteriores, allowDomain era um método de retorno de chamada que você implementava. No ActionScript 3.0, allowDomain() é um método embutido de LocalConnection que você chama. Com essa alteração, allowDomain() funciona da mesma maneira que flash.system.Security.allowDomain().

Parâmetros

Elementos da API relacionados

Especifica um ou mais domínios que podem enviar chamadas LocalConnection a este objeto LocalConnection.

O método allowInsecureDomain() funciona como o método allowDomain(), com a exceção de que o método allowInsecureDomain() permite adicionalmente que arquivos de origens não HTTPS enviem chamadas LocalConnection a arquivos SWF de origens HTTPS. Essa diferença apenas será significativa se você chamar o método allowInsecureDomain() a partir de um arquivo que foi carregado usando HTTPS. Será necessário chamar o método allowInsecureDomain() mesmo que você esteja atravessando um limite não HTTPS/HTTPS dentro do mesmo domínio; por padrão, chamadas LocalConnection nunca são permitidas a partir de arquivos não HTTPS para arquivos HTTPS, mesmo dentro do mesmo domínio.

Não convém chamar allowInsecureDomain(), uma vez que isso pode comprometer a segurança oferecida pelo HTTPS. Ao carregar um arquivo via HTTPS, você tem a garantia de que esse arquivo não será adulterado durante a entrega via rede. Se você permitir que um arquivo não HTTPS faça chamadas LocalConnection para o arquivo HTTPS, estará aceitando chamadas de um arquivo que, de fato, pode ter sido adulterado durante a entrega. Isso geralmente requer uma vigilância extra, já que não é possível confiar na autenticidade de chamadas LocalConnection que chegam ao seu arquivo HTTPS.

Por padrão, os arquivos hospedados com o uso do protocolo HTTPS apenas podem ser acessados por outros arquivos hospedados com o protocolo HTTPS. Essa implementação mantém a integridade fornecida pelo protocolo HTTPS.

O uso deste método para substituir o comportamento padrão não é recomendado, pois ele compromete a segurança HTTPS. Entretanto, talvez seja necessário fazer isso, por exemplo, se você precisar permitir acesso a arquivos SWF HTTPS publicados para o Flash Player 9 ou posterior a partir de arquivos SWF HTTP publicados para o Flash Player 6 ou anterior.

Para obter mais informações relacionadas à segurança, consulte o tópico do Centro dos desenvolvedores do Flash Player Security.

Parâmetros

Elementos da API relacionados

Fecha (desconecta) um objeto LocalConnection. Emita esse comando quando você não quiser mais que o objeto aceite comandos; por exemplo, quando quiser emitir um comando connect() usando o mesmo parâmetro connectionName em outro arquivo SWF.

Elementos da API relacionados

Prepara um objeto LocalConnection para receber comandos que são despachados de um comando send() (do objeto LocalConnection de envio). O objeto usado com o método connect() é chamado de objeto LocalConnection de recebimento. Os objetos de envio e recebimento devem estar em execução no mesmo computador cliente.

Para evitar uma condição de risco, defina os métodos anexados ao objeto LocalConnection de recebimento antes de chamar esse método, como mostra o exemplo da classe LocalConnection.

Por padrão, o argumento connectionName é resolvido em um valor de "superdomain:connectionName", em que superdomain é o superdomínio do arquivo que contém o comando connect(). Por exemplo, se o arquivo que contém o objeto LocalConnection de recebimento localizado em www.someDomain.com, connectionName é resolvido como "someDomain.com:nomeConexão". (Se um arquivo em execução no Flash Player estiver localizado no computador cliente, o valor atribuído a superdomain será "localhost".)

No conteúdo em execução na área de segurança application no Adobe AIR (conteúdo instalado com o AIR), o tempo de execução usa a string app#seguida pela ID do aplicativo para o AIR (definido no arquivo descritivo) no lugar do superdomínio. Por exemplo, um connectionName para um aplicativo com a ID com.example.air.MyApp connectionName resolve para "app#com.example.air.MyApp:connectionName".

Além disso, por padrão, o Flash Player permite que o objeto LocalConnection de recebimento aceite comandos apenas de objetos LocalConnection de envio cujo nome de conexão também seja resolvido em um valor de "superdomain:connectionName". Dessa maneira, o Flash Player simplifica a comunicação entre arquivos localizados no mesmo domínio.

Se você estiver implementando a comunicação apenas entre arquivos no mesmo domínio, especifique uma string para connectionName que não comece com um sublinhado (_) e que não determine um nome de domínio (por exemplo, "myDomain:nomeConexão"). Use a mesma string no método connect(connectionName).

Se você estiver implementando a comunicação entre arquivos em diferentes domínios, especificar uma string para connectionName que comece com um sublinhado (_) torna o arquivo com o objeto LocalConnection de recebimento mais durável entre domínios. Estes são os dois casos possíveis:

• Se a string para connectionName não começar com um sublinhado (_), um prefixo é adicionado com o superdomínio e um caractere de dois pontos (por exemplo, "myDomain:connectionName"). Embora isso garanta que a sua conexão não entre em conflito com as conexões de nome idêntico em outros domínios, qualquer objeto LocalConnection de envio deve especificar esse superdomínio (por exemplo, "myDomain:connectionName"). Se o arquivo com o objeto LocalConnection de recebimento for movido para outro domínio, o player alterará o prefixo de modo a refletir o novo superdomínio (por exemplo, "anotherDomain:connectionName"). Todos os objetos LocalConnection de envio precisariam ser manualmente editados de modo a apontar para o novo superdomínio.
• Se a string para connectionName começar com um sublinhado (por exemplo, "_connectionName"), um prefixo não será adicionado. Isso significa que os objetos LocalConnection de recebimento e envio usam strings idênticas para connectionName. Se o objeto de recebimento usar allowDomain() para especificar que serão aceitas conexões de qualquer domínio, o arquivo com o objeto LocalConnection de recebimento poderá ser movido para outro domínio sem alterar qualquer objeto LocalConnection de envio.

Para obter mais informações, consulte a discussão na visão geral sobre a classe e a discussão de connectionName em send(), bem como as entradas allowDomain() e domain.

Observação: caracteres de dois pontos são usados como caracteres especiais para separar o superdomínio da string connectionName. Uma string para connectionName que contenha um caractere de dois pontos não é válida.

Ao usar esse método, considere o modelo de segurança do Flash Player. Por padrão, um objeto LocalConnection é associado à caixa de proteção do arquivo que o criou e chamadas entre domínios a objetos LocalConnection não são permitidas, a não ser que você chame o método LocalConnection.allowDomain() no arquivo de recebimento. Você pode impedir o arquivo de usar esse método configurando o parâmetro allowNetworking das marcas object e embed na página HTML com o conteúdo SWF.Contudo, no Adobe AIR, o conteúdo na área de segurança application (conteúdo instalado com o Adobe AIR) não é restringido por essas limitações de segurança.

Para obter mais informações relacionadas à segurança, consulte o tópico do Centro dos desenvolvedores do Flash Player Security.

Parâmetros

Elementos da API relacionados

Invoca o método denominado methodName em uma conexão aberta com o método connect(connectionName) (no objeto LocalConnection de recebimento). O objeto usado com o método send() é chamado de objeto LocalConnection de envio. Os arquivos SWF que contêm os objetos de envio e recebimento devem estar em execução no mesmo computador cliente.

Há um limite de 40 quilobytes sobre a quantidade de dados que podem ser transmitidos como parâmetros a esse comando. Se send() lançar ArgumentError, mas a sua sintaxe estiver correta, tente dividir as solicitações send() em vários comandos, cada um com menos de 40K de dados.

Conforme discutido na entrada connect(), o superdomínio atual é adicionado a connectionName por padrão. Se você estiver implementando a comunicação entre diferentes domínios, precisará definir connectionName nos objetos LocalConnection de envio e recebimento, de maneira que o superdomínio atual não seja adicionado a connectionName. Isso pode ser feito de uma destas duas maneiras:

• Use um sublinhado (_) no início de connectionName dos objetos LocalConnection de envio e recebimento. No arquivo que contém o objeto de recebimento, use LocalConnection.allowDomain() para especificar que serão aceitas conexões de qualquer domínio. Essa implementação permite armazenar os arquivos de envio e recebimento em qualquer domínio.
• Inclua o superdomínio em connectionName no objeto LocalConnection de envio - por exemplo, myDomain.com:myConnectionName. No objeto de recebimento, use LocalConnection.allowDomain() para especificar que serão aceitas conexões do superdomínio especificado (nesse caso, meuDomínio.com) ou que serão aceitas conexões de qualquer domínio.

Observação: Não é possível especificar um superdomínio em connectionName do objeto LocalConnection de recebimento; isso pode ser feito apenas no objeto LocalConnection de envio.

Ao usar esse método, considere o modelo de segurança do Flash Player. Por padrão, um objeto LocalConnection é associado à caixa de proteção do arquivo que o criou e chamadas entre domínios a objetos LocalConnection não são permitidas, a não ser que você chame o método LocalConnection.allowDomain() no arquivo de recebimento. Para o conteúdo SWF em execução no navegador, você pode impedir o arquivo de usar esse método configurando o parâmetro allowNetworking das marcas object e embed na página HTML com o conteúdo SWF. Contudo, no Adobe AIR, o conteúdo na caixa de proteção de segurança application (conteúdo instalado com o Adobe AIR) não é restringido por essas limitações de segurança.

Para obter mais informações relacionadas à segurança, consulte o tópico do Centro dos desenvolvedores do Flash Player Security.

Parâmetros

Elementos da API relacionados

Despachado quando uma exceção é lançada assincronamente – ou seja, a partir do código assíncrono nativo.

Esse evento tem as seguintes propriedades:

Despachado se uma chamada para LocalConnection.send() tentar enviar dados a uma área de segurança diferente.

Esse evento tem as seguintes propriedades:

Elementos da API relacionados

Despachado quando um objeto LocalConnection relata seu status. Se LocalConnection.send() for bem-sucedido, o valor da propriedade level do objeto de evento de status será "status"; se a chamada falhar, a propriedade level será "error". Se o arquivo de recebimento recusar a conexão, a chamada poderá falhar sem notificação ao arquivo de envio.

Esse evento tem as seguintes propriedades:

Elementos da API relacionados

No arquivo SWF LocalConnectionSenderExample, uma ocorrência de LocalConnection é criada e, quando o botão é pressionado, o método call() é usado para chamar o método denominado lcHandler no arquivo SWF com o nome de conexão "myConnection", transmitindo o conteúdo de TextField como um parâmetro.

No arquivo SWF LocalConnectionReceiverExample, uma ocorrência de LocalConnection é criada, e o método connect() é chamado para designar esse arquivo SWF como o destinatário de mensagens que são endereçadas à conexão denominada "myConnection". Além disso, essa classe inclui um método público denominado lcHandler(); esse método é chamado pelo arquivo SWF LocalConnectionSenderExample. Ao ser chamado, o texto transmitido como parâmetro é acrescentado a TextField no Palco.

Observação: Para testar o exemplo, ambos os arquivos SWF devem ser carregados no mesmo computador simultaneamente.

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