SharedObject  - AS3

Wskazuje obiekt, w ramach którego są uaktywniane metody wywołań zwrotnych. Obiektem domyślnym jest this. Właściwość client można ustawić na inny obiekt i metody wywołania zwrotnego będą wywoływane na rzecz tego innego obiektu.

Kolekcja atrybutów przypisanych do właściwości data; atrybuty te mogą być udostępniane i przechowywane. Każdy atrybut może być obiektem ActionScript lub JavaScript dowolnego typu — Array, Number, Boolean, ByteArray, XML itd. Przykład: poniższe wiersze przypisują wartości do różnych aspektów obiektu udostępnionego:

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

Wszystkie atrybuty właściwości data obiektu udostępnionego są zapisywane, pod warunkiem że obiekt jest trwały, a obiekt udostępniony zawiera następujące informacje:

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

Uwaga: Nie należy przypisywać wartości bezpośrednio do właściwości data obiektu udostępnionego, np. so.data = someValue; program Flash Player ignoruje takie przypisania.

Aby usuwać atrybuty lokalnych obiektów udostępnionych, należy użyć kodu takiego jak delete so.data.attributeName; ustawienie dla atrybutu wartości null lub undefined dla lokalnego obiektu udostępnionego nie powoduje usunięcia atrybutu.

W celu utworzenia wartości prywatnych dla obiektu udostępnionego — wartości, które będą dostępne tylko dla instancji klienta podczas korzystania z obiektu i nie będą zapisywane z obiektem po jego zamknięciu — należy utworzyć właściwości zapisywane z nazwą inną niż data, co przedstawia poniższy przykład:

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

Obiekt udostępniony zawiera następujące dane:

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

W przypadku zdalnych obiektów udostępnionych, jakie są używane z serwerem, wszystkie atrybuty właściwości data są dostępne dla wszystkich klientów podłączonych do obiektu udostępnionego, a wszystkie atrybuty są zapisywane, jeśli obiekt jest trwały. Jeśli jeden klient zmieni wartość atrybutu, wszyscy klienci zobaczą nową wartość.

Powiązane elementy interfejsu API

Domyślne kodowanie (wersja AMF) wszystkich obiektów udostępnianych utworzonych w pliku SWF. Gdy lokalne obiekty udostępnione są zapisywane na dysk, właściwość SharedObject.defaultObjectEncoding wskazuje wersję formatu AMF (Action Message Format), jaka powinna być używana: format ActionScript 3.0 (AMF3) lub format ActionScript 1.0 albo 2.0 (AMF0).

Więcej informacji o kodowaniu obiektu, łącznie z opisem różnic między kodowaniem w obiektach lokalnych i zdalnych, zawiera opis właściwości objectEncoding.

Wartość domyślna SharedObject.defaultObjectEncoding powoduje użycie formatu ActionScript 3.0, AMF3. Jeśli wymagane jest zapisanie lokalnego obiektu udostępnionego, który będzie odczytywany przez pliki SWF formatu ActionScript 2.0 lub 1.0, ustaw właściwość SharedObject.defaultObjectEncoding w taki sposób, aby używany był format ActionScript 1.0 lub ActionScript 2.0, flash.net.ObjectEncoding.AMF0 — na początku pliku przed utworzeniem jakichkolwiek lokalnych obiektów udostępnionych. Wszystkie lokalne obiektu udostępnione utworzone potem będą korzystały z kodowania AMF0 i będą mogły wchodzić w interakcje ze starszą zawartością. Nie można zmienić wartości objectEncoding istniejących lokalnych obiektów udostępnionych poprzez ustawienie SharedObject.defaultObjectEncoding po utworzeniu lokalnych obiektów udostępnionych.

Aby ustawiać kodowanie dla poszczególnych obiektów, a nie dla wszystkich obiektów udostępnionych utworzonych przez ten plik SWF, należy ustawić właściwość objectEncoding lokalnego obiektu udostępnionego.

Powiązane elementy interfejsu API

Określa częstotliwość (na sekundę) wysyłania do serwera zmian obiektu udostępnionego, jakie wprowadza klient.

Za pomocą tej metody można kontrolować natężenie ruchu między klientem i serwerem. Przykład: jeśli połączenie między klientem i serwerem jest powolne, możliwe jest ustawienie fps na niską wartość. I przeciwnie: jeśli klient jest podłączony do aplikacji obsługującej wielu użytkowników, w której limity czasu mają znaczenie, dla fps można ustawić wyższą wartość.

Ustawienie fps spowoduje wywołanie zdarzenia sync i załadowanie zmian do serwera. Jeśli użytkownik chce zaktualizować serwer ręcznie, należy ustawić fps na 0.

Zmiany nie są wysyłane do serwera do czasu wywołania zdarzenia sync Oznacza to, że jeśli odpowiedzi z serwera są przesyłane wolniej, aktualizacje mogą być wysyłane do serwera z mniejszą częstotliwością niż wartość określona w tej właściwości.

Kodowanie obiektów (wersja AMF) dotyczące tego obiektu udostępnianego. Gdy lokalny obiekt udostępniony jest zapisywany na dysk, właściwość objectEncoding wskazuje wersję formatu AMF (Action Message Format), jaka powinna być używana: format ActionScript 3.0 (AMF3) lub format ActionScript 1.0 albo 2.0 (AMF0).

Kodowanie obiektu jest obsługiwane inaczej w zależności od tego, czy obiekt udostępniony jest lokalny czy zdalny.

• Lokalne obiekty udostępnione. Dla lokalnych obiektów udostępnionych można pobierać lub ustawiać wartość właściwości objectEncoding. Wartość objectEncoding określa formatowanie, jakie jest używane podczas zapisywania tego lokalnego obiektu udostępnionego. Jeśli wymagane jest, aby lokalny obiekt udostępniony był odczytywany przez plik SWF ActionScript 2.0 lub 1.0 SWF, należy ustawić dla właściwości objectEncoding wartość ObjectEncoding.AMF0. Nawet jeśli ustawiono zapisywanie obiektu w kodowaniu AMF3, program Flash Player może odczytywać lokalne obiekty udostępnione w formacie AMF0. Oznacza to, że jeśli używana jest wartość domyślna właściwości — ObjectEncoding.AMF3 — plik SWF może odczytywać udostępnione pliki utworzone przez pliki SWF ActionScript 2.0 lub 1.0.
• Zdalne obiekty udostępnione. Po podłączeniu do serwera zdalny obiekt dziedziczy jego ustawienie objectEncoding ze skojarzonej instancji NetConnection (instancja używana do połączenia ze zdalnym obiektem udostępnionym). Po podłączeniu do serwera zdalny obiekt udostępniony dziedziczy ustawienie defaultObjectEncoding ze skojarzonej instancji NetConnection. Wartości właściwości objectEncoding zdalnego obiektu udostępnionego jest określona przez instancję NetConnection, dlatego ta właściwość jest tylko do odczytu dla zdalnych obiektów udostępnionych.

Powiązane elementy interfejsu API

Określa, czy w usłudze kopii zapasowych w środowisku rozproszonym iOS są wykonywane kopie zapasowe lokalnych obiektów współużytkowanych.

Ustaw wartość true lub false:

• Wartość true zapobiega wykonywaniu kopii zapasowych jakichkolwiek lokalnych obiektów współużytkowanych w usłudze kopii zapasowych w środowisku rozproszonym iOS.
• Wartość false (domyśla) powoduje wykonywanie kopii zapasowych lokalnych obiektów współużytkowanych w usłudze kopii zapasowych w środowisku rozproszonym iOS.

Ta właściwość ma zastosowanie tylko do lokalnych obiektów współużytkowanych i systemu iOS.

Bieżący rozmiar obiektu udostępnianego (w bajtach).

Program Flash oblicza wielkość udostępnionego obiektu przechodząc przez wszystkie jego właściwości data; im więcej właściwości data zawiera obiekt, tym dłużej będzie trwało określanie jego wielkości. Określanie wielkości obiektu może trwać dość długo, dlatego korzystanie z tej metody nie jest wskazany, chyba że jest to konieczne.

import flash.net.SharedObject;

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

W przypadku lokalnych obiektów udostępnionych kasuje wszystkie dane i usuwa obiekt udostępniony z dysku. Odwołanie do obiektu udostępnionego jest nadal aktywne, ale właściwości danych zostały usunięte.

W przypadku zdalnych obiektów udostępnionych używanych z serwerem Flash Media Server metoda clear() powoduje odłączenie obiektu i usunięcie wszystkich danych. Jeśli obiekt udostępniony jest trwały lokalnie, ta metoda powoduje również usunięcie udostępnionego obiektu z dysku. Odniesienie do obiektu udostępnionego jest nadal aktywne, ale właściwości danych zostały usunięte.

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
            }
        }
    }
}

Zamyka połączenie między zdalnym obiektem udostępnionym i serwerem. Jeśli zdalny obiekt udostępniony jest trwały lokalnie, użytkownik może dokonywać zmian na lokalnej kopii obiektu po wywołaniu tej metody. Wszystkie zmiany dokonane na lokalnym obiekcie są wysyłane na serwer w momencie kolejnego połączenia użytkownika ze zdalnym obiektem udostępnionym.

Łączy się ze zdalnym obiektem udostępnionym określonym w obiekcie NetConnection. Tej metody należy użyć po wywołaniu metody getRemote(). Jeśli połączenie zostanie zrealizowane pomyślnie, wywołane zostanie zdarzenie sync.

Przed próbą rozpoczęcia pracy ze zdalnym obiektem udostępnionym należy sprawdzić za pomocą instrukcji try..catch..finally, czy istnieje możliwość wystąpienia błędu. Następnie należy wykryć i obsłużyć zdarzenie sync przed dokonaniem zmian w obiekcie udostępnionym. Wszystkie zmiany dokonane lokalnie — przed wywołaniem zdarzenia sync — mogą zostać utracone.

Metoda connect() wywoływana jest w celu połączenia ze zdalnym obiektem udostępnionym, na przykład:

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

Parametry

Powiązane elementy interfejsu API

Natychmiast zapisuje lokalnie trwały obiekt w pliku lokalnym. Jeśli ta metoda nie zostanie użyta, program Flash Player zapisze do pliku obiekt udostępniony w momencie zakończenia jego sesji — gdy plik SWF został zamknięty po odśmieceniu obiektu udostępnionego ze względu na utratę wszystkich odwołań do niego, lub gdy wywołana zostanie metoda SharedObject.clear() lub SharedObject.close().

Jeśli ta metoda zwróci wartość SharedObjectFlushStatus.PENDING, program Flash Player wyświetli okno dialogowe, w którym powiadomi użytkownika o potrzebie zwiększenia dostępnej ilości miejscana dysku dla obiektu z tej domeny. Aby umożliwić zwiększenie miejsca dla obiektów udostępnianych do zapisu w przyszłości, copozwala uniknąć zwrócenia wartości PENDING, należy przekazać wartość do parametru minDiskSpace. Kiedy program Flash Player spróbuje zapisać plik, wyszuka liczbę bajtów przekazaną w parametrze minDiskSpace, zamiast wyszukiwania dostatecznej ilości miejsca do zapisania obiektu udostępnionego w jego bieżącym rozmiarze.

Na przykład, jeśli oczekuje się przyrostu rozmiaru obiektu do maksimum 500 bajtów, mimo że początkowo może on być dużo mniejszy, należy przekazać do parametru minDiskSpace wartość 500. Jeśli program Flash wygeneruje dla użytkownika komunikat z prośbą o przydzielenie miejsca na dysku dla udostępnionego obiektu, poprosi o 500 bajtów. Gdy użytkownik przydzieli żądaną ilość miejsca, program Flash nie będzie prosił o przydzielenie większej ilości miejsca przy kolejnych próbach kasowania obiektu (pod warunkiem że jego wielkość nie przekracza 500 bajtów).

Gdy użytkownik zareaguje na wyświetlenie okna dialogowego, ta metoda zostanie ponownie wywołana. Zostanie wywołane zdarzenie netStatus z właściwością code o wartości SharedObject.Flush.Success lub SharedObject.Flush.Failed.

Parametry

Powiązane elementy interfejsu API

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
        }
    }
}

Zwraca odwołanie do lokalnie trwałego obiektu udostępnionego, który jest dostępny tylko dla bieżącego klienta. Jeśli obiekt udostępniony nie istnieje w danym momencie, ta metoda utworzy jeden. Jeśli jakiekolwiek wartości przekazane do metody getLocal() są nieprawidłowe, lub jeśli wywołanie zakończy się niepowodzeniem, program Flash Player zgłosi wyjątek.

Następujący kod pokazuje, jak przypisać zwrócone odwołanie obiektu udostępnionego do zmiennej.

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

Uwaga: jeśli użytkownik wybrał, aby nie zezwalano na przechowywanie lokalne w tej domenie, obiekt nie zostanie zapisany lokalnie nawet, jeśli określono wartość parametru localPath. Wyjątkiem od tej reguły jest treść lokalna. Lokalna treść może zawsze zapisać na dysk obiekty udostępnione z pozostałych domen (domen innych niż domena w pasku adresu przeglądarki), nawet jeśli zapisywanie takich obiektów jest niedozwolone.

Aby uniknąć konfliktów nazw, program Flash sprawdza lokalizację pliku SWF tworzącego obiekt udostępniony. Na przykład, jeśli plik SWF na stronie www.myCompany.com/apps/stockwatcher.swf tworzy obiekt udostępniony o nazwie portfolio, ten obiekt nie będzie w konflikcie z innym obiektem o nazwie portfolio, który został utworzony przez plik SWF na stronie www.yourCompany.com/photoshoot.swf, ponieważ oba pliki pochodzą z różnych katalogów.

Mimo że parametr localPath jest parametrem opcjonalnym, należy zastanowić się nad jego użyciem zwłaszcza, jeśli pozostałe pliki SWF wymagają dostępu do obiektu udostępnionego. Jeśli dane obiektu udostępnionego są charakterystyczne dla jednego pliku SWF, który nie będzie przenoszony do innej lokalizacji, wówczas użycie wartości domyślnych jest sensowne. Jeśli pozostałe pliki SWF wymagają dostępu do obiektu udostępnionego, lub jeśli plik SWF tworzący obiekt udostępniony będzie w późniejszym czasie przenoszony, wówczas wartość tego parametru decyduje o dostępności obiektu. Na przykład jeśli utworzony zostanie obiekt udostępniony z parametrem localPath ustawionym na wartość domyślną dla pełnej ścieżki do pliku SWF, wówczas żaden inny plik SWF nie uzyska dostępu do tego obiektu. Jeśli w późniejszym czasie oryginalny plik SWF zostanie przeniesiony do innej lokalizacji, wówczas żaden plik, nawet ten plik SWF, nie będzie miał dostępu do danych przechowywanych w obiekcie udostępnionym.

Aby uniknąć przypadkowego ograniczenia dostępu do obiektu udostępnionego, należy skorzystać z parametru localpath. Najbardziej tolerancyjnym podejściem jest ustawienie parametru localPath na znak / (prawy ukośnik), który czyni obiekt udostępniony dostępnym dla wszystkich plików SWF w domenie; powoduje to jednak wzrost prawdopodobieństwa konfliktu nazw z pozostałymi obiektami udostępnionymi w domenie. Bardziej restrykcyjnym podejściem jest połączenie parametru localPath z nazwami folderów, które znajdują się w pełnej ścieżce do pliku SWF. Na przykład dla obiektu udostępnionego portfolio utworzonego przez plik SWF na stronie www.myCompany.com/apps/stockwatcher.swf, można ustawić parametr localPath jako /, /apps lub /apps/stockwatcher.swf. Należy określić, które podejście zapewni optymalną elastyczność dla aplikacji użytkownika.

Korzystając z tej metody, należy wziąć pod uwagę model zabezpieczeń:

• Nie można uzyskać dostępu do obiektów udostępnionych w innych obszarach izolowanych.
• Użytkownicy mogą ograniczyć dostęp do obiektów udostępnionych za pomocą okna dialogowego Ustawienia Flash Player lub Menedżera ustawień. Domyślnie aplikacja może utworzyć obiekty udostępnione do 100 kB danych na domenę. Administratorzy i użytkownicy mogą także tworzyć ograniczenia możliwości zapisu w systemie plików.

Przypuśćmy, że treść pliku SWF publikowana jest w celu odtworzenia jako pliki lokalne (pliki SWF zainstalowane lokalnie lub pliki EXE), należy wówczas uzyskać dostęp do określonego obiektu udostępnionego z więcej jak jednego lokalnego pliku SWF. W tej sytuacji należy mieć świadomość, że możliwe są dwie różne lokalizacje przechowywania obiektów udostępnionych jako plików lokalnych. Domena, która jest używana, zależy od uprawnień zabezpieczeń nadanych lokalnemu plikowi, który utworzył obiekt udostępniony. Pliki lokalne mogą mieć trzy różne poziomy uprawnień:

1. Dostęp tylko do lokalnego systemu plików.
2. Dostęp tylko do sieci.
3. Dostęp do sieci i lokalnego systemu plików.

Pliki lokalne z dostępem do lokalnego systemu plików (poziom 1 lub 3) przechowują swoje obiekty udostępnione w jednej lokalizacji. Pliki lokalne bez dostępu do lokalnego systemu plików (poziom 2) przechowują swoje obiekty udostępnione w innej lokalizacji.

Istnieje możliwość zablokowania pliku SWF przed korzystaniem z tej metody, ustawiając parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej treść SWF.

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

Parametry

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

Zwraca odwołanie do obiektu udostępnionego serwera Flash Media Server, do którego dostęp może uzyskać wielu klientów. Jeśli zdalny obiekt udostępniony nie istnieje w danym momencie, ta metoda utworzy jeden.

Aby utworzyć zdalny obiekt udostępniony, należy wywołać metodę getRemote() oraz metodę connect() w celu połączenia obiektu udostępnianego z serwera tak, jak przedstawiono poniżej:

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

Aby potwierdzić, że lokalne i zdalne kopie obiektu udostępnionego są zsynchronizowane, należy wykryć i obsłużyć zdarzenie sync. Wszyscy klienci, którzy chcą udostępnić ten obiekt muszą przekazać tę samą wartość dla parametru name i remotePath.

Aby utworzyć obiekt udostępniony wyłącznie bieżącemu klientowi, należy skorzystać z metodySharedObject.getLocal().

Parametry

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

Powiązane elementy interfejsu API

Powoduje emisję komunikatu do wszystkich klientów podłączonych do zdalnego obiektu udostępnionego, łącznie z klientem, który wysłał komunikat. W celu przetworzenia i zareagowania na komunikat należy utworzyć funkcję wywołania zwrotnego dołączoną do obiektu udostępnionego.

Parametry

Wskazuje serwerowi, że wartość właściwości w obiekcie udostępnionym została zmieniona. Ta metoda oznacza właściwość jako dirty, co oznacza zmienione.

Aby utworzyć właściwości dla obiektu udostępnionego, należy wywołać metodę SharedObject.setProperty().

Metoda SharedObject.setProperty() implementuje metodę setDirty(). W większości przypadków — np. gdy wartość właściwości jest typu pierwotnego, takiego jak String lub Number — można wywołać metodę setProperty() zamiast metody setDirty(). Jeśli jednak wartość właściwości jest obiektem, który zawiera własne właściwości, należy wywołać metodę setDirty() w celu wskazania czasu zmiany wartości w obiekcie.

Parametry

Powiązane elementy interfejsu API

Aktualizuje wartość właściwości w obiekcie udostępnionym i informuje serwer o tym, że wartość właściwości została zmieniona. Metoda setProperty() w sposób jawny oznacza właściwości jako zmienione (dirty).

Więcej informacji o zdalnych obiektach udostępnionych zawiera dokumentacja serwera Flash Media Server.

Uwaga: Metoda SharedObject.setProperty() implementuje metodę setDirty(). W większości przypadków — np. gdy wartość właściwości jest typu pierwotnego, takiego jak String lub Number — można użyć metody setProperty() zamiast metody setDirty(). Jeśli jednak wartość właściwości jest obiektem, który zawiera własne właściwości, należy użyć metody setDirty() w celu wskazania czasu zmiany wartości w obiekcie. Lepszą metodą postępowania jest wywoływanie metody setProperty() zamiast setDirty(), ponieważ metoda setProperty() aktualizuje wartość właściwości tylko wówczas, gdy wartość została zmieniona, natomiast setDirty() wymusza synchronizację wszystkich klientów subskrybujących.

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, gdy obiekt SharedObject zgłasza swój stan lub warunek błędu. Zdarzenie netStatus zawiera właściwość info, która jest obiektem informacji zawierającym określone informacje dotyczące zdarzenia np. czy próba połączenia zakończyła się powodzeniem lub czy obiekt udostępniony został pomyślnie zapisany na dysku lokalnym.

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

Powiązane elementy interfejsu API

Wywoływane, gdy zdalny obiekt udostępniony został zaktualizowany przez serwer.

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

Powiązane elementy interfejsu API