URLStream  - AS3

Zwraca liczbę bajtów, które można odczytać z bufora wejściowego. Kod użytkownika musi wywoływać właściwość bytesAvailable, aby upewnić się, że dostępna jest wystarczająca ilość danych, zanim nastąpi próba ich odczytania za pomocą jednej z metod read.

Wskazuje, czy ten obiekt URLStream jest aktualnie podłączony. Wywołanie do tej właściwości zwraca wartość true, jeśli obiekt URLStream jest w danym momencie połączony, w innym przypadku wartość false.

Przedstawia porządek bajtów danych. Możliwe wartości to: Endian.BIG_ENDIAN lub Endian.LITTLE_ENDIAN.

Wartością domyślną jest Endian.BIG_ENDIAN.

Powiązane elementy interfejsu API

Zapewnia kontrolę nad wersją formatu AMF (Action Message Format) stosowaną przy zapisywaniu i odczycie obiektu.

Powiązane elementy interfejsu API

Natychmiast zamyka strumień i anuluje operację pobierania. Żadne dane nie zostaną odczytane ze strumienia po wywołaniu metody close().

Rozpoczyna pobieranie adresu URL określonego w parametrze request.

Uwaga: jeśli ładowany plik zawiera znaki, które nie są znakami ASCII (co zdarza się w wielu nieangielskich językach), zalecane jest zapisanie pliku z kodowaniem w systemie UTF-8 lub UTF-16 jako przeciwnego w stosunku do formatu niebędącego formatem Unicode np. ASCII.

Jeśli operacja pobierania natychmiast zakończy się niepowodzeniem, zgłoszony zostanie wyjątek IOError lub SecurityError (wraz z błędem zabezpieczeń pliku lokalnego) opisujący niepowodzenie. W innym wypadku wywołane zostanie zdarzenieopen, jeśli pobieranie adresu URL rozpocznie się pomyślnie lub zdarzenie error, jeśli pojawi się błąd.

Domyślnie wywołujący plik SWF oraz ładowany URL muszą być w tej samej domenie. Na przykład plik SWF na stronie www.adobe.com może ładować dane jedynie ze źródeł, które również znajdują się na stronie www.adobe.com. Aby ładować dane z różnych domen, należy umieścić plik reguł URL na serwerze przechowującym dane.

W programie Flash Player nie można nawiązywać połączeń z portami, które są zazwyczaj zastrzeżone. Pełną listę zablokowanych portów zawiera sekcja „Ograniczanie sieciowych interfejsów API” w publikacji ActionScript 3.0 — Podręcznik programistów.

W programie Flash Player istnieje możliwość zapobieżenia użyciu tej metody przez plik SWF; należy w tym celu ustawić parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej treść SWF.

W programie Flash Player 10 i późniejszych wersjach oraz w środowisku AIR 1.5 i późniejszych wersjach, jeśli użyty zostanie wieloczęściowy nagłówek Content-Type (np. "multipart/form-data"), w którym przesyłane są pliki (wskazywane przez parametr "filename" w nagłówku "content-disposition" w treści operacji POST), wówczas operacja POST podlega regułom zabezpieczeń zastosowanym do wysyłania plików:

• Operację POST należy wykonać w odpowiedzi na działanie zainicjowane przez użytkownika, np. kliknięcie myszy lub naciśnięcie klawisza.
• Jeśli operacja POST jest operacją międzydomenową (cel operacji POST nie znajduje się na tym samym serwerze, co plik SWF, który wysyła żądanie POST), docelowy serwer musi dostarczyć plik reguł URL, który zezwoli na międzydomenowy dostęp.

Dla dowolnego wieloczęściowego nagłówka Content-Type również składnia musi być poprawna (zgodnie ze standardami RFC2046). Jeśli składnia okaże się niepoprawna, operacja POST będzie podlegać regułom zabezpieczeń stosowanym do wysyłania plików.

Te reguły mają także zastosowanie do treści AIR w nieaplikacyjnych obszarach izolowanych zabezpieczeń. Jednak w aplikacji Adobe AIR treść obszaru izolowanego aplikacji (zawartość instalowana razem z aplikacją AIR) nie podlega ograniczeniom wynikającym z tych reguł zabezpieczeń.

Więcej informacji na temat zabezpieczeń zawiera odpowiedni temat w witrynie Flash Player Developer Center: Bezpieczeństwo.

W środowisku AIR obiekt URLRequest może być zarejestrowany jako odbiorca zdarzeń statusu httpResponse. W przeciwieństwie do zdarzenia httpStatus, zdarzenie httpResponseStatus jest dostarczane przed danymi odpowiedzi. Ponadto zdarzenia httpResponseStatus zawiera wartości właściwości responseHeaders i responseURL (niezdefiniowane w przypadku zdarzenia httpStatus). Należy zauważyć, że ewentualne zdarzenie httpResponseStatus zostanie wysłane przed (i oprócz) wszelkich zdarzeń ukończenia lubbłędu.

Jeśli faktycznie istnieje detektor zdarzeń httpResponseStatus, treść komunikatu odpowiedzi jest zawsze wysyłana, a odpowiedzi z kodem statusu HTTP zawsze powodują wywołanie zdarzenia complete. I to niezależnie od tego, czy kod statusu HTTP w odpowiedzi wskazuje na powodzenie, czy na błąd.

W środowisku AIR, jeśli nie istnieje detektor zdarzeń httpResponseStatus, zachowanie zależy od wersji pliku SWF:

• W przypadku treści SWF 9 treść komunikatu odpowiedzi HTTP jest wysyłana tylko wtedy, gdy kod statusu HTTP w odpowiedzi wskazuje na powodzenie. W przeciwnym razie (jeśli wystąpił błąd), treść nie jest wysyłana, a obiekt URLRequest wywołuje zdarzenie IOError.
• W przypadku treści SWF 10 treść komunikatu odpowiedzi HTTP jest zawsze wysyłana. Jeśli wystąpi błąd, obiekt URLRequest wywołuje zdarzenie IOError.

Parametry

Czyta ze strumienia wartość typu Boolean. Po odczytaniu jednego bajtu metoda zwraca true, jeśli bajt jest wartością niezerową; w przeciwnym wypadku false.

Czyta ze strumienia oznakowany bajt.

Zwracana wartość jest z przedziału od -128 do 127.

Czyta ze strumienia liczbę bajtów określoną przez parametr length . Bajty zczytywane są do obiektu ByteArray określonego w parametrze bytes, rozpoczynając od bajtów określonych w parametrze offset obiektu ByteArray.

Parametry

Czyta ze strumienia liczbę zmiennoprzecinkową o podwójnej precyzji (IEEE 754).

Czyta ze strumienia liczbę zmiennoprzecinkową o pojedynczej precyzji (IEEE 754).

Czyta ze strumienia 32-bitową liczbę całkowitą ze znakiem.

Zwracana wartość jest z przedziału od -2147483648 do 2147483647.

Czyta ze strumienia bajtów wielobajtowy ciąg o określonej długości, używając określonego zestawu znaków.

Parametry

Czyta z gniazda obiekt zakodowany w formacie AMF (Action Message Format).

Powiązane elementy interfejsu API

Czyta ze strumienia 16-bitową liczbę całkowitą ze znakiem.

Zwracana wartość jest z przedziału od -32768 do 32767.

Czyta ze strumienia nieoznakowany bajt.

Zwracana wartość jest z przedziału od 0 do 255.

Czyta ze strumienia 32-bitową liczbę całkowitą bez znaku.

Zwracana wartość jest z przedziału od 0 do 4294967295.

Czyta ze strumienia 16-bitową liczbę całkowitą bez znaku.

Zwracana wartość jest z przedziału od 0 do 65535.

Czyta ze strumienia ciąg znaków UTF-8. Zakłada się, że ciąg znaków jest poprzedzony prefiksem w postaci liczby typu short bez znaku, która określa długość ciągu w bajtach.

Czyta ze strumienia sekwencję bajtów UTF-8 o długości length i zwraca ciąg znaków.

Parametry

Wywoływane po pomyślnym wczytaniu danych.

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

Wywoływane, jeśli wywołanie metody URLStream.load() skutkuje próbą uzyskania dostępu do danych za pomocą protokołu HTTP i aplikacja Adobe AIR ma możliwość wykrycia i zwrócenia kodu stanu żądania.

Jeśli obiekt URLStream rejestruje zdarzenie httpStatusEvent, odpowiedzi na błędy są specjalnie dostarczane jako treść. Dlatego zamiast wywołania zdarzenia ioError, obiekt URLStream wywoła zdarzenia progress i complete w momencie załadowania danych błędu do obiektu URLStream.

Stała HTTPStatusEvent.HTTP_RESPONSE_STATUS definiuje wartość właściwości type obiektu zdarzenia httpResponseStatus.

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

Powiązane elementy interfejsu API

Wywoływane, jeśli wywołanie metody URLStream.load() skutkuje próbą uzyskania dostępu do danych za pomocą protokołu HTTP i program Flash Player lub środowisko Adobe AIR ma możliwość wykrycia i zwrócenia kodu stanu żądania. (Niektóre środowiska przeglądarek mogą nie być w stanie zapewnić tych informacji). Należy zauważyć, że ewentualne zdarzenie httpStatus zostanie wysłane przed (i oprócz) jakichkolwiek zdarzeń complete lub error.

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

Powiązane elementy interfejsu API

Wywoływane, gdy wystąpi błąd wejścia lub wyjścia uniemożliwiający wczytywanie danych.

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

Powiązane elementy interfejsu API

Wywoływane po rozpoczęciu ładowania.

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

Powiązane elementy interfejsu API

Wywoływane w trakcie stopniowego ładowania danych. Odebrane dane można odczytać natychmiast korzystając z metod klasy URLStream.

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

Powiązane elementy interfejsu API

Wywoływane, jeśli wywołanie metody URLStream.load() skutkuje próbą pobrania danych z serwera na zewnątrz obszaru izolowanego.

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

Powiązane elementy interfejsu API

Aby uruchomić przykład, należy umieścić plik o nazwie URLStreamExample.swf w tym samym katalogu, co plik SWF.

package {
    import flash.display.Sprite;
    import flash.errors.*;
    import flash.events.*;
    import flash.net.URLRequest;
    import flash.net.URLStream;

    public class URLStreamExample extends Sprite {
        private static const ZLIB_CODE:String = "CWS";
        private var stream:URLStream;

        public function URLStreamExample() {
            stream = new URLStream();
            var request:URLRequest = new URLRequest("URLStreamExample.swf");
            configureListeners(stream);
            try {
                stream.load(request);
            } catch (error:Error) {
                trace("Unable to load requested URL.");
            }
        }

        private function configureListeners(dispatcher:EventDispatcher):void {
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
        }

        private function parseHeader():void {
            trace("parseHeader");
            trace("isCompressed: " + isCompressed());
            trace("version: " + stream.readByte());
        }

        private function isCompressed():Boolean {
            return (stream.readUTFBytes(3) == ZLIB_CODE);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
            parseHeader();
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:Event):void {
            trace("progressHandler: " + event);
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }

        private function httpStatusHandler(event:HTTPStatusEvent):void {
            trace("httpStatusHandler: " + event);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }
    }
}