Spis treści
Pomoc dla Power Net List

Witam w programie odbiorczym szybkiego dostępu do zasobów Internetu i proponuję zapoznanie się z zagadnieniami związanymi z jego użytkowaniem:

Przeznaczenie programu

Polecenia do programu

Opcje konfiguracyjne

Komunikaty DDE

Komunikaty w raporcie

Przykładowa lista poleceń

Zakończenie pracy

O programie


Przeznaczenie programu

Program "Power Net List" służy do odbioru wielu zasobów sieciowych, dostępnych dzięki  protokółom HTTP/1.0, HTTP/1.1 oraz FTP, w trakcie jednej sesji odbiorczej. Popularne przeglądarki stron WWW umożliwiają w danym momencie dostęp do jednej strony hipertekstowej wraz z towarzyszącymi jej grafiką, animacją i muzyką. Czas potrzebny do pełnej percepcji takiej strony jest z reguły ograniczony koniecznością utrzymania kosztownego połączenia z serwerem. Odwołanie się do odsyłaczy znajdujących się na stronie powoduje najczęściej utratę już odebranej informacji. Wszystkie te negatywne efekty uboczne usuwa użycie programu "Power Net List" wraz z odpowiednim programem sterującym. Program bowiem, w możliwie najkrótszym czasie, realizuje odbiór wielu stron WWW wraz z ich otoczeniem.

Podczas odbioru, za pośrednictwem protokółu FTP, zbiorów dyskowych z Internetu często zdarza się, że połączenie z odległym host'em zostaje przerwane. Utracie ulega wtedy często duża już część odebranego pliku. W przypadku pokaźnych zbiorów stanowi to realną stratę kosztów połączenia z Internetem. Zapobiega temu użycie programu "Power Net List". Potrafi on odtworzyć stan przerwanego połączenia i podjąć dalszą transmisję tak, jagby przerwanie to nie nastąpiło. Jedynym wymogiem jest tutaj pozostawienie bez zmian dotyczczasowych parametrów transmisji i fragmentu odebranego zbioru dyskowego.

Program został utworzony za pomocą Microsoft Macro Assembler'a 6.0. W obecnej wersji program "Power Net List" w trakcie odbioru zasobów z Internetu wymaga obecności  biblioteki WINSOCK.DLL, wchodzącej wskład pakietów sieciowych "Trumpet Winsock", "Quarterdeck" albo innych.

Miłej pracy z programem życzy autor Dariusz Żurek

tvtautor@lodz.pdi.net               Łódź dn. 25.09.1997

http://www.lodz.pdi.net/~tvtautor


Polecenia do programu

Aby program "Power Net List" rozpoczął odbiór zasobów sieciowych należy przekazać mu listę poleceń. Lista poleceń może być dostarczona w postaci pliku dyskowego, o nazwie wskazywanej przez pierwszy parametr za nazwą programu albo przez segment -DDE-. Lista musi być zbiorem tekstowym ASCII i składa się z wierszy tekstu występujących w grupach po trzy wiersze. Długość listy nie może przekraczać wartości (2**16 - 3) a zbiór musi być zakończony znakiem -EOF- -1AH-. Każdy pierwszy wiersz grupy może zawierać zestaw opcji konfigurujących odbior zasobu.

Polecenia HTTP

Polecenia FTP

Gdy lista poleceń do programu jest dostarczona za pomocą pliku dyskowego wtedy nazwa pliku w postaci ciągu znaków musi być wpisana za nazwą programu, program zaś natychmiast przystapi do wykonywania operacji odczytu. Po nazwie pliku z lista poleceń można, po spacji, wprowadzić nazwę drugiego pliku dyskoweg. Do tego pliku program zapisze raport o wykonanych w trakcie sesji operacjach i ewentualnie o powstałych w tym czasie błędach. Format raportu można czesciowo zmieniać wpisując odpowiednią opcją do listy poleceń. Ustalony w wersji 1.0 programu format nie będzie zmieniany w nowych jego wersjach. Ogólnie raport składa się z grup wierszy dotyczących odbioru pojedynczego zasobu sieciowego. Grupy wierszy są oddzielone od siebie conajmniej dwoma znacznikami końca wiersza t.j. znakami CRLF.

Po rozpoczęciu pracy, oraz po każdym zakończeniu procesu odbioru dokumentów ale przed rozpoczęciem następnego odbioru, program wysyła do okna o nazwie klasy "Power_Net_Main_Win" komunikat o numerze -0C210H-, informujac o swojej gotowości do rozpoczęcia odbioru zasobów. Młodsze słowo parametru -lParam- informuje o statusie poprzednio przeprowadzonego odbiotu, gdy odbior jest wykonany poprawnie słowo przyjmuje wartosc -0- (zaraz po uruchomieniu programu wartość ta nie ma znaczenia). Inny program, który chce uruchomić opisywany program, w celu skorzystania z jego usług, musi posiadać okno o wspomnianej nazwie klasy. Jesli lista poleceń ma być dostarczona za pomoca komunikatu -DDE-, do linii parametrów nie zapisuje się żadnych parametrów a program wysyła wspomniany juz komunikat -0C210H- i wchodzi w stan oczekiwania na komunikat z zewnątrz. Stan oczekiwania na komunikat może trwać najdłużej 300s po czym program zakończy pracę. Komunikaty z zewnątrz o numerach opisanych w punkcie Komunikaty DDE muszą być skierowane do okna -DDE- o nazwie klasy "Power_Net_List_Win".


Polecenia HTTP do programu
Polecenia HTTP

W przypadku odbioru zasobów za pośrednictwem protokółu HTTP pierwszy wiersz trójki musi zawierać słowo "OPT: ", za którym mogą się znajdować, opisane w punkcie Opcje konfiguracyjne, opcje konfigurujące odbiór. Opcje konfiguracyjne muszą być oddzielone od siebie pojedynczą spacją. Drugi wiersz trójki zawiera adres sieciowy odbieranego zasobu w postaci pełnego -URL- (adresu bezwzględnego) np. "http://www.pdi.net/~tvtautor". Trzeci wiersz zawiera specyfikację zbioru dyskowego, do którego zostanie zapisany, odebrany zasób sieciowy.


Polecenia FTP do programu
Polecenia FTP

W przypadku odbioru zasobów sieciowych za pośrednictwem protokółu -FTP- pierwszy wiersz trójki musi być rozpoczynać się od słowa "FTP: ", za którym musi się znajdować dziesiętna liczba integer, bez znaku, określająca numer porządkowy trójki wierszy. Występujące dalej opcje konfiguracyjne, opisane w punkcie Opcje konfiguracyjne, muszą być oddzielone od siebie pojedynczą spacją. Numer porzadkowy zostanie użyty do oznaczenia raportu o wykonanej operacji, umieszczanego w pliku raportów. Jesli nie użyto opcji "Wrk-File=", to do zbioru wynikowego jest zapisywana informacja tekstowa z listą pozycji znajdujących się w określonym opcją "Wrk-Dir=" katalogu. Jesli nie użyto opcji "Wrk-Dir=", operacje wykonywane są na katalogu roboczym albo aktualnym host'a odległego. Drugi wiersz trójki zawiera nazwę serwera, z którego będzie obierany zbiór dyskowy, w postaci domenowej albo IP. Trzeci wiersz zawiera specyfikację zbioru dyskowego, do którego zostanie zapisany plik, odebrany z sieci albo inne informacje.


Opcje konfiguracyjne

Zarówno przy odbiorze zasobów za pośrednictwem protokółu HTTP jak i FTP do programu trzeba dostarczyć zestaw poleceń, wskład których wchodzą opcje konfiguracyjne.

Opcje HTTP

Opcje FTP


Opcje konfiguracyjne HTTP
Opcje HTTP

Zbiór opcji konfiguracyjnych umieszczanych po słowie "OPT: " listy poleceń do programu:

"User-Id=" - parametr stanowi identyfikator użytkownika używany w wypadku konieczności dokonania identyfiakcji, jako ciąg znaków ACSII, misi występować w parze z "User-Pwd=".

"User-Pwd=" - parametr stanowi hasło użytkownika używane w wypadku konieczności dokonania identyfiakcji, jako ciąg znaków ACSII, misi występować w parze z "User-Id="

"Set-1.1" - wymuszenie wysyłania żądań -HTTP/1.1-

"From=" - parametr stanowi adres e-mail użytkownika programu, przekazywany serwerowi w celach statystycznych i kontrolnych

"Ref=" - parametr stanowi adres strony (pelny URL), który zostanie umiesczony w polu "Referer" komumikatu do serwera. Parametr odnosi się do wszystkich następnych poleceń nie zawierających tego parametru

"Gt-Hdr-Ent" - umieszczanie w raporcie pól HEADER i ERROR-ENTITY komunikatu response. Pole ERROR-ENTITY jest umiesczane miedzy dwoma ciągami znaków: ciąg przed pierwszym znakiem pola ma postać |*{[( , zaś ciąg za ostatnim znakiem pola )]}*| .

"If-Mod-S" - umieszczenie parametru powoduje umieszczenie w komunikacie rządania zasobu pola -If-Modified-Since- z datą zawartą w pliku dyskowym. Data może być zapisana do tego pliku w momencie odebrania zasobu.

"File-Info=" - parametr stanowi nazwę pliku dyskowego, do którego bedą zapisane dodatkowe informacje o odczytywanych zasobach m.in. daty ostatniej modyfikacji używane w opcji "If-Mod-S". Parametr odnosi się do wszystkich następnych poleceń nie zawierających tego parametru.

"No-Recov" - umieszczenie parametru wymusza odbior zbioru FTP w całości od nowa czyli rezygnacje z funkcji -recover-

"Rem-x=" - x to dowolna liczba dziesiętna, parametr stanowi dowolny ciąg znaków będący parametrem albo komentarzem (bez spacji)


Opcje konfiguracyjne FTP
Opcje FTP

Zbiór opcji konfiguracyjnych umieszczanych po słowie "FTP: " listy poleceń do programu:

"User-Id=" - parametr stanowi identyfikator użytkownika używany w wypadku konieczności dokonania identyfiakcji, jako ciąg znaków ACSII.

"User-Pwd=" - parametr stanowi hasło użytkownika używane w wypadku konieczności dokonania identyfiakcji, jako ciąg znaków ACSII.

"User-Acc=" - parametr stanowi informacje o koncie użytkownika wykorzystywane w wypadku konieczności dokonania identyfikacji, jako ciąg znaków ACSII.

"Wrk-Dir=" - parametr stanowi katalog dyskowy albo inny identyfikator grupy plików, z którego będzie pobierany rządany zbiór dyskowy.

"Wrk-File=" - parametr stanowi nazwę pliku dyskowego, który będzie pobierany z określonego katalogu.

"Abo-File" - polecenie: zapisz do zbioru dyskowego informacje o pliku określonym opcją "Wrk-File=", w przeciwieństwie do jego zawartości.

"Rem-x=" - parametr stanowi dowolny ciąg znaków ASCII; -x- to dowolna liczba dziesietna.

"No-Recov" - umieszczenie parametru wymusza odbiór zbioru FTP w całości od nowa, czyli rezygnację z funkcji -recovery-


Komunikaty DDE do programu

Sterowanie pracą programu "Power Net List" może być realizowane za pośrednictwem poczty komuniktów. Program akceptuje następujące komunikaty:

0C211H - Rozpocznij operację odbioru (komunikat z zewnątrz)

lParam - hWord - uchwyt segmentu (global memory) zawierającago strukturę danych o długości 10 bajtów, opisaną niżej

lParam - lWord - offset adresu struktury danych

---------

Opis struktury danych inicjującej operację odbioru:

0000 - offset poczatku listy poleceń do programu

0002 - uchwyt segmentu (global memory) listy poleceń

0004 - offset poczatku bufora dla raportu o przebiegu operacji odbioru

0006 - uchwyt segmentu (global memory) bufora dla raportu

0008 - długość bufora dla raportu

UWAGA! Segmenty muszą być utrzymane do czasu zakończenia bieżącego odbioru, t.j. do wysłania przez opisywany program komunikatu o numerze -0C210H-

0C212H - Zakończ aktualnie wykonywaną operację i zakończ pracę programu (komunikat z zewnątrz)

0C213H - Poinformuj o aktualnym stanie własnym (komunikat z zewnątrz)

0C214H - Odpowiedź na komunikat -0C213H- (komunikat do innego programu)

lParam - hWord - uchwyt segmentu (global memory) zawierającago strukturę danych o długości 8 bajtów, opisaną niżej

lParam - lWord - offset adresu struktury danych

---------

Opis struktury danych:

0000 - 32-bitowa liczba odebranych bajtow od poczatku pracy programu

0004 - 32-bitowa liczba sekund, które upłynęły od poczatku pracy programu


Komunikaty w pliku raportu
Komunikaty w raportcie

Zasadą w pliku raportu, generowanym na życzenie przez program, jest obecność komunikatów o zaistniałych błędach, dotyczących odbioru każdego z zasobów sieciowych. Grupy komunikatów dotyczące poszczególnych zasobów są od siebie oddzielone dwiema parami znaków końca wiersza.

Komunikaty HTTP

Komunikaty FTP


Komunikaty HTTP w pliku raportu
Komunikaty HTTP

Numery komunikatów o błędach umieszczone są na początku wiersza opisującego błąd i ujęte w nawiasy okrągłe np. "(06) Podany host nie podjal wspolpracy". Gdy odbierany za pośrednictwem protokółu HTTP zasób został odebrany poprawnie, generowany jest komunikat (20) albo (04). Przedstawiona treść komunikatów jest w pełni zgodna z ich treścią w pliku raportu (treść jest w kilku wypadkach wyrwana z kontekstu całego zdania). A oto zbiór komunikatów:

(01) Nieprawidlowy format parametrow, adresu zasobu albo adres zbyt dlugi

(02) Odebrano odpowiedz z serwera z komunikatem o bledzie

(03) Wewnetrzny blad w trakcie procesu transmisji

(04) przeprowadzona bez bledu, w wersji HTTP/0.9

(05) Zbyt maly bufor dla zapisania zasobu

(06) Podany host nie podjal wspolpracy

(07) Nieaktywna warstwa fizyczna

(08) Uplynal czas przeznaczony na transmisje danych

(09) Przerwanie na rzadanie uzytkownika

(10) Nie znaleziono rzadanego zasobu

(11) Zasob niedostepny albo serwer rzada identyfikacji uzytkownika

(12) Serwer nie rozpoznal przeslanego rzadania

(13) Zasob nie zostal zmieniony

(14) Powstal blad z winy serwera

(15) Serwer okreslil poprawna nazwe zasobu:

(16) Dolaczono informacje dodatkowe:

(17) Naglowek komunikatu response mial postac:

(18) Czas odbioru i sredni transfer:

(20) przeprowadzona bez bledu

(21) Brak pamieci dyskowej do zapisu zasobu

(22) Wystapil blad operacji dyskowej

(23) Odebrano zasob o zerowej dlugosci

Komunikat (13) jest generowany tylko, gdy użyto opcji "If-Mod-S". Komunikat (15) poprzedza, określoną przez serwer, nawę zasobu, wpisywaną w następnym wierszu raportu. Komunikat (16) poprzedza treść informacji generowanej przez serwer. Informacja jest ograniczona dwoma ciągami, opisanymi w punkcie Opcje HTTP. Komunikat (18) jest umieszczany w pliku raportu, na jego końcu i poprzedza dwie informacje odzielone spacją, znajdujące się w następnym wierszu.


Komunikaty FTP w pliku raportu
Komunikaty FTP

Początek pierwszego wiersza komunikatu FTP stanowi dziesiętna liczba porządkowa polecenia odbioru przeniesiona z pliku poleceń, ograniczona znakami "-" (minus). Za nią występuje odpowiedni tekst. Początek drugiego wiersza komunikatu stanowi kod wykonanej operacji odczytu, jako liczba dziesiętna, ograniczona nawiasami okrągłymi. Możliwe wartości opisane są poniżej. Następne wiersze, jeśli występują, zawierają treść odpowiedzi odległego host'a, pozwalającą zinterpretować ewentualne błędy transmisji.

0 - operacja wykonana poprawnie

1 - nieprawidłowy format parametrów, nazwy hosta albo nazwa zbyt długa

2 - błąd w trakcie trwania operacji sieciowych

3 - wewnętrzny błąd w trakcie wykonywania procesu

4 - nieznany format odpowiedzi na polecenie -LIST-

5 - podana nazwa nie stanowi nazwy pliku albo nieaktualna dlugosc pliku

6 - podany host nie podjął wspołpracy

7 - nieaktywna warstwa fizyczna

9 - przerwanie na rządanie operatora

11 - zasób niedostępny albo niepowodzeniem zakończyła się identyfikacja użytkownika


Przykładowa lista poleceń

Poniżej znajdą Państwo przykładową listę poleceń do programu "Power Net List" zlożoną z dwóch poleceń odbioru za pośrednictwem protokółu FTP. Każde polecenie zawiera trzy wiersze tekstu.

Pierwsze polecenie powoduje odebranie tekstowej listy zawartości katalogu "/pub" znajdującego się na host'cie "ftp.lodz.pdi.net". Lista zostanie zapisana do zbioru dyskowego o specyfikacji "C:\KATALOG\PLIK_N01.TXT".

Drugie polecenie powoduje odebranie zbioru dyskowego o nazwie "ls-lR" znajdującego się w katalogu "/pub" na host'cie "ftp.lodz.pdi.net". Zasób zostanie zapisany do zbioru dyskowego o specyfikacji "C:\KATALOG\PLIK_N02.TXT".

FTP: 01 User-Id=anonymous User-Pwd=tvtautor@lodz.pdi.net Wrk-Dir=/pub

ftp.lodz.pdi.net

C:\KATALOG\PLIK_N01.TXT

FTP: 02 User-Id=anonymous User-Pwd=tvtautor@lodz.pdi.net Wrk-Dir=/pub Wrk-File=ls-lR

ftp.lodz.pdi.net

C:\KATALOG\PLIK_N02.TXT


Zakończenie pracy programu

Zakończenie pracy programu "Power Net List" jest sygnalizowane poprzez wysłanie, do wszystkich aktywnych okien w systemie, komunikatu o wartości heksadecymalnej 0C217h, z okna o uchwycie 01234h. Młodszy bajt młodszego słowa parametru -lParam- informuje natomiast o sposobie zakończenia pracy programu. Jeśli program zakończył pracę po wykonaniu wszystkich założonych czynności to bajt ten przyjmuje wartość -0- .


O programie

Program "Power Net List" jest dziełem autora, o którym mowa w punkcie Przeznaczenie programu Program "Power Net List" jest częścią pakietu programów "Power Net". Program "Power Net List" podlega ochronie prawnej. Dystrybucja programu może odbywać się wyłącznie za zgodą autora wyrażoną na piśmie.

Proszę o zgłaszanie wszelkich uwag na temat pracy programu, za które z góry dziękuję. Będą one uwzględnione przy powstawaniu nowych wersji programu. Informacje te powinny zawierać krótki opis zauważonych nieprawidłowości w działaniu programu oraz adresy odbieranych zasobów i ewentualne komunikaty o powstałych błędach.

Program "Power Net" został zarejestrowany w Polskim Rynku Oprogramowania.