SharedObject  - AS3

Indica o objeto no qual os métodos de retorno de chamada são invocados. O objeto padrão é this. É possível definir a propriedade "client" como outro objeto, e os métodos de retorno de chamada serão invocados nesse outro objeto.

A coleção de atributos designados à propriedade data do objeto; esses atributos podem ser armazenados e compartilhados. Cada atributo pode ser um objeto de qualquer tipo ActionScript ou JavaScript — Array, Number, Boolean, ByteArray, XML e assim por diante. Por exemplo, as linhas a seguir atribuem valores a vários aspectos de um objeto compartilhado:

     var items_array:Array = new Array(101, 346, 483);
     var currentUserIsAdmin:Boolean = true;
     var currentUserName:String = "Ramona";
     
     var my_so:SharedObject = SharedObject.getLocal("superfoo");
     my_so.data.itemNumbers = items_array;
     my_so.data.adminPrivileges = currentUserIsAdmin;
     my_so.data.userName = currentUserName;
     
     for (var prop in my_so.data) {
       trace(prop+": "+my_so.data[prop]);
     }
     

Todos os atributos da propriedade data de um objeto compartilhado serão salvos se esse objeto for persistente, e o objeto compartilhado contém as seguintes informações:

     userName: Ramona
     adminPrivileges: true
     itemNumbers: 101,346,483
     

Observação: Não atribua valores diretamente à propriedade data de um objeto compartilhado, como em so.data = someValue; o Flash Player ignora esse tipo de atribuição.

Para excluir atributos para objetos compartilhados locais, use um código como delete so.data.attributeName. Definir um atributo como null ou undefined para um objeto compartilhado local não exclui esse atributo.

Para criar valores privados para um objeto compartilhado (valores disponíveis somente para a ocorrência do cliente enquanto o objeto estiver em uso e que não são armazenados com esse objeto quando ele é fechado) crie propriedades não denominadas data para armazená-los, como mostra o exemplo a seguir:

     var my_so:SharedObject = SharedObject.getLocal("superfoo");
     my_so.favoriteColor = "blue";
     my_so.favoriteNightClub = "The Bluenote Tavern";
     my_so.favoriteSong = "My World is Blue";
     
     for (var prop in my_so) {
       trace(prop+": "+my_so[prop]);
     }
     

O objeto compartilhado contém os seguintes dados:

     favoriteSong: My World is Blue
     favoriteNightClub: The Bluenote Tavern
     favoriteColor: blue
     data: [object Object]
     

Para objetos compartilhados remotos usados com um servidor, todos os atributos da propriedade data estão disponíveis a todos os clientes conectados ao objeto compartilhado, e todos os atributos serão salvos se o objeto for persistente. Se um cliente alterar o valor de um atributo, todos os clientes verão o novo valor.

Elementos da API relacionados

A codificação de objeto padrão (versão AMF) para todos os objetos compartilhados locais criados no arquivo SWF. Quando objetos compartilhados locais são gravados em disco, a propriedade SharedObject.defaultObjectEncoding indica qual versão do AMF (Action Message Format) deve ser usada: o formato ActionScript 3.0 (AMF3) ou o formato ActionScript 1.0 ou 2.0 (AMF0).

Para obter mais informações sobre a codificação de objetos, incluindo a diferença entre a codificação em objetos compartilhados locais e remotos, consulte a descrição da propriedade objectEncoding.

O valor padrão de SharedObject.defaultObjectEncoding é definido de forma a utilizar o formato ActionScript 3.0, AMF3. Se você precisar gravar objetos compartilhados locais que podem ser lidos por arquivos SWF ActionScript 2.0 ou 1.0, defina SharedObject.defaultObjectEncoding de forma a utilizar o formato ActionScript 1.0 ou ActionScript 2.0, flash.net.ObjectEncoding.AMF0, no início do script, antes de você criar objetos compartilhados locais. Todos os objetos compartilhados locais criados dali em diante usarão a codificação AMF0 e poderão interagir com conteúdo mais antigo. Não é possível alterar o valor objectEncoding de objetos compartilhados locais existentes definindo SharedObject.defaultObjectEncoding após a criação dos objetos compartilhados locais.

Para definir a codificação para cada objeto em vez de para todos os objetos compartilhados criados pelo arquivo SWF, defina a propriedade objectEncoding do objeto compartilhado local como alternativa.

Elementos da API relacionados

Especifica o número de vezes por segundo que as alterações de um cliente em um objeto compartilhado são enviadas ao servidor.

Use esse método quando quiser controlar a quantidade de tráfego entre o cliente e o servidor. Por exemplo, se a conexão entre o cliente e o servidor for relativamente lenta, convém definir fps como um valor relativamente baixo. De modo oposto, se o cliente estiver conectado a um aplicativo para vários usuários no qual a temporização seja importante, convém definir fps como um valor relativamente alto.

Definir fps acionará um evento sync e atualizará todas as alterações no servidor. Se você apenas quiser atualizar o servidor manualmente, defina fps como 0.

As alterações não serão enviadas ao servidor até que o evento sync tenha sido despachado. Ou seja, se o tempo de resposta do servidor for lento, as atualizações poderão ser enviadas ao servidor com menor frequência do que o valor especificado nessa propriedade.

A codificação de objeto (versão AMF) para este objeto compartilhado. Quando um objeto compartilhado local é gravado em disco, a propriedade objectEncoding indica qual versão do AMF (Action Message Format) deve ser usada: o formato ActionScript 3.0 (AMF3) ou o formato ActionScript 1.0 ou 2.0 (AMF0).

A codificação de objetos será manipulada de maneira diferente dependendo de o objeto compartilhado ser local ou remoto.

• Objetos compartilhados locais. Você pode obter ou definir o valor da propriedade objectEncoding para objetos compartilhados locais. O valor de objectEncoding afeta qual formatação é usada para a gravação desse objeto compartilhado local. Se esse objeto compartilhado local precisar ser legível por arquivos SWF ActionScript 2.0 ou 1.0, defina objectEncoding como ObjectEncoding.AMF0. Mesmo que a codificação de objetos esteja definida para gravar no AMF3, o Flash Player ainda pode ler objetos compartilhados locais AMF0. Ou seja, se você usar o valor padrão dessa propriedade, ObjectEncoding.AMF3, seu arquivo SWF ainda poderá ler os objetos compartilhados criados por arquivos SWF ActionScript 2.0 ou 1.0.
• Objetos compartilhados remotos. Quando conectado ao servidor, um objeto compartilhado remoto herda sua configuração de objectEncoding da ocorrência de NetConnection associada (a ocorrência usada para conexão com o objeto compartilhado remoto). Quando não conectado ao servidor, um objeto compartilhado remoto herda a configuração de defaultObjectEncoding da ocorrência de NetConnection associada. Como o valor da propriedade objectEncoding de um objeto compartilhado remoto é determinado pela ocorrência de NetConnection, essa propriedade é somente leitura para objetos compartilhados remotos.

Elementos da API relacionados

Especifica se os objetos locais compartilhados serão armazenados no serviço de backup em nuvem do iOS.

Especifique true ou false:

• true: impede que os objetos locais compartilhados sejam armazenados no serviço de backup em nuvem do iOS.
• false (o padrão): os objetos locais compartilhados serão armazenados no serviço de backup em nuvem do iOS.

Essa propriedade aplica-se somente aos objetos locais compartilhados e é compatível somente com o iOS.

O tamanho atual do objeto compartilhado, em bytes.

O Flash calcula o tamanho de um objeto compartilhado avançando por todas as suas propriedades de dados. Quanto mais propriedades de dados o objeto tiver, maior será o tempo necessário para estimar o seu tamanho. A estimativa do tamanho do objeto pode exigir um tempo de processamento significativo e, portanto, convém evitar o uso desse método, a não ser que exista uma necessidade específica.

import flash.net.SharedObject;

// if these get copied or not
var mySo:SharedObject = SharedObject.getLocal("thehobbit");
mySo.data.username = "bilbobaggins";
trace(mySo.size); // 55

Para objetos compartilhados locais, expurga todos os dados e exclui o objeto compartilhado do disco. A referência ao objeto compartilhado permanece ativa, mas suas propriedades de dados são excluídas.

Para objetos compartilhados remotos usados com o Flash Media Server, clear() desconecta o objeto e expurga todos os dados. Se o objeto compartilhado for localmente persistente, esse método também excluirá o objeto compartilhado do disco. A referência ao objeto compartilhado permanece ativa, mas suas propriedades de dados são excluídas.

package {
    import flash.net.SharedObject;

    public class SharedObject_clear {
        private var hostName:String = "yourDomain";
        private var username:String = "yourUsername";

        public function SharedObject_clear() {
            var mySo:SharedObject = SharedObject.getLocal(hostName);
            if(mySo.data.username == null) {
                mySo.data.username = username;
                trace("set: " + mySo.data.username); // yourUsername
            }
            else {
                mySo.clear();
                trace("cleared: " + mySo.data.username); // undefined
            }
        }
    }
}

Encerra a conexão entre um objeto compartilhado remoto e o servidor. Se um objeto compartilhado remoto for localmente persistente, o usuário poderá fazer alterações na cópia local do objeto depois que esse método for chamado. As alterações feitas no objeto local serão enviadas ao servidor da próxima vez que o usuário se conectar ao objeto compartilhado remoto.

Conecta-se a um objeto compartilhado remoto em um servidor através de um objeto NetConnection especificado. Use esse método depois de chamar getRemote(). Quando uma conexão for bem-sucedida, o evento sync será despachado.

Antes de tentar trabalhar com um objeto compartilhado remoto, verifique primeiro se existem erros usando uma instrução try..catch..finally. Em seguida, forneça e manipule o evento sync antes de fazer alterações no objeto compartilhado. Todas as alterações feitas localmente (antes de o evento sync ser despachado) poderão ser perdidas.

Chame o método connect() para se conectar a um objeto compartilhado remoto, por exemplo:

     var myRemoteSO:SharedObject = SharedObject.getRemote("mo", myNC.uri, false);
     myRemoteSO.connect(myNC);
     

Parâmetros

Elementos da API relacionados

Grava imediatamente um objeto compartilhado localmente persistente em um arquivo local. Se você não usar esse método, o Flash Player gravará o objeto compartilhado em um arquivo quando a sessão desse objeto compartilhado for encerrada; ou seja, quando o arquivo SWF for fechado, quando o objeto compartilhado for coletado como lixo por não ter mais referências ao arquivo ou quando você chamar SharedObject.clear() ou SharedObject.close().

Se esse método retornar SharedObjectFlushStatus.PENDING, o Flash Player exibirá uma caixa de diálogo solicitando que o usuário aumente a quantidade de espaço em disco disponível a objetos deste domínio. Para permitir espaço de forma que o objeto compartilhado possa crescer quando for salvo no futuro, evitando assim valores de retorno de PENDING, transmita um valor para espaçoDiscoMin. Quando o Flash Player tentar gravar o arquivo, ele procurará pelo número de bytes transmitidos a espaçoDiscoMin, em vez de procurar por um espaço suficiente para salvar o objeto compartilhado com seu tamanho atual.

Por exemplo, se você espera que um objeto compartilhado cresça até um tamanho máximo de 500 bytes, mesmo que ele possa começar muito menor, transmita 500 para espaçoDiscoMin. Se o Flash solicitar que o usuário aloque espaço em disco para o objeto compartilhado, ele solicitará 500 bytes. Depois que o usuário alocar a quantidade de espaço requerida, o Flash não precisará solicitar mais espaço em tentativas futuras de descarregar o objeto (desde que o tamanho não exceda 500 bytes).

Depois que o usuário responder à caixa de diálogo, esse método será novamente chamado. Um evento netStatus é despachado com uma propriedade code de SharedObject.Flush.Success ou SharedObject.Flush.Failed.

Parâmetros

Elementos da API relacionados

package {
    import flash.net.SharedObject;

    public class SharedObject_flush {
        private var hostName:String = "yourDomain";
        private var username:String = "yourUsername";

        public function SharedObject_flush() {
            var mySo:SharedObject = SharedObject.getLocal(hostName);
            mySo.data.username = username;
            var flushResult:Object = mySo.flush();
            trace("flushResult: " + flushResult);
            trace(mySo.data.username); // yourUsername
        }
    }
}

Retorna uma referência a um objeto compartilhado localmente persistente que apenas está disponível para o cliente atual. Se o objeto compartilhado ainda não existir, esse método criará um. Se os valores transmitidos a getLocal() forem inválidos ou se a chamada falhar, o Flash Player lançará uma exceção.

O código a seguir mostra como atribuir à referência retornada do objeto compartilhado a uma variável:

var so:SharedObject = SharedObject.getLocal("savedData");

Observação: Se o usuário tiver optado por nunca permitir o armazenamento local para esse domínio, o objeto não será salvo localmente, mesmo que um valor para caminhoLocal seja especificado. A exceção a essa regra é o conteúdo local. O conteúdo local sempre pode gravar em disco os objetos compartilhados a partir de domínios de terceiros (domínios diferentes daquele na barra de endereços do navegador atual), mesmo se a gravação em disco de objetos compartilhados de terceiros não for permitida.

Para evitar conflitos de nome, o Flash examina a localização do arquivo SWF que está criando o objeto compartilhado. Por exemplo, se um arquivo SWF em www.myCompany.com/apps/stockwatcher.swf criar um objeto compartilhado denominado portfolio, esse objeto compartilhado não entrará em conflito com outro objeto denominado portfolio que foi criado por um arquivo SWF em www.yourCompany.com/photoshoot.swf, já que esses arquivos SWF foram originados em diretórios diferentes.

Embora o parâmetro caminhoLocal seja opcional, é necessário considerar o seu uso, especialmente se outros arquivos SWF precisarem de acesso ao objeto compartilhado. Se os dados no objeto compartilhado forem específicos para um arquivo SWF que não será movido para outro local, convém usar o valor padrão. Se outros arquivos SWF precisarem de acesso ao objeto compartilhado ou se o arquivo SWF que o criar for ser movido mais tarde, o valor desse parâmetro afetará o grau de acessibilidade do objeto compartilhado. Por exemplo, se você criar um objeto compartilhado com caminhoLocal definido como o valor padrão do caminho local para o arquivo SWF, nenhum outro arquivo SWF poderá acessar esse objeto compartilhado. Se, mais tarde, você mover o arquivo SWF original para outro local, nem mesmo esse arquivo SWF poderá acessar os dados já armazenados no objeto compartilhado.

Para evitar a restrição inadvertida do acesso a um objeto compartilhado, use o parâmetro caminhoLocal. A abordagem mais permissiva é definir caminhoLocal como / (barra), o que torna o objeto compartilhado disponível para todos os arquivos SWF no domínio, mas aumenta as chances de conflitos de nome com outros objetos compartilhados nesse domínio. Uma abordagem mais restritiva é acrescentar caminhoLocal com nomes de pastas que estejam no caminho completo para o arquivo SWF. Por exemplo, para um objeto compartilhado portfolio criado pelo arquivo SWF em www.myCompany.com/apps/stockwatcher.swf, você poderia definir o parâmetro localPath como /, /apps ou /apps/stockwatcher.swf. Determine qual abordagem proporciona flexibilidade ideal para o seu aplicativo.

Ao usar esse método, considere o seguinte modelo de segurança:

• Não é possível acessar objetos compartilhados entre limites de caixa de proteção.
• Os usuários podem restringir o acesso a objetos compartilhados usando a caixa de diálogo Configurações do Flash Player ou o Gerenciador de configurações. Por padrão, um aplicativo pode criar objetos compartilhados de até 100 KB de dados por domínio. Administradores e usuários também podem aplicar restrições quanto à capacidade de gravar no sistema de arquivos.

Suponha que você publique um conteúdo de arquivo SWF a ser reproduzido como arquivos locais (sejam arquivos EXE ou arquivos SWF localmente instalados) e precise acessar um objeto compartilhado específico a partir de mais de um arquivo SWF local. Nessa situação, lembre-se de que, para arquivos locais, duas localizações diferentes podem ser usadas para armazenar objetos compartilhados. O domínio usado depende das permissões de segurança concedidas ao arquivo que criou o objeto compartilhado. Arquivos locais podem ter três níveis diferentes de permissões:

1. Acesso ao sistema de arquivos local apenas.
2. Acesso à rede apenas.
3. Acesso à rede e ao sistema de arquivos local.

Arquivos locais com acesso ao sistema de arquivos local (nível 1 ou 3) armazenam seus objetos compartilhados em um local. Arquivos locais sem acesso ao sistema de arquivos local (nível 2) armazenam seus objetos compartilhados em outro local.

Você pode impedir o arquivo SWF de usar esse método configurando o parâmetro allowNetworking das marcas object e embed na página HTML com o conteúdo SWF.

Para obter mais informações, consulte o tópico do Centro de desenvolvedores do Flash Player: Security.

Parâmetros

  ~ % & \ ; : " ' , < > ? # 
  

Retorna uma referência a um objeto compartilhado no Flash Media Server que vários clientes podem acessar. Se o objeto compartilhado remoto ainda não existir, esse método criará um.

Para criar um objeto compartilhado remoto, chame getRemote() e, em seguida, connect() para conectar esse objeto ao servidor, como a seguir:

     var nc:NetConnection = new NetConnection();
     nc.connect("rtmp://somedomain.com/applicationName");
     var myRemoteSO:SharedObject = SharedObject.getRemote("mo", nc.uri, false);
     myRemoteSO.connect(nc);
     

Para confirmar se as cópias local e remota do objeto compartilhado estão sincronizadas, forneça e manipule o evento sync. Todos os clientes que quiserem compartilhar esse objeto precisarão transmitir os mesmos valores para os parâmetros name e caminhoRemoto.

Para criar um objeto compartilhado disponível apenas ao cliente atual, use SharedObject.getLocal().

Parâmetros

    ~ % & \ ; :  " ' , > ? ? #

Elementos da API relacionados

Transmite uma mensagem a todos os clientes conectados a um objeto compartilhado remoto, incluindo o cliente que enviou essa mensagem. Para processar e responder à mensagem, crie uma função de retorno de chamada anexada ao objeto compartilhado.

Parâmetros

Indica o servidor no qual o valor de uma propriedade no objeto compartilhado foi alterado. Esse método marca propriedades como dirty; ou seja, alteradas.

Chame SharedObject.setProperty() para criar propriedades para um objeto compartilhado.

O método SharedObject.setProperty() implementa setDirty(). Na maioria dos casos, por exemplo, quando o valor de uma propriedade é um tipo primitivo, como String ou Number, você pode chamar setProperty() em vez de setDirty(). Entretanto, quando o valor de uma propriedade for um objeto que contém suas próprias propriedades, chame setDirty() para indicar quando um valor dentro do objeto tiver sido alterado.

Parâmetros

Elementos da API relacionados

Atualiza o valor de uma propriedade em um objeto compartilhado e indica ao servidor que o valor dessa propriedade foi alterado. O método setProperty() marca explicitamente as propriedades como alteradas, ou "dirty".

Para obter mais informações sobre objetos compartilhados remotos, consulte a documentação do Flash Media Server.

Observação: O método SharedObject.setProperty()implementa o método setDirty(). Na maioria dos casos, por exemplo, quando o valor de uma propriedade é um tipo primitivo, como String ou Number, você pode usar setProperty() em vez de setDirty(). Entretanto, quando o valor de uma propriedade for um objeto que contém suas próprias propriedades, use setDirty() para indicar quando um valor dentro do objeto tiver sido alterado. Em geral, convém chamar setProperty() em vez de setDirty(), uma vez que setProperty() apenas atualizará um valor de propriedade quando esse valor tiver sido alterado, enquanto setDirty() força a sincronização em todos os clientes inscritos.

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 quando uma ocorrência de SharedObject está relatando seu status ou uma condição de erro. O evento netStatus contém uma propriedade info, que é um objeto de informações contendo informações específicas sobre esse evento; por exemplo, se uma tentativa de conexão foi bem-sucedida ou se o objeto compartilhado foi gravado com êxito no disco local.

Esse evento tem as seguintes propriedades:

Elementos da API relacionados

Despachado quando um objeto compartilhado remoto foi atualizado pelo servidor.

Esse evento tem as seguintes propriedades:

Elementos da API relacionados