FileReference  - AS3

Data utworzenia pliku na dysku lokalnym. Jeśli obiekt nie został wypełniony, wywołanie w celu pobrania wartości tej właściwości zwróci wartość null.

Uwaga: Jeśli system operacyjny nie ma właściwości creationDate wartość CreationDate jest równa lastModifiedDate.

Powiązane elementy interfejsu API

Typ kreatora platformy Macintosh dla pliku, z którego można korzystać w wersjach systemu Mac OS wcześniejszych niż Mac OS X. W systemach Windows i Linux ta właściwość ma wartość null. Jeśli obiekt FileReference nie został wypełniony, wywołanie w celu pobrania wartości tej właściwości zwróci wartość null.

Powiązane elementy interfejsu API

Obiekt ByteArray reprezentujący dane z załadowanego pliku po pomyślnym wywołaniu metody load().

Powiązane elementy interfejsu API

Rozszerzenie nazwy pliku.

Rozszerzenie pliku jest częścią jego nazwy poprzedzoną końcową kropką ("."), bez tej kropki. Jeśli brakuje kropki w nazwie pliku rozszerzenie ma wartość null.

Uwaga: Właściwości extension należy używać w celu określania typu pliku; nie należy w tym celu używać właściwości creator lub type. Właściwości creator oraz type należy uważać jako właściwości niezalecane. Mają zastosowanie w starszych wersjach systemów Mac OS.

Data ostatniej modyfikacji pliku na dysku lokalnym. Jeśli obiekt FileReference nie został wypełniony, wywołanie w celu pobrania wartości tej właściwości zwróci wartość null.

Powiązane elementy interfejsu API

Nazwa pliku na dysku lokalnym. Jeśli obiekt FileReference nie został wypełniony (poprawnym wywołaniem metody FileReference.download() lub FileReference.browse()), program Flash Player zgłosi błąd podczas próby pobrania wartości tej właściwości.

Wszystkie właściwości obiektu FileReference są wypełniane przez wywołanie metody browse(). W przeciwieństwie do pozostałych właściwości obiektu FileReference wywołanie metody download() powoduje wypełnienie właściwości name, jeśli wywołane zostanie zdarzenie select.

Powiązane elementy interfejsu API

Sprawdź, czy system otrzymał pozwolenie na dostęp do systemu plików.

Powiązane elementy interfejsu API

Rozmiar pliku na dysku lokalnym (w bajtach).

Uwaga: w początkowych wersjach języka ActionScript 3.0, właściwość size była definiowana jako obiekt uint, który obsługiwał pliki o rozmiarze do około 4 GB. W tej chwili jest zaimplementowana jako obiekt Number w celu umożliwienia obsługi większych plików.

Powiązane elementy interfejsu API

Typ pliku.

W systemach Windows i Linux ta właściwość jest rozszerzeniem pliku. Na platformie Macintosh ta właściwość jest 4-znakowym typem pliku, który używany jest jedynie w wersjach systemu Mac OS wcześniejszych niż Mac OS X. Jeśli obiekt FileReference nie został wypełniony wywołanie w celu pobrania wartości tej właściwości zwróci wartość null.

Dla systemów Windows, Linux oraz Mac OS X, rozszerzenie pliku — sekcja właściwości name, która następuje po ostatnim wystąpieniu znaku kropki (.). — wskazuje na typ pliku.

Powiązane elementy interfejsu API

Tworzy nowy obiekt typu FileReference. Podczas wypełniania obiekt FileReference reprezentuje plik na dysku lokalnym użytkownika.

Powiązane elementy interfejsu API

Wyświetla okno przeglądania plików, w którym użytkownik może wybrać plik do wysłania. Okno dialogowe należy do systemu operacyjnego użytkownika. Użytkownik może wybrać plik z lokalnego komputera lub z innych systemów, na przykład za pomocą ścieżki UNC w systemie Windows.

Uwaga: Klasa File dostępna w środowisku Adobe AIR zawiera metody umożliwiające dostęp do bardziej konkretnie określonych systemowych okien dialogowych wyboru plików. Są to metody: File.browseForDirectory(), File.browseForOpen(), File.browseForOpenMultiple() oraz File.browseForSave().

Po pomyślnym wywołaniu tej metody i wybraniu przez użytkownika pliku, właściwości tego obiektu FileReference są wypełniane właściwościami tego pliku. Każde kolejne wywołanie metody FileReference.browse() powoduje ponowne ustawienie właściwości obiektu FileReference na plik, który użytkownik wybrał w oknie dialogowym. Tylko jedna sesja browse() lub download() może być przetwarzana w tym samym czasie (ponieważ tylko jedno okno dialogowe może być otwarte w danej chwili).

Za pomocą parametru typeFilter można określić, które pliki będą wyświetlane w oknie dialogowym.

W programie Flash Player 10 i Flash Player 9 z aktualizacją 5 metodę można wywołać pomyślnie tylko w odpowiedzi na zdarzenie użytkownika (np. w module obsługi zdarzenia dla zdarzenia kliknięcia myszą lub naciśnięcia klawisza). W przeciwnym wypadku wywołanie metody skutkuje w programie Flash Player zgłoszeniem wyjątku Error.

Należy zauważyć, że ze względu na nową funkcjonalność dodaną do programu Flash Player podczas publikowania do Flash Player 10 jednocześnie może być aktywna tylko jedna z następujących operacji: FileReference.browse(), FileReference.upload(), FileReference.download(), FileReference.load(), FileReference.save(). W przeciwnym wypadku program Flash Player zgłosi błąd wykonania (kod 2174). Aby zatrzymać operację w toku, należy użyć metody FileReference.cancel(). To ograniczenie obowiązuje jedynie w programie Flash Player 10. Ograniczenie jednoczesnego wykonywania wielu operacji nie dotyczy poprzednich wersji programu Flash Player.

W środowisku Adobe AIR okno dialogowe przeglądania w poszukiwaniu pliku nie zawsze jest wyświetlane przed oknami, których właścicielami są inne okna (przed oknami z wartością właściwości owner inną niż null). Aby uniknąć problemów z kolejnością, przed wywołaniem tej metody należy ukryć okna mające właścicieli.

Parametry

Powiązane elementy interfejsu API

Anuluje wszystkie trwające operacje upload lub download tego obiektu FileReference. Wywołanie tej metody nie powoduje wywołania zdarzenia cancel; to zdarzenie wywoływane jest jedynie wtedy, gdy użytkownik anuluje operację odwołując okno dialogowe wysyłania lub pobierania pliku.

Otwiera okno dialogowe, które pozwala użytkownikowi pobrać pliki ze zdalnego serwera. Mimo że program Flash Player nie posiada ograniczeń dotyczących rozmiarów plików do wysyłania i pobierania, odtwarzacz oficjalnie obsługuje wysyłanie i pobieranie plików o wielkości do 100 MB.

W pierwszej kolejności metoda download() otwiera okno dialogowe systemu operacyjnego, w którym należy wprowadzić nazwę pliku i wybrać lokalizację w komputerze lokalnym, w której plik zostanie zapisany. Po wybraniu pliku i potwierdzeniu operacji download (na przykład przez kliknięcie opcji Zapisz) rozpoczyna się pobieranie z serwera zdalnego. Detektory przechwytują zdarzenia w celu wskazania postępu, powodzenia lub błędu pobierania. Aby stwierdzić stan okna dialogowego i operacji download·po wywołaniu metody download(), w kodzie użytkownika muszą być wykrywane takie zdarzenia, jak cancel, open, progress oraz complete.

Funkcji FileReference.upload() oraz FileReference.download() nie można zablokować. Powrót z tych funkcji następuje po wywołaniu, przed zakończeniem przesyłania pliku. Ponadto, jeśli obiekt FileReference znajdzie się poza zasięgiem, jakiekolwiek wysyłanie lub pobieranie, które nie zostało jeszcze zakończone, zostanie anulowane ze względu na opuszczenie zasięgu. Należy upewnić się, że obiekt FileReference pozostaje w zasięgu tak długo, jak długo kontynuowane jest pobieranie lub wysyłanie.

Jeśli pobieranie pliku zakończy się pomyślnie, właściwości obiektu FileReference są wypełniane właściwościami pliku lokalnego. Zdarzenie complete zostanie wywoływane, jeśli pobieranie zakończy się pomyślnie.

Tylko jedna sesja browse() lub download() może być przetwarzana w tym samym czasie (ponieważ tylko jedno okno dialogowe może być otwarte w tym samym czasie).

Ta metoda obsługuje pobieranie wszystkich typów plików, za pośrednictwem protokołu HTTP lub HTTPS.

Nie można połączyć się z portem, który zazwyczaj jest zastrzeżony. Pełną listę zablokowanych portów zawiera sekcja „Ograniczanie sieciowych interfejsów API” w publikacji ActionScript 3.0 — podręcznik dla programistów.

Uwaga: jeśli serwer wymaga uwierzytelnienia użytkownika, tylko pliki SWF uruchomione w przeglądarce — tj. za pomocą wtyczki przeglądarki lub elementu sterującego ActiveX — mogą dostarczyć okno dialogowe w celu zapytania o nazwę i hasło użytkownika dla uwierzytelniania; tylko w przypadku operacji pobierania. W przypadku wysyłania za pomocą wtyczki lub elementu sterującego ActiveX lub w przypadku pobierania i wysyłania za pomocą samodzielnego lub zewnętrznego odtwarzacza, przesyłanie pliku zakończy się niepowodzeniem.

Korzystając z tej metody, należy wziąć pod uwagę następujący model zabezpieczeń programu Flash Player.

• Operacje ładowania są niedozwolone, jeśli wywołujący plik SWF znajduje się w niezaufanym lokalnym obszarze izolowanym.
• Domyślnym zachowaniem pomiędzy obszarami izolowanymi jest odmowa dostępu. Serwis sieci Web może zezwolić na dostęp do zasobu, dodając plik reguł URL.
• Istnieje możliwość zablokowania używania tej metody przez plik SWF. W tym celu należy ustawić parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej zawartość SWF.
• W programie Flash Player 10 i Flash Player 9 z aktualizacją 5 metodę można wywołać pomyślnie tylko w odpowiedzi na zdarzenie użytkownika (np. w module obsługi zdarzenia dla zdarzenia kliknięcia myszą lub naciśnięcia klawisza). W przeciwnym wypadku wywołanie metody skutkuje w programie Flash Player zgłoszeniem wyjątku Error.

Jednak w aplikacji Adobe AIR treść obszaru izolowanego application (treść instalowana razem z aplikacją AIR) nie jest ograniczana przez te reguły zabezpieczeń.

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

Plik pobrany tą metodą jest oznaczany jako pobrany w systemach operacyjnych, w których przewidziano mechanizm takiego oznaczania:

• Windows XP z dodatkiem Service Pack 2 lub późniejszym oraz w systemie Windows Vista
• Mac OS 10.5 i późniejsze wersje

Niektóre systemy operacyjne, takie jak Linux, nie oznaczają pobranych plików.

Należy zauważyć, że ze względu na nową funkcjonalność dodaną do programu Flash Player podczas publikowania do Flash Player 10 jednocześnie może być aktywna tylko jedna z następujących operacji: FileReference.browse(), FileReference.upload(), FileReference.download(), FileReference.load(), FileReference.save(). W przeciwnym wypadku program Flash Player zgłosi błąd wykonania (kod 2174). Aby zatrzymać operację w toku, należy użyć metody FileReference.cancel(). To ograniczenie obowiązuje jedynie w programie Flash Player 10. Ograniczenie jednoczesnego wykonywania wielu operacji nie dotyczy poprzednich wersji programu Flash Player.

W środowisku Adobe AIR okno dialogowe pobierania nie zawsze jest wyświetlane przed oknami, których właścicielami są inne okna (przed oknami z wartością właściwości owner inną niż null). Aby uniknąć problemów z kolejnością, przed wywołaniem tej metody należy ukryć okna mające właścicieli.

Parametry

Powiązane elementy interfejsu API

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;
    import flash.net.FileFilter;

    public class FileReference_download extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_download() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            configureListeners(file);
            file.download(downloadURL, fileName);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
        }

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

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

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

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

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

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

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
        }
    }
}

Rozpoczyna ładowanie pliku lokalnego wybranego przez użytkownika. Mimo że program Flash Player nie nakłada ograniczeń dotyczących rozmiarów plików do wysyłania, pobierania czy zapisywania, odtwarzacz oficjalnie obsługuje pliki o wielkości do 100 MB. W przypadku treści działającej w programie Flash Player przed wywołaniem metody load() należy wywołać metodę FileReference.browse() lub FileReferenceList.browse(). Jednak treść działająca w środowisku AIR w obszarze izolowanym aplikacji może wywołać metodę load() obiektu File bez konieczności wcześniejszego wywoływania metody browse(). (Klasa File w środowisku AIR rozszerza klasę FileReference).

Detektory przechwytują zdarzenia w celu wskazania postępu, powodzenia lub błędu ładowania. Mimo że możliwe jest takie użycie obiektu FileReferenceList, aby użytkownik mógł wybrać wiele plików do załadowania, pliki muszą być ładowane po jednym. Aby załadować pliki jeden po drugim, należy iteracyjnie przejrzeć tablicę FileReferenceList.fileList zawierającą obiekty FileReference.

Środowisko Adobe AIR zawiera także klasę FileStream, która udostępnia więcej opcji odczytu plików.

Funkcji FileReference.upload(), FileReference.download(), FileReference.load() oraz FileReference.save() nie można zablokować. Powrót z tych funkcji następuje po wywołaniu, przed zakończeniem przesyłania pliku. Ponadto, jeśli obiekt FileReference znajdzie się poza zasięgiem, jakiekolwiek transakcja, która nie została jeszcze zakończona, zostanie anulowana ze względu na opuszczenie zasięgu. Należy upewnić się, że obiekt FileReference pozostaje w zasięgu tak długo, jak długo kontynuowane jest pobieranie, wysyłanie lub zapisywanie.

Jeśli ładowanie pliku zakończy się pomyślnie, jego zawartość jest zapisywana jako tablica bajtów we właściwości data obiektu FileReference.

Obowiązują następujące uwarunkowania związane z bezpieczeństwem:

• Operacje ładowania są niedozwolone, jeśli wywołujący plik SWF znajduje się w niezaufanym lokalnym obszarze izolowanym.
• Domyślnym zachowaniem pomiędzy obszarami izolowanymi jest odmowa dostępu. Strona sieci Web może zezwolić na dostęp do zasobu, dodając międzydomenowy plik reguł.
• Istnieje możliwość zapobieżenia użyciu tej metody w pliku; należy w tym celu ustawić parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej treść SWF.

Jednak te uwarunkowania nie mają zastosowania do treści AIR w obszarze izolowanym aplikacji.

Należy zwrócić uwagę, że w przypadku publikacji dla wersji Flash Player 10 lub AIR 1.5 w danej chwili może być aktywna tylko jedna z następujących operacji: FileReference.browse(), FileReference.upload(), FileReference.download(), FileReference.load(), FileReference.save(). W przeciwnym wypadku aplikacja zgłosi błąd wykonania (kod 2174). Aby zatrzymać operację w toku, należy użyć metody FileReference.cancel(). To ograniczenie obowiązuje tylko w programie Flash Player 10 i środowisku AIR 1.5. We wcześniejszych wersjach programu Flash Player i środowiska AIR ograniczenie to nie ma wpływu na równoległe wykonywanie wielu operacji.

W środowisku Adobe AIR okno dialogowe przeglądania w poszukiwaniu pliku nie zawsze jest wyświetlane przed oknami, których właścicielami są inne okna (przed oknami z wartością właściwości owner inną niż null). Aby uniknąć problemów z kolejnością, przed wywołaniem tej metody należy ukryć okna mające właścicieli.

Powiązane elementy interfejsu API

var buttonShape:Shape = new Shape();
buttonShape.graphics.beginFill(0x336699);
buttonShape.graphics.drawCircle(50, 50, 25);
var button = new SimpleButton(buttonShape, buttonShape, buttonShape, buttonShape);
addChild(button);

var fileRef:FileReference= new FileReference();
button.addEventListener(MouseEvent.CLICK, onButtonClick);

function onButtonClick(e:MouseEvent):void {
fileRef.browse([new FileFilter("Images", "*.jpg;*.gif;*.png")]);
fileRef.addEventListener(Event.SELECT, onFileSelected);
}

function onFileSelected(e:Event):void {
fileRef.addEventListener(Event.COMPLETE, onFileLoaded);
fileRef.load();
}

function onFileLoaded(e:Event):void {
var loader:Loader = new Loader();
loader.loadBytes(e.target.data);
addChild(loader);
}

Wysyła żądanie udzielenia pozwolenia na dostęp do systemu plików.

Otwiera okno dialogowe, które umożliwia użytkownikom zapisanie pliku w lokalnym systemie plików. Mimo że program Flash Player nie posiada ograniczeń dotyczących rozmiarów plików do wysyłania, pobierania czy zapisywania, odtwarzacz oficjalnie obsługuje pliki o wielkości do 100 MB.

W pierwszej kolejności metoda save() otwiera okno dialogowe systemu operacyjnego, w którym należy wprowadzić nazwę pliku i wybrać lokalizację w komputerze lokalnym, w której zostanie zapisany plik. Po wybraniu pliku i potwierdzeniu operacji save (na przykład przez kliknięcie opcji Zapisz) rozpocznie się proces zapisywania. Detektory przechwytują zdarzenia w celu wskazania postępu, powodzenia lub błędu operacji save. Aby stwierdzić stan okna dialogowego i operacji save po wywołaniu metody save(), w kodzie użytkownika muszą być wykrywane takie zdarzenia, jak cancel, open, progress oraz complete.

Środowisko Adobe AIR zawiera także klasę FileStream, która udostępnia więcej opcji lokalnego zapisywania plików.

Funkcji FileReference.upload(), FileReference.download(), FileReference.load() oraz FileReference.save() nie można zablokować. Powrót z tych funkcji następuje po wywołaniu, przed zakończeniem przesyłania pliku. Ponadto, jeśli obiekt FileReference znajdzie się poza zasięgiem, jakiekolwiek transakcja, która nie została jeszcze zakończona, zostanie anulowana ze względu na opuszczenie zasięgu. Należy upewnić się, że obiekt FileReference pozostaje w zasięgu tak długo, jak długo kontynuowane jest pobieranie, wysyłanie lub zapisywanie.

Jeśli zapisywanie pliku zakończy się pomyślnie, właściwości obiektu FileReference są wypełniane właściwościami pliku lokalnego. Zdarzenie complete zostanie wywoływane, jeśli zapisywanie zakończy się pomyślnie.

Tylko jedna sesja browse() lub save() może być przetwarzana w tym samym czasie (ponieważ tylko jedno okno dialogowe może być otwarte w tym samym czasie).

W programie Flash Player metodę tę można wywołać pomyślnie tylko w odpowiedzi na zdarzenie użytkownika (np. w podprogramie obsługi zdarzenia kliknięcia myszą lub naciśnięcia klawisza). W przeciwnym wypadku wywołanie metody skutkuje w programie Flash Player zgłoszeniem wyjątku Error. To ograniczenie nie ma zastosowania do treści AIR w obszarze izolowanym aplikacji.

W środowisku Adobe AIR okno dialogowe zapisywania nie zawsze jest wyświetlane przed oknami, których właścicielami są inne okna (przed oknami z wartością właściwości owner inną niż null). Aby uniknąć problemów z kolejnością, przed wywołaniem tej metody należy ukryć okna mające właścicieli.

Parametry

Powiązane elementy interfejsu API

var MyTextField:TextField = new TextField();
var MyButtonField:TextField = new TextField();
var MyFile:FileReference = new FileReference();

MyTextField.border = true;
MyTextField.type = TextFieldType.INPUT;

MyButtonField.background = true;
MyButtonField.backgroundColor = 0x339933;
MyButtonField.x = 150;
MyButtonField.height = 20;
MyButtonField.text = "Click here to save";

addChild(MyTextField);
addChild(MyButtonField);
MyButtonField.addEventListener(MouseEvent.CLICK, clickhandler);

function clickhandler(e:MouseEvent): void {
    MyFile.save(MyTextField.text);
}

Rozpoczyna wysyłanie pliku na serwer zdalny. Mimo że program Flash Player nie posiada ograniczeń dotyczących rozmiarów plików do wysyłania i pobierania, odtwarzacz oficjalnie obsługuje wysyłanie i pobieranie plików o wielkości do 100 MB.Przed wywołaniem tej metody należy wywołać metodę FileReference.browse() lub FileReferenceList.browse().

W przypadku klasy File środowiska Adobe AIR, która rozszerza klasę FileReference, można używać metody upload() do wysyłania dowolnych plików. W przypadku klasy FileReference (używanej w środowisku odtwarzacza Flash Player) użytkownik musi najpierw wybrać plik.

Detektory przechwytują zdarzenia w celu wskazania postępu, powodzenia lub błędu wysyłania. Mimo możliwości skorzystania z obiektu FileReferenceList w celu zezwolenia użytkownikom na wybranie wielu plików do wysyłania, pliki należy wysyłać jeden po drugim; aby to uczynić, należy przejść iteracyjnie przez obiekty FileReference w tablicy FileReferenceList.fileList.

Funkcji FileReference.upload() oraz FileReference.download() nie można zablokować. Powrót z tych funkcji następuje po wywołaniu, przed zakończeniem przesyłania pliku. Ponadto, jeśli obiekt FileReference znajdzie się poza zasięgiem, jakiekolwiek wysyłanie lub pobieranie, które nie zostało jeszcze zakończone, zostanie anulowane ze względu na opuszczenie zasięgu. Należy upewnić się, że obiekt FileReference pozostaje w zasięgu tak długo, jak długo kontynuowane jest pobieranie lub wysyłanie.

Plik jest wysyłany do adresu URL przekazanego w parametrze url. Adres URL musi być skryptem serwera skonfigurowanym w celu akceptowania wysyłania. Program Flash Player wysyła pliki za pomocą metody POST protokołu HTTP. Skrypt serwera obsługujący wysyłanie powinien oczekiwać żądania POST wraz z następującymi elementami:

• Nagłówek Content-Type o wartości multipart/form-data
• Nagłówek Content-Disposition z atrybutem name ustawionym domyślnie na wartość "Filedata" oraz atrybutem filename ustawionym na nazwę oryginalnego pliku
• Binarne treści pliku

Nie można połączyć się z portem, który zazwyczaj jest zastrzeżony. Pełną listę zablokowanych portów zawiera sekcja „Ograniczanie sieciowych interfejsów API” w publikacji ActionScript 3.0 — podręcznik dla programistów.

Przykład żądania POST znajduje się w opisie parametru uploadDataFieldName. Parametry POST lub GET można przesłać metodą upload(); zobacz opis parametru request.

Jeśli parametr testUpload ma wartość true i plik do wysłania jest większy niż w przybliżeniu 10 kB, program Flash Player w systemie Windows najpierw wysyła operację POST z zerową treścią przed wysłaniem rzeczywistego pliku w celu zweryfikowania prawdopodobieństwa pomyślnego przesłania pliku. Porgram Flash Player wysyła następnie kolejną operację POST, która zawiera rzeczywistą treść pliku. Dla plików o rozmiarze poniżej 10 kB program Flash Player wykonuje pojedynczą operację wysyłania metodą POST z rzeczywistą treścią pliku. Na platformie Macintosh program Flash Player nie testuje operacji wysyłania metodą POST.

Uwaga: jeśli serwer wymaga uwierzytelnienia użytkownika, tylko pliki SWF uruchomione w przeglądarce — tj. za pomocą wtyczki przeglądarki lub elementu sterującego ActiveX — mogą dostarczyć okno dialogowe w celu zapytania o nazwę i hasło użytkownika dla uwierzytelniania; tylko w przypadku operacji pobierania. W przypadku wysyłania za pomocą wtyczki lub elementu sterującego ActiveX lub w przypadku pobierania i wysyłania za pomocą samodzielnego lub zewnętrznego odtwarzacza, przesyłanie pliku zakończy się niepowodzeniem.

Korzystając z tej metody, należy wziąć pod uwagę następujący model zabezpieczeń programu Flash Player.

• Operacje ładowania są niedozwolone, jeśli wywołujący plik SWF znajduje się w niezaufanym lokalnym obszarze izolowanym.
• Domyślnym zachowaniem pomiędzy obszarami izolowanymi jest odmowa dostępu. Serwis sieci Web może zezwolić na dostęp do zasobu, dodając plik reguł URL.
• Istnieje możliwość zablokowania używania tej metody przez plik SWF. W tym celu należy ustawić parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej zawartość SWF.

Jednak w aplikacji Adobe AIR zawartość obszaru izolowanego application (zawartość instalowana razem z aplikacją AIR) nie jest ograniczana przez te reguły zabezpieczeń.

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

Należy zauważyć, że ze względu na nową funkcjonalność dodaną do programu Flash Player podczas publikowania do Flash Player 10 jednocześnie może być aktywna tylko jedna z następujących operacji: FileReference.browse(), FileReference.upload(), FileReference.download(), FileReference.load(), FileReference.save(). W przeciwnym wypadku program Flash Player zgłosi błąd wykonania (kod 2174). Aby zatrzymać operację w toku, należy użyć metody FileReference.cancel(). To ograniczenie obowiązuje jedynie w programie Flash Player 10. Ograniczenie jednoczesnego wykonywania wielu operacji nie dotyczy poprzednich wersji programu Flash Player.

Parametry

    Content-Type: multipart/form-data; boundary=AaB03x
    --AaB03x 
    Content-Disposition: form-data; name="Filedata"; filename="example.jpg" 
    Content-Type: application/octet-stream
    ... contents of example.jpg ... 
    --AaB03x-- 
    

Powiązane elementy interfejsu API

Inicjuje wysyłanie pliku pod adres URL bez żadnego kodowania. Podczas, gdy metoda upload() koduje plik w formacie „form-data envelope”, metoda uploadUnencoded() przekazuje treść, w takiej postaci, jaka jest w treści żądania HTTP. Jeśli wysyłane dane mają być zakodowane w formacie zrozumiałym dla serwera odbierającego przed ich wysłaniem, należy skorzystać z metody uploadUnencoded(). W takich sytuacjach zazwyczaj korzysta się z metody uploadeUnencoded() oraz metody HTTP/WebDAV PUT.

Parametry

Powiązane elementy interfejsu API

Wywoływane, gdy użytkownik anuluje wysyłanie lub pobieranie pliku w oknie dialogowym przeglądania plików. Program Flash Player nie wywoła tego zdarzenia, jeśli użytkownik anuluje wysyłanie lub pobieranie w inny sposób (zamykając przeglądarkę lub zatrzymując bieżącą aplikację).

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

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

    public class FileReference_event_cancel extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_event_cancel() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            file.addEventListener(Event.CANCEL, cancelHandler);
            file.download(downloadURL, fileName);
        }
        private function cancelHandler(event:Event):void {
            trace("cancelHandler: " + event);
        }
    }
}

Dysponowana po zakończeniu pobierania lub wtedy, gdy podczas wysyłania danych zostanie wygenerowany kod stanu HTTP 200. W przypadku pobierania pliku to zdarzenie jest wywoływane, gdy program Flash Player lub aplikacja Adobe AIR zakończy pobieranie na dysk całego pliku. W przypadku wysyłania pliku to zdarzenie wywoływane jest po odebraniu przez program Flash Player lub aplikację Adobe AIR kodu stanu HTTP o numerze 200 z serwera odbierającego przesyłane dane.

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

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

    public class FileReference_event_complete extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_event_complete() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            configureListeners(file);
            file.download(downloadURL, fileName);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
        }

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

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

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

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

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

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

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
        }
    }
}

Powiązane elementy interfejsu API

Wywoływane, jeśli wywołanie metody upload() lub uploadUnencoded() 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.

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ływana, gdy wysłanie danych nie powiedzie się i będzie dostępny kod stanu HTTP opisujący błąd. Wywołanie zdarzenia httpStatus poprzedzane jest zdarzeniem ioError.

Zdarzenie httpStatus wywoływane jest jedynie w przypadku niepowodzeń wysyłania. Dla treści uruchamianych w programie Flash Player to zdarzenie nie ma zastosowania w przypadku niepowodzeń pobierania. Jeśli pobieranie zakończy się niepowodzeniem z powodu błędu protokołu HTTP, zostanie on zgłoszony jako błąd we/wyj.

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

Powiązane elementy interfejsu API

Dysponowana, gdy pobieranie lub wysyłanie danych nie powiedzie się. Przesyłanie pliku może zakończyć się niepowodzeniem z następujących powodów:

• Wystąpił błąd wejścia/wyjścia podczas odczytywania, zapisywania lub przesyłania pliku przez odtwarzacz.
• Plik SWF usiłuje wysłać plik na serwer, który wymaga uwierzytelniania (tj. nazwy użytkownika i hasła). Podczas wysyłania program Flash Player lub środowisko Adobe AIR nie zapewnia użytkownikom środków do wprowadzania haseł. Jeśli plik SWF usiłuje wysłać plik na serwer, który wymaga uwierzytelniania, wysyłanie zakończy się niepowodzeniem.
• Plik SWF usiłuje pobrać plik z serwera, który wymaga uwierzytelniania, za pomocą samodzielnego lub zewnętrznego odtwarzacza. Podczas pobierania autonomiczne i zewnętrzne odtwarzacze nie zapewniają użytkownikom środków do wprowadzania haseł. Pobieranie zakończy się niepowodzeniem, jeśli w tych odtwarzaczach plik SWF usiłuje pobierania pliku z serwera, który wymaga uwierzytelniania. Pobieranie pliku zakończy się pomyślnie jedynie w odtwarzaczach działających jako elementy sterujące ActiveX i wtyczki przeglądarek oraz w środowisku wykonawczym Adobe AIR.
• Wartość przekazana do parametru url metody upload() zawiera niepoprawny protokół. Poprawnymi protokołami są HTTP i HTTPS.

Ważne: jedynie aplikacje uruchomiane w przeglądarce — tj. za pomocą wtyczki przeglądarki lub elementu sterującego ActiveX — oraz treści uruchamiane w aplikacji Adobe AIR umożliwiają wyświetlenie okna dialogowego w celu zapytania o nazwę i hasło użytkownika dla uwierzytelniania; tylko w przypadku pobierania. W przypadku wysyłania za pomocą wtyczki lub elementu sterującego ActiveX w wersji programu Flash Player, lub w przypadku pobierania lub wysyłania za pomocą samodzielnego lub zewnętrznego odtwarzacza, przesyłanie pliku zakończy się niepowodzeniem.

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

Powiązane elementy interfejsu API

Wywoływane po rozpoczęciu operacji wysyłania lub pobierania.

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

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;
    import flash.net.FileFilter;

    public class FileReference_download extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_download() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            configureListeners(file);
            file.download(downloadURL, fileName);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
        }

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

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

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

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

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

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

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
        }
    }
}

Powiązane elementy interfejsu API

Rozsyłane, gdy aplikacja zażąda pozwolenia na dostęp do systemu plików. Sprawdź wartość właściwości status, aby zobaczyć, czy pozwolenie zostało udzielone czy nie.

Powiązane elementy interfejsu API

Dysponowana okresowo podczas operacji wysyłania lub wczytywania pliku. Zdarzenie progress wywoływane jest, gdy program Flash Player przesyła dane na serwer i okresowo podczas przesyłania, nawet jeśli ostatecznie nie zakończy się ono powodzeniem. Aby określić, czy i kiedy przesyłanie rzeczywiście zostanie zakończone powodzeniem, należy wykrywać zdarzenie complete.

W niektórych przypadkach zdarzenia progress nie zostaną odebrane. Na przykład, jeśli przesyłany plik jest bardzo mały lub wysyłanie/pobieranie odbywa się bardzo szybko zdarzenie progress może nie być wywoływane.

Postępu wysyłania pliku nie można wyznaczyć na platformach Macintosh z systemem operacyjnym w wersji starszej niż OS X 10.3. Zdarzenie progress wywoływane jest podczas operacji upload, lecz wartość właściwości bytesLoaded zdarzenia postępu wynosi -1 i wskazuje, że nie można wyznaczyć postępu.

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

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

    public class FileReference_event_progress extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_event_progress() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            file.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            file.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            file.addEventListener(Event.COMPLETE, completeHandler);
            file.download(downloadURL, fileName);
        }

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler: name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }
        
        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }
        
        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }
    }
}

Powiązane elementy interfejsu API

Wywoływane, kiedy wywołanie metody FileReference.upload() lub FileReference.download()skutkuje próbą wysłania pliku na serwer lub pobrania pliku z serwera, który działa na zewnątrz obszaru izolowanego kodu wywołującego. Wartością właściwości text opisującej określony błąd, który się pojawił, jest zazwyczaj "securitySandboxError". Plik wywołujący SWF usiłował uzyskać dostęp do pliku SWF na zewnątrz własnej domeny i nie posiada uprawnień do tego typu działania. Istnieje możliwość zapobiegania takim błędom przez użycie pliku reguł URL.

W aplikacji Adobe AIR te ograniczenia nie są stosowane dla treści w obszarze izolowanym aplikacji.

W aplikacji Adobe AIR te ograniczenia nie są stosowane dla zawartości w obszarze izolowanym aplikacji.

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

Powiązane elementy interfejsu API

Dysponowana, gdy użytkownik wybierze w oknie przeglądania plików plik do wysłania lub pobrania. (To okno dialogowe otwierane jest w momencie wywołania metod FileReference.browse(), FileReferenceList.browse() lub FileReference.download()). Kiedy użytkownik wybiera plik i potwierdza operację (na przykład klikając opcję Zapisz), właściwości obiektu FileReference są wypełniane.

Dla treści uruchomionych w programie Flash Player lub na zewnątrz obszaru izolowanego aplikacji w środowisku wykonawczym Adobe AIR zdarzenie select działa nieco inaczej w zależności od metody, która je wywołała. Jeśli zdarzenie select wywołane zostanie po wywołaniu metody browse(), program Flash Player lub aplikacja AIR może odczytać wszystkie właściwości obiektu FileReference, ponieważ plik wybrany przez użytkownika znajduje się w lokalnym systemie plików. Jeśli po wywołaniu metody download() pojawi się zdarzenie select, program Flash Player lub aplikacja AIR może odczytać jedynie właściwość name, ponieważ w momencie wywołania zdarzenia select plik nie został jeszcze pobrany do lokalnego systemu plików. Jeśli w momencie pobrania pliku wywołane zostanie zdarzenie complete, program Flash Player lub aplikacja AIR będzie w stanie odczytać wszystkie pozostałe właściwości obiektu FileReference.

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

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

    public class FileReference_event_select extends Sprite {
        private var uploadURL:URLRequest;
        private var file:FileReference;

        public function FileReference_event_select() {
            uploadURL = new URLRequest();
            uploadURL.url = "http://www.[yourDomain].com/yourUploadHandlerScript.cfm";
            file = new FileReference();
            file.addEventListener(Event.SELECT, selectHandler);
            file.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            file.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            file.addEventListener(Event.COMPLETE, completeHandler);
            file.browse();
        }

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + uploadURL.url);
            file.upload(uploadURL);
        }

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

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler: name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

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

Wywoływana po pomyślnym wysłaniu danych i odbiorze danych z serwera. To zdarzenie nie jest wywoływane, jeśli dane nie zostaną zwrócone z serwera.

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

Uwaga: w celu uruchomienia tego przykładu, należy zmienić właściwość uploadURL.url tak, aby wskazywała na rzeczywisty adres URL, a nie fikcyjny adres z tego przykładu. Adres URL powinien wskazywać na plik o nazwie yourUploadHandlerScript.cfm w katalogu głównym określonego adresu URL. W zależności od konfiguracji środowiska użytkownika może zaistnieć potrzeba skompilowania pliku SWF z opcją Zabezpieczenie odtwarzania lokalnego ustawioną na Tylko sieć lokalna lub zaktualizowanie ustawień zabezpieczeń programu Flash Player w celu zezwolenia temu plikowi na dostęp do sieci.

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileFilter;
    import flash.net.FileReference;
    import flash.net.URLRequest;

    public class FileReferenceExample extends Sprite {
        private var uploadURL:URLRequest;
        private var file:FileReference;

        public function FileReferenceExample() {
            uploadURL = new URLRequest();
            uploadURL.url = "http://www.[yourDomain].com/yourUploadHandlerScript.cfm";
            file = new FileReference();
            configureListeners(file);
            file.browse(getTypes());
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            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);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
            dispatcher.addEventListener(DataEvent.UPLOAD_COMPLETE_DATA,uploadCompleteDataHandler);
        }

        private function getTypes():Array {
            var allTypes:Array = new Array(getImageTypeFilter(), getTextTypeFilter());
            return allTypes;
        }

        private function getImageTypeFilter():FileFilter {
            return new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg;*.jpeg;*.gif;*.png");
        }

        private function getTextTypeFilter():FileFilter {
            return new FileFilter("Text Files (*.txt, *.rtf)", "*.txt;*.rtf");
        }

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

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

        private function uploadCompleteDataHandler(event:DataEvent):void {
            trace("uploadCompleteData: " + event);
        }

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

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

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

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

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + uploadURL.url);
            file.upload(uploadURL);
        }
    }
}