ApplicationUpdaterUI  - AS3

Położenie pliku konfiguracyjnego, w którym określone są wartości właściwości delay i updateURL. Plik zawiera także ustawienia decydujące o tym, czy aplikacja wyświetla różne okna dialogowe potwierdzeń w procesie aktualizacji. Jeśli ta właściwość wskazuje na nieistniejący plik, wywołanie metody initialize() spowoduje wygenerowanie wyjątku Error.

Oto przykładowy plik konfiguracyjny:

 <?xml version="1.0" encoding="utf-8"?> 
         <configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0" >
           <url>app:/server/update.xml</url>
           <delay>1</delay>
           <defaultUI>
              <dialog name="checkForUpdate" visible="true" />
               <dialog name="downloadUpdate" visible="false" />
               <dialog name="downloadProgress" visible="true" />
               <dialog name="installUpdate" visible="true" />    
           </defaultUI>
        </configuration>

Zamiast ładować plik konfiguracyjny, można za pomocą kodu ActionScript przypisać wartości następującym właściwościom obiektu ApplicationUpdaterUI: delay, isCheckForUpdateVisible, isDownloadProgressVisible, isDownloadUpdateVisible, isFileUpdateVisible, isInstallUpdateVisible oraz updateURL.

Powiązane elementy interfejsu API

Bieżąca wersja aplikacji. Wartość tej właściwości jest przypisywana podczas wywołania metody initialize(). Przypisana wartość jest równa wersji określonej w pliku deskryptora aplikacji.

Odstęp czasu (w dniach) między sprawdzeniami dostępności nowych aktualizacji.

Wartość 0 (domyślna) oznacza, że licznik czasu nie jest aktywny, a zatem dostępność aktualizacji nie jest regularnie sprawdzana. Opóźnienie można określić za pośrednictwem tej właściwości lub w pliku konfiguracyjnym. Gdy wartość jest określona na oba sposoby, przyjmowana jest wartość przypisana właściwości.

Wartością domyślną jest 0.

Powiązane elementy interfejsu API

Powoduje, że okna Sprawdzanie dostępności aktualizacji, Brak aktualizacji i Błąd aktualizacji są widoczne. Gdy ta właściwość ma wartość true, obiekt Updater wyświetla powyższe okna dialogowe w toku aktualizacji. To samo ustawienie można określić w pliku konfiguracyjnym aktualizacji. Wartość określona za pośrednictwem tej właściwości przesłania ustawienie określone w pliku konfiguracyjnym.

Powoduje, że okno Pobieranie aktualizacji jest widoczne. Gdy ta właściwość ma wartość true, obiekt Updater wyświetla powyższe okno dialogowe w toku aktualizacji. To samo ustawienie można określić w pliku konfiguracyjnym aktualizacji. Wartość określona za pośrednictwem tej właściwości przesłania ustawienie określone w pliku konfiguracyjnym.

Powoduje, że okno Pobieranie aktualizacji jest widoczne. Gdy ta właściwość ma wartość true, obiekt Updater wyświetla powyższe okna dialogowe w toku aktualizacji. To samo ustawienie można określić w pliku konfiguracyjnym aktualizacji. Wartość określona za pośrednictwem tej właściwości przesłania ustawienie określone w pliku konfiguracyjnym.

Powoduje, że okna dialogowe Plik - aktualizacja, Plik - brak aktualizacji i Błąd pliku są widoczne. Gdy ta właściwość ma wartość true, obiekt Updater wyświetla powyższe okna dialogowe w toku aktualizacji. To samo ustawienie można określić w pliku konfiguracyjnym aktualizacji. Wartość określona za pośrednictwem tej właściwości przesłania ustawienie określone w pliku konfiguracyjnym.

Określa, czy jest to pierwsze uruchomienie po pomyślnej aktualizacji (true), czy nie (false). Obiekt Updater ustawia tę wartość podczas wywołania metody initialize(). Program powinien sprawdzać, czy właściwość isFirstRun jest ustawiona na true, jeśli istnieje potrzeba migracji danych z jednej wersji do drugiej.

Powiązane elementy interfejsu API

Powoduje, że okno dialogowe Instalowanie aktualizacji jest widoczne. Gdy ta właściwość ma wartość true, obiekt Updater wyświetla powyższe okno dialogowe w toku aktualizacji. To samo ustawienie można określić w pliku konfiguracyjnym aktualizacji. Wartość określona za pośrednictwem tej właściwości przesłania ustawienie określone w pliku konfiguracyjnym.

Funkcja, której obiekt Updater powinien używać do porównywania wersji. Domyślnie architektura aktualizacji porównuje wersje w celu wykrycia, czy wersja z witryny zdalnej jest nowsza od zainstalowanej wersji aplikacji. Jednak niekiedy domyślny sposób porównywania nie jest zgodny z systemem oznaczania wersji przyjętym przez programistę. Ta właściwość umożliwia określenie nowej funkcji realizującej porównanie.

Domyślna funkcja porównująca przyjmuje numery wersji w postaci x.y.z, gdzie x, y, i z mogą zawierać litery i cyfry. Domyślna funkcja porównująca rozpoznaje pewne sytuacje szczególne. Jeśli funkcja testująca znajdzie w ciągu wersji ciąg znaków "alpha", "beta", lub "rc", to obowiązuje zasada alpha < beta < rc.

appUpdate.isNewerVersionFunction = customFn; 

function customFn (currentVersion:String, updateVersion:String):Boolean 
{
    return updateVersion > currentVersion;
}

Powoduje, że okno dialogowe Nieoczekiwany błąd jest widoczne. Gdy ta właściwość ma wartość true, obiekt ApplicationUpdater wyświetla powyższe okno dialogowe w toku instalacji. To samo ustawienie można określić w pliku konfiguracyjnym aktualizacji. Wartość określona za pośrednictwem tej właściwości przesłania ustawienie określone w pliku konfiguracyjnym.

Właściwość typu Boolean, która ma wartość true, jeśli proces aktualizacji jest uruchomiony, a wartość false w przeciwnym wypadku.

Tablica definiująca łańcuch ustawień narodowych stosowany w interfejsie użytkownika. Zazwyczaj z właściwości tej korzystają tylko programiści posługujący się językiem JavaScript (HTML).

W środowisku Flex do obsługi łańcucha ustawień narodowych można używać menedżera zasobów.

Domyślnie w aplikacjach opartych na języku HTML języki są podzielone na grupę języków wymienionych w tablicy Capabilities.languages i grupę dziesięciu języków obsługiwanych przez interfejs użytkownika. Jeśli nie zostanie znaleziony zgodny język, w interfejsie użytkownika stosowany jest język angielski.

W tym przykładzie, napisanym w języku JavaScript, zastosowano architekturę lokalizacji HTML środowiska AIR, wchodzącą w skład pakietu SDK środowiska AIR. Aplikacja sortuje języki, porównując języki dostępne z listą wszystkich języków, a następnie wskazuje angielski jako domyślny język obowiązujący w razie nieznalezienia języka lokalnego:

 appUpdater.addResources("ro_RO", {titleCheck: "Titlu", msgCheck: "Mesaj", btnCheck: "Buton"});
        appUpdater.addResources("hu", {titleCheck: "Cím", msgCheck: "Üzenet"}); 
        var languages = ["ro", "hu"];
        languages = languages.concat(air.Capabilities.languages);
        var sortedLanguages = air.Localizer.sortLanguagesByPreference(languages, air.Capabilities.language, "en-US");  
        sortedLanguages.push("en-US");
        appUpdater.localeChain = sortedLanguages;

Powiązane elementy interfejsu API

Poprzednie położenie katalogu magazynu aplikacji, jeśli zmieniło się po aktualizacji. Położenie katalogu magazynu aplikacji zmienia się po uaktualnieniu, któremu towarzyszy migracja certyfikatu. Jeśli nie ma miejsca migracja certyfikatu, katalog magazynu aplikacji nie ulega zmianie podczas aktualizacji aplikacji. Wówczas ta właściwość przyjmuje wartość null. Wartość tej właściwości jest przypisywana podczas wywołania metody initialize().

Programista może podpisać nową wersję aplikacji AIR nowym certyfikatem, korzystając z opcji -migrate podczas tworzenia pakietu z plikiem AIR za pomocą programu ADT. Jeśli do podpisania nowej wersji aplikacji AIR użyty został nowy certyfikat, katalog magazynu lokalnego aplikacji zmieni się, gdy użytkownik zainstaluje nową wersję. Ta właściwość umożliwia przeniesienie danych ze starego katalogu magazynu aplikacji do nowego katalogu magazynu aplikacji (File.applicationStorageDirectory). Więcej informacji zawiera sekcja „Podpisywanie pliku AIR w celu zmiany certyfikatu aplikacji” w rozdziale „Tworzenie aplikacji AIR za pomocą narzędzi wiersza poleceń” podręcznika programowania w środowisku Adobe AIR.

Poprzednia wersja aplikacji. Wartość tej właściwości jest przypisywana podczas wywołania metody initialize(). Zwraca numer poprzedniej wersji aplikacji przed uaktualnieniem (wartość przypisana tylko wtedy, gdy właściwość isfirstRun jest równa true); w przeciwnym razie przyjmuje wartość null.

Treść pliku deskryptora aktualizacji pobranego spod adresu URL aktualizacji. Ta właściwość ma wartość różną od null po wywołaniu przez obiekt Updater zdarzenia updateStatus.

Położenie pliku deskryptora aktualizacji. Dozwolone jest każde położenie, jakiego można użyć w ścieżce URLRequest. Jest to jedyne ustawienie obowiązkowe wymagane przez obiekt Updater. Adres URL aktualizacji można określić albo za pośrednictwem tej właściwości, albo w pliku konfiguracyjnym. Gdy wartość jest określona na oba sposoby, obiekt Updater przyjmuje wartość przypisaną tej właściwości.

Powiązane elementy interfejsu API

Określa, czy istniała aktualizacja odłożona w czasie, nawet jeśli jej instalacja nie powiodła się (true); false w przeciwnym wypadku. Obiekt Updater przypisuje wartość tej właściwości podczas wywołania metody initialize(). Właściwości wasPendingUpdate i isFirstRun umożliwiają sprawdzenie, czy instalacja aktualizacji nie powiodła się (wówczas wasPendingUpdate przyjmuje wartość true, a isFirstRun przyjmuje wartość false).

Powiązane elementy interfejsu API

Funkcja konstruktora.

Dynamicznie dodaje nowy pakunek zasobów dla określonego języka. Programiści korzystający z języka JavaScript stosują tę metodę w celu dynamicznego dodawania nowych języków dla okien dialogowych wyświetlanych przez interfejs użytkownika aktualizacji aplikacji. (Programiści korzystający ze środowiska Flex mogą bezpośrednio dodać nowy język do pakunku zasobów „ApplicationUpdaterDialogs”).

Parametry

Powiązane elementy interfejsu API

Anuluje proces aktualizacji. Wywołanie tej metody anuluje wszystkie oczekujące operacje pobierania, usuwa wszystkie nie w pełni pobrane pliki i ponownie uruchamia zegar odliczający interwał między sprawdzeniami dostępności aktualizacji.

Proces aktualizacji można anulować w dowolnym momencie, o ile tylko maszyna stanu nie jest w stanie "uninitialized" ani "initializing". Metoda nie wykonuje żadnych czynności, jeśli zostanie wywołana w stanie "uninitialized" lub "initializing".

Rozpoczyna proces aktualizacji. Wywołanie tej metody nie powoduje zatrzymania licznika czasu opóźnienia między sprawdzaniem dostępności aktualizacji; metoda wykrywa jednak uruchomiony proces aktualizacji i pomija bieżącą iterację.

Ta metoda jest wykonywana tylko wtedy, gdy bieżący stan to "Ready".

Wywołanie tej metody może spowodować, że obiekt Updater wywoła następujące zdarzenie:

Inicjuje obiekt Updater. Po wywołaniu metoda wykonuje następujące operacje:

1. Inicjuje architekturę aktualizacji i cicho (oraz synchroniczne) instaluje wszelkie oczekujące aktualizacje. Metodę tę należy wywołać w fazie uruchamiania aplikacji, ponieważ może spowodować ponowne jej uruchomienie.

2. Sprawdza, czy istnieje oczekująca (odłożona w czasie) aktualizacja, a jeśli tak, instaluje ją.

3. Jeśli wcześniejsza aktualizacja nie powiodła się, usuwa z pamięci informacje o pliku aktualizacji i o wersji.

4. Jeśli upłynął czas opóźnienia między automatycznym sprawdzaniem dostępności aktualizacji, rozpoczyna aktualizację; w przeciwnym razie uruchamia licznik czasu opóźnienia. Jednak podczas testowania aplikacji za pomocą programu AIR Debug Launcher (ADL) próba zaktualizowania aplikacji spowoduje wygenerowanie wyjątku IllegalOperationError.

Rozpoczyna proces aktualizacji przy użyciu lokalnego pliku AIR.

Wywołanie tej metody nie odnosi skutku, jeśli trwa już proces aktualizacji (w stanie innym niż "Downloaded").

Ta funkcja jest przydatna w aplikacjach, dla których w pliku deskryptora element customUpdateUI jest ustawiony na true.

Podczas testowania aplikacji za pomocą aplikacji ADL (AIR Debug Launcher) wywoływanie tej metody powoduje wygenerowanie wyjątku IllegalOperationError.

Parametry

Wywoływane tuż przed zainstalowaniem aktualizacji, po wywołaniu metody installUpdate(). Niekiedy celowe jest uniemożliwienie instalacji na tym etapie, ponieważ użytkownik mógłby utracić wszystkie wyniki pracy po zakończeniu pracy aplikacji wymuszonym w celu zainstalowania aktualizacji.

Wywołanie metody preventDefault() obiektu zdarzenia powoduje odłożenie instalacji do momentu następnego uruchomienia aplikacji. Po wywołaniu metody preventDefault() nie jest możliwe uruchomienie jakiegokolwiek następnego procesu aktualizacji w tej sesji aplikacji (poprzez wywołanie metody installUpdate() lub po automatycznym okresowym sprawdzeniu).

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

Wywoływane przed rozpoczęciem procesu aktualizacji, tuż zanim obiekt Updater podejmie próbę pobrania pliku deskryptora aktualizacji. Obiekt Updater może wywołać to zdarzenie w wyniku bezpośredniego wywołania metody checkNow() lub po upływie czasu odmierzanego przez licznik opóźnienia między sprawdzaniem dostępności aktualizacji.

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

Wywoływane po ukończeniu pobierania pliku aktualizacji.

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

Wywoływane, jeśli podczas nawiązywania połączenia lub pobierania pliku aktualizacji wystąpi błąd. To zdarzenie jest także wywoływane w wypadku odebrania niepoprawnego statusu HTTP (np. „404 - nie znaleziono pliku”).

Z chwilą wywołania tego zdarzenia automatycznie uruchamiany jest licznik czasu (jeśli opóźnienie jest większe od 0).

Właściwość errorID obiektu DownloadErrorEvent jest liczbą całkowitą definiującą informacje o błędzie (zob. poniższą tabelę). Dodatkowa właściwość subErrorID może zawierać dalsze informacje o błędzie.

Wywoływane po wywołaniu metody downloadUpdate() i nawiązaniu połączenia z serwerem. W przypadku użycia biblioteki ApplicationUpdater często stosowanym rozwiązaniem jest wyświetlanie paska postępu pobierania w procedurze obsługi tego zdarzenia.

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

Wywoływane, gdy wystąpi błąd podczas inicjowania lub podczas procesu aktualizacji (w razie zajścia nieoczekiwanego zdarzenia).

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

Wywoływane, gdy wystąpi błąd podczas weryfikacji pliku przekazanego jako parametr airFile w wywołaniu metody installFromAIRFile().

Wywoływane po tym, jak obiekt Updater pomyślnie zweryfikuje plik w wywołaniu metody installFromAIRFile().

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

Wywoływane po zakończeniu inicjowania.

To zdarzenie ma następujące właściwości przeznaczone tylko do odczytu:

• isFirstRun (Boolean) true, jeśli jest to pierwsze uruchomienie po pomyślnej aktualizacji; false w przeciwnym wypadku.

• previousVersion (String) Poprzednia wersja aplikacji przed uaktualnieniem (wartość przypisywana tylko wtedy, gdy isfirstRun ma wartość true).

• currentVersion (String) Wersja odczytana z pliku deskryptora obecnie zainstalowanej wersji aplikacji.

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

Wywoływane w chwili pobrania pliku aktualizacji.

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

Wywoływane, gdy wystąpi błąd przy próbie pobrania lub przeanalizowania pliku deskryptora aktualizacji.

Gdy obiekt Updater wywoła to zdarzenie, automatycznie uruchamiany jest licznik czasu (jeśli opóźnienie jest ustawione na wartość większą niż 0). Wskazane jest, aby aplikacja ukrywała wszelkie okna dialogowe błędów, gdy obiekt Updater wywoła nowe zdarzenie checkForUpdate.

Wywoływane po tym, jak obiekt Updater pomyślnie pobierze i zinterpretuje plik deskryptora aktualizacji.

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