Remote Quotation Protocol - opis

Transkrypt

1 Remote Quotation Protocol - opis Michał Czerski 20 kwietnia 2011 Spis treści 1 Streszczenie 1 2 Cele 2 3 Terminologia 2 4 Założenia Połączenie Powiązania z innymi protokołami Model komunikacji Opis formatu komunikatów Typy pomocnicze Typy komunikatów Opis wymienianych komunikatów 4 7 Opis stanów Klient WAIT MESSAGE STATE WAIT ANSWER STATE Serwer cytatów Numery 7 1 Streszczenie Niniejszy dokument opisuje specyfikację protokołu komunikacji z serwerem cytatów/sentencji. Składa się z następujących sekcji: opis celów protokołu, opis założeń, opis formatu komunikatów, opis stanów. 1

2 2 Cele Głównym celem protokołu jest możliwość szybkiego i masowego pobierania cytatów/sentencji z zdalnego serwera. 3 Terminologia Wykaz używanych w tekście terminów i ich znaczenia: RQP Remote Quotation Protocol Klient instancja protokołu RQP zgłaszająca chęć otrzymania losowego cytatu/sentencji. Serwer cytatów instancja protokołu RQP, która posiada bazę cytatów oraz możliwość ich rozsyłania w odpowiedzi na żądania klientów. 4 Założenia 4.1 Połączenie Komunikacja między klientem a serwerem cytatów odbywać się będzie na zasadach modelu klient-serwer. Każdy z użytkowników instancji protokołu może połączyć się z serwerem cytatów i na zasadach równych praw otrzymać losowo wybrany cytat. 4.2 Powiązania z innymi protokołami Protokół działa w warstwie aplikacji. Transmisja wiadomości musi być przede wszystkim szybka, a nie musi być niezawodna, cała komunikacja będzie się zatem opierać na protokole UDP. 4.3 Model komunikacji Protokół RQP działa w oparciu o model klient-serwer. Serwer cytatów działa na porcie będącym jego parametrem uruchomieniowym, lecz port ten może się zmienić w trakcie jego działania w reakcji na działania użytkownika. 5 Opis formatu komunikatów Założenia: porządek octetów w liczbach: sieciowy. sposób interpretacji liczb ze znakiem: jak w arytmetyce uzupełnień do 2. 2

3 5.1 Typy pomocnicze QDATA_T { uint32 quot_id; uint32 part_no; uint32 parts_total; octet[24] encoding; uint16 buf_length; octet[buf_length] buf; parts_total pole zawierające informację o tym, na ile części została podzielona odpowiedź serwera cytatów. Serwer cytatów dzieli cytaty na części za każdym razem w ten sam sposób. encoding nazwa (w ASCII) zastosowanego kodowania tekstu. buf_length pole zawierające długość danych, długość ta obejmuje tablicę buf. ERROR_T { sint32 error_code; uint16 error_buf_length; octet[error_buf_length] error_buf; error_buf_length pole zawierające długość danych, długość ta obejmuję tablicę error_buf. Kody błędów, które powinny być obsługiwane przez każdą instancję protokołu: error_code Znaczenie 1 Żądanie odrzucone 2 Za dużo żądań, spróbuj później 3 Baza cytatów jest pusta, lub nie istnieje 4 Baza cytatów nie posiada cytatu o danym quot_id 5 Cytat quot_id nie posiada części o danym part_no 6 Żądanie zbyt wielu cytatów (patrz BATCH_REQUEST_MSG) 5.2 Typy komunikatów REQUEST_MSG_T { request_id w przypadku zgłoszenia wielu żądań od jednego klienta, wartość request_id jest unikalna dla każdego z nich. BATCH_REQUEST_MSG_T { uint8 no_of_requests; 3

4 no_of_requests w przypadku zgłoszenia żądania o wiele cytatów, wartość no_of_requests mówi nam o oczekiwanej liczbie cytatów otrzymanej w odpowiedzi. RETRANS_MSG_T { uint32 quot_id; uint32 part_no; QUOT_MSG_T { QDATA_T quot; ERROR_MSG_T { ERROR_T error; 6 Opis wymienianych komunikatów W protokole używane są następujące komunikaty (w nawiasach podane sa argumenty, a po dwukropku typ komunikatu). Numer porządkowy to jednocześnie msg_id przydzielone komunikatowi. 1. REQUEST_MSG(request_id) : REQUEST_MSG_T Prośba o przesłanie losowego cytatu wysłana do serwera cytatów identyfikowana poprzez id. 2. BATCH_REQUEST_MSG(request_id, no_of_requests) : BATCH_REQUEST_MSG_T Prośba o przesłanie no_of_requests losowych cytatów. Przy bezbłędnej komunikacji odpowiedzi przesyłane przez serwer mają w polu request_id wartości z zakresu [request_id, request_id + no_of_requests 1]. 3. RETRANS_MSG(request_id, quot_id, part_no) : RETRANS_MSG_T Prośba o ponowną transmisję części part_no cytatu quot_id. Wartość id powinna być identyczna jak w żądaniu, w którym zaistniał błąd. 4. QUOT_MSG(request_id, quotation_part) : QUOT_MSG_T Odpowiedź serwera cytatów na żądanie o parametrze id zawierająca część cytatu (quotation_part). 5. ERROR_MSG(request_id, error) : ERROR_MSG_T Zgłoszenie błędu error przetwarzania żądania id do klienta. 4

5 msg_id Komunikat 1 REQUEST_MSG(request_id) 2 BATCH_REQUEST_MSG(request_id, no_of_requests) 3 RETRANS_MSG(request_id, quot_id, part_no) 4 QUOT_MSG(request_id, quotation_part) 5 ERROR_MSG(request_id, error) 7 Opis stanów Klient może znajdować się w jednym z dwóch stanów: WAIT_MESSAGE_STATE WAIT_ANSWER_STATE Serwer cytatów jest bezstanowy. 7.1 Klient WAIT MESSAGE STATE W tym stanie klient czeka na zlecenie pobrania nowego cytatu/cytatów z serwera cytatów wysyłając do niego jeden z dwóch możliwych typów wiadomości. 5

6 7.1.2 WAIT ANSWER STATE W tym stanie klient oczekuje na odpowiedź serwera - zawierającą fragment cytatu, lub komunikat o błędzie. Jeżeli klient nie otrzymał jeszcze oczekiwanej liczby cytatów, a od ostatniej odpowiedzi serwera upłynęło już wiecej niż TIMEOUT milisekund, to może zgłosić prośbę o retransmisję niektórych fragmentów. 6

7 7.2 Serwer cytatów Serwer cytatów oczekuje na żądania od klientów, wybiera dla nich cytaty, dzieli je na fragmenty mniejsze od PACKET_SIZE bajtów (podział danego cytatu nie może zmienić się podczas pojedynczego uruchomienia serwera) oraz wysyła odpowiedzi, lub ewentualnie komunikaty o błędach zwiaząnych z przetwarzaniem żądania. 8 Numery Wykaz używanych w tekście stałych i ich wartości: 7

8 PACKET_SIZE zalecana wartość to Wartość ustalana podczas kompilacji. TIMEOUT zalecana wartość to 2500ms. Wartość ustalana podczas uruchomienia. 8