Protokół PolChat

Nieoficjalna dokumentacja protokołu POLCHAT 3.0

(cc) 2007 - 2016 - Marcin 'TheDoctor' Grzechowiak, egonfreeman@gmail.com

Rewizja: 0.4.0.1; data ostatniej modyfikacji: 3. września 2016r.

• Spis treści
• Wstęp
• 1 – Podstawowe informacje
  • 1.1 – Słowo o formacie, konwencje w tym dokumencie
  • 1.2 – Budowa pakietów
  • 1.3 – Bezpieczeństwo
• 2 – Komunikacja z serwerem
  • 2.1 – Połączenie i zalogowanie się
    • 2.1.1 – Błędy połączenia / logowania
  • 2.2 – Pakiety powitalne
  • 2.3 – Pokoje
    • 2.3.1 – Wejście do pokoju
    • 2.3.2 – Zmiana pokoju / wyjście z pokoju
  • 2.4 – Podtrzymanie połączenia (ping)
  • 2.5 – Użytkownicy i stany
    • 2.5.1 – Lista użytkowników
    • 2.5.2 – Stany globalne, stany lokalne
    • 2.5.3 – Kolory, privy
    • 2.5.4 – Operatorzy
    • 2.5.5 – Przyjaciele, ignorowani
  • 2.6 – Prowadzenie rozmowy
    • 2.6.1 – Rozmowy w oknie głównym (main)
    • 2.6.2 – Rozmowy prywatne (priv)
    • 2.6.3 – Polecenia
  • 2.7 – Rozmowa moderowana
  • 2.8 – Kategorie
  • 2.9 – Zmiana hasła (lub rejestracja nicka)
  • 2.10 – Zakończenie sesji, wylogowanie się
• 3 – Indeks pakietów
• 4 – Pytania, korekty
• 5 – Changelog - lista zmian
• 6 – Podziękowania

Wstęp do wstępu, dn. 3. września 2016 roku.

Polchat umarł. Śmierć zanotowano dn. 5. listopada 2012 roku, w/g serwisu antysop.info. W związku z tym faktem wiele projektów budujących na sukcesie serwisu Polchat umarło wraz z nim, wliczając w to P3, TheRaven i inne. Więc po co wskrzeszać zaginiony opis protokołu dla serwera, który na dzień publikacji tego wstępu jest pogrzebany od prawie 4 lat? Cóż – powody są dwa.

Po pierwsze – w końcu udało mi się odkopać w miarę aktualną (jeśli nie najnowszą) wersję tego dokumentu. Straciłem go wraz z wieloma innymi rzeczami w Wielkiej Awarii 2014, kiedy to padły mi zasadniczo wszystkie sprzęty. Chciałem, aby ten dokument gdzieś sobie wisiał i istniał – więc niech wisi i istnieje.

Po drugie, i chyba ważniejsze – zdążyłem już wiele zapomnieć, a ostatnio naszła mnie ochota na odświeżenie wiedzy i odkurzenie paru narzędzi z antycznych półek... a do tego celu potrzebny mi był w miarę kompletny opis protokołu. Na sieci nadal istnieje kilka 'klonów-córek' serwera Polchat (najczęściej w wersji 2.0/2.1), dla których nadal rozwijane jest oprogramowanie (np. klient czatowy na Androida) - jednym z takich serwisów jest Polfan.pl. Nie mam pojęcia co do ich legalności, ale w niczym nie przeszkadza to rozwojowi narzędzi na te platformy.

W każdym razie... nadszedł dzień wskrzeszenia tego dokumentu, co niniejszym czynię (korzystając przy tem z okazji na naniesienie kilku poprawek kosmetycznych). Nie przedłużając więc - zapraszam do lektury i budowania projektów w oparciu o protokół Polchat. Może i umarł, ale zombie zombie zombie. ;-)

— Autor

Wstęp

Nie miałem dotychczas okazji znaleźć kompletnego i niezwiązanego z konkretną implementacją opisu protokołu - dlatego postanowiłem napisać własny. Historia mojej 'współpracy' z Polchatem nie jest jakoś specjalnie długa - bardzo wiele pomogli mi tutaj inni, którzy mieli z nim więcej do czynienia, a także kilka osób równie ciekawych jego pracy jak i ja.

Osobiście jestem programistą PHP (tak, używam języka PHP do pisania programów wykonywalnych .exe), więc mogą pojawić się pewne naleciałości z tego języka - np. analiza pakietów jest dla mnie o niebo łatwiejsza w implementacji PHP, gdyż moje wysiłki wsparte są funkcją unpack().

Miej także, miły Czytelniku, na uwadze fakt, iż opis ten nie jest do końca sztywną specyfikacją, a raczej luźnym podejściem do zebrania i posegregowania wiadomości które - jako ogół czatowiczów - wyszukaliśmy, wyniuchaliśmy i zebraliśmy przez te parę lat pracy systemu. Większość wiadomości pochodzi z moich własnych prób rozgryzienia 'co i jak', lecz nie bałem się prosić o pomoc innych (patrz rozdział 'Podziękowania').

Jeśli zauważysz jakiś błąd, lub doszukasz się czegoś co przeoczyłem - nie wahaj się powiadomić mnie o tym! Mój adres email znajdziesz na górze tego dokumentu, oraz w dziale 'Pytania, korekty'. Pod adresem www http://kadtech.info/polchatproto/ znajduje się zawsze najnowsza wersja tego dokumentu - jeśli znajdziesz uchybienie, sprawdź najpierw, czy dokument który masz jest najświeższą rewizją.

Dokument niniejszy udostępniony jest na warunkach licencji Creative Commons 'ATTRIBUTION' (link otwiera się w nowym oknie) - co oznacza, że możesz go kopiować, rozpowszechniać, edytować, tworzyć zbiory zebrane wliczające ów dokument, a nawet sprzedać - pod warunkiem, że w jasny i czytelny sposób, w widocznym miejscu, zawrzesz informację o autorze tego dokumentu.

Przy okazji - słowo dla wszystkich tych, którzy uważają, iż publikacja protokołu Polchatu spowoduje nagły napływ flooderów, spammerów etc. - przykro mi to wam powiedzieć, ale Polchat jest już pełny tych programów, a ja mam nadzieję na to, że opis protokołu pomoże tym, którzy mają pomysły na np. dobrego bota...

UWAGA: Czytelnik powinien być dobrze zaznajomiony ze sposobem działania serwera Polchatu (od strony użytkownika / czatowicza) przed przystąpieniem do lektury. Nie jest to oczywiście absolutnie konieczne, ale bez tej wiedzy niektóre elementy niniejszego opisu będą wydawać się 'oderwane od siebie' i niespójne.

1 – Podstawowe informacje

1.1a – Słowo o formacie

Protokół Polchatu, ze względu na stosunkowo dużą ilość użytkowników na nim bytujących (a przynajmniej taki projekt) jest protokołem kompaktowym. Mam przez to na myśli fakt, iż używa własnego formatu ciasnego pakowania danych (w przeciwieństwie do np. protokołu Tlena, który używa przejrzystego - ale i bogatego w często zbędne elementy formatu - XMLa). W związku z tym przy komunikacji potrzebna jest, poza innymi, umiejętność 'rozpakowywania' pakietu do formatu zdatnego do obróbki.

Pomijając ciasne pakowanie pakietu, warto wspomnieć o jednej ważnej rzeczy: wszystkie ciągi tekstowe (STRINGi) w komunikacji z serwerem kodowane są do formatu UTF-8 - wypadałoby więc upewnić się, że mamy odpowiednie komponenty do obróbki tego formatu, zanim zaczniemy próbować nawiązać połączenie.

1.1b – Konwencje w tym dokumencie

Informatycy to cholernie leniwy naród - inaczej po co spędzalibyśmy niezliczone dni, aby zautomatyzować nasze 5-minutowe zadania? ;-) W związku z tym niniejszym przedstawiam konwencję nazewnictwa, której będę się trzymać w całym niniejszym `dokumencie`:

Wszystkie struktury, pakiety i przykłady prezentować będę w tej czy innej formie pseudokodu - faktyczną implementację w dowolnym języku pozostawiam Czytelnikowi.

Kolega zwrócił mi uwagę na fakt, że użycie słowa 'int' dla wartości 16-bit i 'bigint' dla wartości 32-bit może być i jest mylące dla ludzi programujących głównie w C/C++. W związku z tym podmieniłem te słowa w całym dokumencie na konkretne wielkości bitowe, o które chodzi. Zauważ, Czytelniku, że w tekście wyjaśnień oraz w nazwach zmiennych wciąż używam słowa INT - jest to wykorzystanie tylko obrazowe, chodzi o INTy 16-bitowe (smallint / word).

1.2 – Budowa pakietu

Każdy pakiet przesyłany między serwerem a klientem charakteryzuje się sztywną konstrukcją - składa się, jak to zwykle bywa, z nagłówka oraz treści. Nagłówek pakietu ma długość 10 bajtów, a struktura jego jest następująca:

Po nagłówku występują dane (treść), składające się z 16-bitowych liczb całkowitych, a po nich - ciągów znaków. Budowa 16-bitowego INTa nie jest specjalnie trudna - jest to wartość dwubajtowa, prezentowana w formie Big-Endian. Budowa ciągów tekstowych jest (dla pewności zrozumienia) następująca:

Wynikowa struktura dowolnego pakietu obrazuje się mniej-więcej tak:

Zwróć uwagę, drogi Czytelniku, że choć tutaj prezentuję budowę nagłówka pakietu, nie będę (w przeciwieństwie do ekg.chmurka.net) prezentować w dalszej części tylko 'reszty' pakietu - z dwóch powodów: pierwszy - ponieważ nagłówek pakietu się zmienia (jego wartości, przynajmniej); po drugie - w opisie protokołu Gadu-Gadu długo nie mogłem wykombinować dlaczego serwer mnie rozłącza... Okazało się, że wskoczyłem od razu 'w środek' całości, i zbudowałem wszystkie struktury bez nagłówka, który opisany był tylko na początku dokumentu. Drugim powodem więc jest ułatwienie i logiczna całość.

1.3 – Bezpieczeństwo

System Polchat w aktualnej jego implementacji* ma jedną, poważną wadę: cała komunikacja z serwerem odbywa się w postaci niezaszyfrowanej (plain-text). W związku z tym Polchat nie jest odporny na ataki typu man-in-the-middle czy zwykły podsłuch. Połączenie jest szczególnie wrażliwe w czasie jego rozpoczęcia, kiedy w pierwszym pakiecie przesyłamy w czystym tekście nazwę użytkownika oraz hasło.

Cała treść rozmów, opisy pokoi etc. przesyłane są w protokole w postaci kodu HTML (podejrzewam, że w celu ułatwienia budowy appletu Java). Stwarza to możliwości wstrzykiwania kodu JavaScript (np. OnMouseOver). Problem został załatany w serwerze w wersji 3.0, ale wszystkie wcześniejsze wersje są podatne na tego typu ataki. Wiele klientów czatowych (ICeQ, NPCC, KCIbot, P3 etc.) rozwiązuje ten problem po swojej stronie, najczęściej za pomocą aktywnej filtracji wiadomości.

* W czasie pisania rewizji 0.4 tego dokumentu, w rozwoju był protokół Polchat 3.0 oraz 3.1 (rozszerzający 3.0), który w moim założeniu m.in. miał wprowadzić szyfrowanie połączeń metodą AES z wstępnym zabezpieczeniem wymiany współdzielonego hasła drogą RSA (podobnie do tego, jak robił to program Tlen.pl). Niestety, odejście głównego developera (de facto praktykanta) z zespołu skutecznie zatrzymało wszystkie prace związane i z 3.0, i z 3.1 - jedyne co docelowo znalazło się w rewizji 3.0 to różne usprawnienia administracyjne (m.in. komenda /mute, czy restrykcja kopania/banowania operatorów o wyższych niż własne uprawnieniach).

2 – Komunikacja z serwerem

2.1 – Połączenie i zalogowanie się

Połączenie z serwerem należy kierować bezpośrednio na adres i port serwera czatowego (historycznie było to s1.polchat.pl i port 14003). Typowym portem serwera nadal pozostaje 14003 (Polfan.pl w swoim "aplecie" twierdzi, że jest to 14080, ale jest to nieprawdą). Pierwszym pakietem który musimy wysłać - jest pakiet logowania. Ma on następującą strukturę:

ad. 'Referrer': jest to ciąg znaków identyfikujących stronę która wysłała nas do serwera - historycznie (w wersji 1.x i wczesne 2.0) było to używane w celu sprawdzenia, że klient loguje się z appletu Java danego serwera, a nie innego. Dla każdego serwera jest on inny, więc trzeba ręcznie 'wybadać sprawę' przed połączeniem. Dla wielu serwerów nie ma on już znaczenia, ale jeśli strona/applet go podaje, dla bezpieczeństwa należy go także podać. Historycznie dla głównego serwera Polchatu miał on wartość:

Program ICeQ korzystał z 'http://www.polchat.pl/chat/?room=ikari', co idealnie obrazuje fakt, że pole to jest zasadniczo nieistotne (podana nazwa pokoju mogła być dowolna).

ad. 'Konfiguracja': jest to ciąg znaków określający nasze podejście do czatu ;-) Przykładowa jego wartość to np.:

Warto zwrócić tutaj uwagę, że ustawienie otrzymywania "Przychodzi..." i "Wychodzi..." (jlmsg) ograniczało się tylko do otrzymywania wiadomości TEKSTOWYCH o tych zdarzeniach. Wiadomości w protokole (skutkujące np. wykreśleniem wychodzącego użytkownika z listy czatujących) są konieczne i wysyłane niezależnie od powyższego ustawienia.

O wiele większy wpływ na czat ma czwarte pole, tj. ignprv. Ustawienie go na false zaskutkuje całkowitym zaprzestaniem wysyłania nam pakietów 611 (priv).

2.1.1 – Błędy połączenia / logowania

W przypadku gdy nasza próba logowania nie powiedzie się, otrzymamy od serwera pakiet zamykający połączenie, wraz z wyjaśnieniem przyczyny. Naszym obowiązkiem w tym momencie jest rozłączyć się. Pakiet błędu ma ID 65535 (FF FF).

Znane są następujące przyczyny błędu logowania. Przyczyna numer #1 jest banalna:

co oznacza tyle, że musimy dobrać sobie inny. ;-)

Przyczyna numer #2 już nie jest taka przyjazna:

... no i w tym momencie mamy zagwozdkę, ponieważ wyjaśnienie to opisuje trzy stany:
- przypadek kiedy identyfikator / nick zawiera niedozwolone znaki,
- przypadek kiedy wpiszemy złe hasło dla nicka który jest zarejestrowany, oraz
- przypadek kiedy wpiszemy jakiekolwiek hasło dla nicka który nie jest zarejestrowany.

Trzeci przypadek to już bezpardonowa bezczelność:

co oznacza ni mniej, ni więcej, tylko tyle, że dostaliśmy s-bana (zazwyczaj w wyniku floodowania, wtedy nazywa się to 'floodban').

Czwarty przypadek zdarza się rzadziej niż pozostałe, ale się zdarza:

co oznacza tyle, że coś z serwerem do którego się łączymy jest poważnie 'nie tak' (najczęściej oznacza to, że nickserver leży). Można próbować połączyć się na nicku tymczasowym...

W ostateczności możemy jeszcze nie połączyć się w ogóle - co oznacza, że serwer po prostu leży jak długi... co się zdarza, rzadko - ale jednak.

Warto tutaj wspomnieć o przypadkach, kiedy otrzymujemy pakiet kończący połączenie od razu po połączeniu z serwerem. Jest to tożsame z wyłączonym ('leżącym') serwerem, może być jednak mylące - serwer Polchat do połączeń socketowych używa zewnętrznego socketa (wewnętrznie wszystko biegnie po named sockets lub pipes), i to on nas rozłącza stwierdzając, że nie ma nas dokąd wysłać... ;-)

Może także nastąpić sytuacja typu 'mogę wejść przez applet, ale nie przez klienta' - oznacza to tyle, że socket leży (tak, miewa tendencje do umierania czasem). W takim wypadku trzeba po prostu poczekać, aż go ktoś podniesie.

UWAGA: w przypadku s-bana przy próbie połączenia nie zawsze otrzymamy informację o tym! Miewałem przypadki, w których po prostu dostawałem informację o tym, że 'połączenie z serwerem zakończone porażką(?)' zamiast 'Dostęp z adresu IP Twojego komputera jest obecnie niemożliwy'. Nie wiem dlaczego tak się dzieje, ale się to zdarza.

2.2 – Pakiety powitalne

Jeśli jakimś cudem wszystko poszło dobrze, serwer odpowie nam przesyłając dwa pakiety powitalne - pakiet ID 626 oraz zwykły tekst "Witaj na czacie! :)" (o nim za chwilę). Pakiet ID 626 zawiera wiele informacji jednocześnie (składają się na niego dwa STRINGi). Przykład:

Pakiet ten najłatwiej analizować w dwóch kawałkach - drugi STRING w jasny (widoczny gołym okiem) sposób prezentuje listę kategorii pokoi, pierwszy zaś zawiera parametry potrzebne do współpracy. Kolejno są to:

Tablica konwersji znaków zasługuje na sumaryczne olanie, gdyż nie znajduje zastosowania przy połączeniu oprogramowaniem obsługującym kodowanie UTF-8 (podejrzewam, że jej funkcja sprowadzała się do konwersji na ISO-8859-2 lub podobnych przypadków).

Nazwy kategorii (włącznie z nadrzędną '/') oddzielone są od siebie spacją.

UWAGA: od momentu, kiedy otrzymamy tablicę konwersji znaków, dalsze wiadomości tekstowe (włącznie z listą kategorii) przesyłane są w postaci UTF-8!

Drugi pakiet powitalny to tekst "Witaj na czacie! :)", przesyłany zwykłym pakietem o ID 610. UWAGA: w protokole 3.0 nastąpiła zmiana także tego pakietu, więc polecam poczytać o nim poniżej. Pakiet ten, jak wszystkie teksty pojawiające się w zakładce systemowej, ma pusty string nazwy pokoju.

2.3 – Pokoje

Cała idea systemu Polchat opiera się na wieloużytkownikowych pokojach, w których użytkownicy mogą brać udział we wspólnej dyskusji (rozmowy prywatne są tylko dwuosobowe). Czas na garść informacji o tychże.

2.3.1 – Wejście do pokoju

Zaraz po poprawnym zalogowaniu się i odebraniu pakietów powitalnych, zostaniemy wrzuceni do pokoju który określiliśmy w pakiecie log-in. Procedura wejścia do pokoju jest... bardziej skomplikowana niż inne. Może nawet trochę za bardzo. Ogólna procedura jest następująca:

Należy pamiętać, że do pierwszego pokoju wysyłani jesteśmy bez naszej interwencji - do wszystkich innych musimy wyrazić tę chęć sami (wydając polecenie /join nazwa_pokoju).

UWAGA: czasami nie zostaniemy przeniesieni do pokoju. Objawia się to tym, że po połączeniu i otrzymaniu pakietów konfiguracyjnych następuje... cisza. Dzieje się to tylko wtedy, gdy jako pokój startowy podamy pokój nieistniejący ('tymczasowy') lub pokój utworzony przez użytkownika. Należy wtedy spróbować wejść do jakiegokolwiek pokoju głównego (polchat, erotyczny, 40-lat etc.). Są duże szanse, że akurat trafiliśmy na moment, kiedy wystąpił na serwerze błąd uniemożliwiający a) tworzenie 'tymczasowych' pokoi, i b) dostęp do pokoi użytkowników (nie-głównych). Zdarza się to zupełnie losowo, i najczęściej nie zostaniemy o tym w żaden sposób poinformowani -- /join [nazwapokoju] po prostu nie przyniesie jakiegokolwiek skutku (czasami otrzymujemy wiadomość "** przejście do (innego?) pokoju jest tymczasowo niemożliwe"). Należy tę sytuację po prostu przeczekać. Powyższa sytuacja nie dotyczy pokoi głównych - do nich można wchodzić zawsze.

2.3.2 – Zmiana pokoju / wyjście z pokoju

Kiedy mówię o zmianie pokoju, mam na myśli sytuację kiedy jesteśmy już w pokoju, i chcemy go zmienić. W przypadku kiedy nie jesteśmy w żadnym pokoju (/part), przejście do dowolnego pokoju ma identyczny przebieg jak napisałem wyżej (2.3.1).

Właściwie tutaj należałoby tylko dodać informację o opuszczaniu pokoju - jest to procedura dwu-/trzystopniowa, w zależności od tego kto wychodzi - my, czy ktoś inny:

Chęć wyjścia z pokoju sygnalizuje się wydanie polecenia /part [opcjonalne pożegnanie]. Chęć wejścia do kolejnego pokoju sygnalizuje się poleceniem /join [nazwa pokoju]. Jeśli zmieniamy pokój, musimy najpierw wydać /part i obsłużyć procedurę powyżej, i bezpośrednio po niej /join i obsłużyć ponownie procedurę z pkt. 2.3.1. Jeśli tylko opuszczamy pokój, to obsługujemy tylko to co powyżej.

Powyższy tekst wydawać się może niejasny dla użytkowników Polchat 2.0 - tam można było przebywać tylko w jednym pokoju naraz. W Polchat 3.0 (obecny obowiązujący) można przebywać w wielu jednocześnie, więc wydanie polecenia /join nie skutkuje naszym wyjściem z dotychczasowego pokoju.

2.4 – Podtrzymanie połączenia (ping)

Pakiety ping-pong Polchatu są pakietami 'pustymi', praktycznie dosłownie. Ping-pong działa na prostej zasadzie: serwer Polchat nas pinguje, po czym my mu odpowiadamy. Struktury:

UWAGA: pakiet PONG jest, z tego co mi wiadomo, JEDYNYM pakietem który odchodzi od konwencji 'minimum 1 INT - ID pakietu'.

2.5 – Użytkownicy i stany

Czymże byłby system czatowy bez swoich użytkowników? Niestety, programy wchodzące na Polchat (w tym także, a może przede wszystkim, applet Java) nie wiedzą 'automagicznie' jacy użytkownicy przebywają w pokoju. Wygląd pakietu JOIN już opisałem, pakiet LEAVE także. Czas zakasać rękawy i zabrać się za to, czego tygryski nie trawią w większości implementacji - userlistę.

2.5.1 – Lista użytkowników

Userlista ma to do siebie, że ktoś kto nie jest obeznany ze znaczeniem kolejnych elementów potrafi tygodniami siedzieć i kombinować o co z tym pakietem chodzi. Struktura userlisty jest całkiem logiczna (co nie znaczy 'banalna'):

Może ja od razu wyjaśnię co i jak: userlista, w rdzeniu, zbudowana jest z dwóch rzeczy: listy nicków, oraz ich właściwości. Jak zwykle, ciągi tekstowe umieszczone są na końcu pakietu, co może przyprawiać niektórych o ból głowy... ;-)

Te cztery INTy - NumGlobalInt, NumLocalInt itd. - informują nas, ile elementów 'na łebka' będzie upakowane. W przypadku Polchatu 2.0 jest to odpowiednio 1,1,0,0 - jeden INT globalny, jeden INT lokalny, i zero stringów lokalnych/globalnych. Dla Polchatu 3.0, jest to 1,1,1,0 - jeden INT globalny, jeden INT lokalny, jeden STRING globalny i zero STRINGów lokalnych. Zawartość i znaczenie tych dwóch INTów opiszę poniżej - teraz tylko dokończę pakiet userlisty:

Dla końcowego wyjaśnienia przypominam tylko, że kiedy otrzymujemy userlistę, naszego nicka NIE MA na niej - od tego jest pakiet JOIN.

W przypadku gdy wchodzimy do pustego pokoju, możemy otrzymać 'pustą' userlistę, wygląda to tak:

2.5.2 – Stany globalne, stany lokalne

W punkcie powyżej poruszyłem szalenie istotny temat - dwa INTy stanów. Jest on istotny dlatego, że bez pełnego zrozumienia funkcjonowania tych elementów nie jesteśmy w stanie dowiedzieć się czegokolwiek o stanie użytkowników na pokoju - bez tego jesteśmy ślepi od początku do końca.

Zajmę się najpierw stanem globalnym, gdyż jest łatwiejszy do zrozumienia - a także przez to, że stan globalny użytkownika prezentuje się dla wszystkich czatowiczów tak samo. W tym miejscu muszę, niestety, wprowadzić termin operacji bitowych: bitowe AND, oraz bitowe OR. Krótkie wyjaśnienie:

Jak widać, za pomocą tego operatora możemy sprawdzić, czy wartość 3 'zawiera w sobie' wartość 2 - tzn. jeśli 2 & 3 = 2, to 3 zawiera 2. Ta konkluzja jest szalenie istotna przy odczytywaniu tzw. flag (którymi te INTy w rzeczywistości są). Może w takim zapisie nie jest to najczytelniejsze, ale roważny następujący przykład:

Druga operacja to logiczne OR:

Co sprytniejsi zauważyli, że ta operacja jest operacją 'przeciwną' do bitowego AND w tym sensie, że o ile bitowe AND pozwala 'odczytywać' flagi, o tyle bitowe OR pozwala je TWORZYĆ. Rozważmy następujący przykład:

Wszyscy, którzy zrozumieją powyższe wyjaśnienie, nie będą mieli problemów ze zrozumieniem tego co napiszę w następnych podrozdziałach.

2.5.3 – Kolory, privy

Kolory oraz privy 'nanoszone' są za pomocą bitowego OR na Stan Globalny użytkownika. Priv jest znaczony na najmniej znaczącym bicie tegoż INTa, tj.:

Kolor już nie jest taką prostą sprawą, gdyż kolejne kolory (max. możliwych kolorów to ilość wartości zapisywalnych na najbardziej znaczących 12 bitach 16-bitowego stanu globalnego czyli 4095 kolorów + brak koloru, zakładając że nic nie skorzysta z tej przestrzeni w przyszłości) przeliczane są formułą NumerKoloru * 16. Przykład:

Najłatwiej odczytać kolor użytkownika przesuwając wartość o 4 bity w prawo. ;) (google bitshifting)

Zmiana stanu użytkownika (np. po operacji /guest nadającej kolor, lub /op nadającej opa) sygnalizowana jest za pomocą pakietu GlobalStatusChange:

Dodam jeszcze tylko, że struktura zmiany Stanu Globalnego rozsyłana jest do WSZYSTKICH obecnych w pokoju.

2.5.4 – Operatorzy

Właściwie wyjaśnienie stanu operatora znajduje się w obu punktach powyżej, ale dla porządku: stan operatora określany jest na drugim najmniej znaczącym bicie Stanu Globalnego danego użytkownka (drugi bit od prawej), więc wykonuje się operację bitowego OR z liczbą 2 aby go nadać (przykładowy op: 00000010).

S-operatorzy (operatorzy serwera/sopy) funkcjonują na takiej samej zasadzie. Nie, nie ma dla nich nic wyjątkowego w protokole. Oczywiście, s-operatorzy mają status operatora w każdym pokoju, ale w zależności od typu (sfull, shalf) nadawany jest im odpowiedni typ operatora lokalnego (full, half) po wejściu do danego pokoju — jak każdemu innemu operatorowi.

Różnorakie typy uprawnień operatora nie mają wpływu na protokół.

2.5.5 – Przyjaciele, ignorowani

Stan Globalny opisałem w paragrafach powyżej. Czas na Stan Lokalny - który także jest flagą, ale odpowiada za obecność użytkownika na liście przyjaciół, ignorowanych, lub za stan 'ja sam'. UWAGA: stan lokalny jest dla każdego odbiorcy inny! (tak jak każdy odbiorca ma swoją listę przyjaciół i ignorowanych)

Zmiana stanu lokalnego sygnalizowana jest strukturą LocalStatusChange, którą przytoczyłem przy okazji opisu procedury wejścia do pokoju. Przytoczę ją jednak ponownie, dla jasności:

Stan lokalny użytkownika wysyłany jest tylko do jednego odbiorcy (zasadniczo do nas), i występuje jako reakcja na polecenie (/buddy, /unbuddy, /ignore, /unignore - kiedy przybiera wartość 1, 2 lub 0) oraz w momencie wejścia do pokoju (kiedy przybiera wartość 4 i nicka [nasz nick, na którym weszliśmy do pokoju] aby zasygnalizować że nasz nick na liście - to my).

UWAGA: protokół Polchat POZWALA na taką sytuację, w której otrzymamy wartość 3 (buddy + ignor)! Jest to może i nielogiczne, ale jak najbardziej naturalne - applet Java polchatu potrafi w takiej sytuacji wyświetlić obie 'łapki' (w górę i w dół) przy nicku. Programy typu ICeQ czy NPCC 'załatwiają' sprawę za pomocą ustalenia 'ignora' (jeśli ktoś jest przyjacielem i jednocześnie ignorowany - jest ignorowany, i kropka).

2.6 – Prowadzenie rozmowy

Prowadzenie rozmowy jest kluczowym elementem systemu czatowego. Co zabawne, jest także najprostszym elementem protokołu Polchat.

2.6.1 – Rozmowy w oknie głównym (main)

Wiadomości w oknie głównym rozsyłane są do wszystkich użytkowników obecnych w danym pokoju, chyba że użytkownik zdecydował się ignorować daną osobę - wtedy pakietu z jej wypowiedzią teoretycznie otrzymać nie powinien.

Ktoś może mi się teraz zapytać - o co chodzi? Bo przecież jeden pakiet wypowiedzi już opisałem. Nie, jest pewna różnica: pakiet, który my (klient) wysyłamy do serwera posiada ID 410, podczas gdy ten sam pakiet z naszą wiadomością, wracając do nas, ma już ID równe 610. To pozwala rozróżnić pochodzenie pakietu - rozróżnienie to jest o tyle istotniejsze, że i main, i priv my 'załatwiamy' jednym pakietem, a serwer - dwoma. Ale do rzeczy: pakiet o id 410 nie różni się zasadniczo od pakietu serwerowego:

Różnica jest w tym, że nasza wiadomość wysyłana jest na zasadzie 'Wiadomość', podczas gdy serwer odsyła to do nas spowrotem w formie '[nick]: Wiadomość', odpowiednio nakładając też kolor nicka, w/g jego flagi globalnej (patrz dział 2.5).

2.6.2 – Rozmowy prywatne (priv)

Prowadzenie rozmowy prywatnej jest jakby 'przejściem' pomiędzy rozmową publiczną a poleceniami - gdyż samo w sobie jest poleceniem. Aby rozmawiać z kimś prywatnie, każdą wypowiedź prywatną musimy ująć tak:

Należy pamiętać aby KAŻDĄ wiadomość prywatną tak zapisywać, nie tylko pierwszą!

Wspaniale. O ile wysyłanie wiadomości prywatnej jest proste, o tyle odbieranie jej jest już nieco bardziej skomplikowane. Wiadomości prywatne przychodzą do nas pakietem typu 611 (pisałem o tym rozróżnieniu wcześniej), i ich budowa żalezy od tego czy my wysyłamy, czy odbieramy wiadomość prywatną:

Jeśli chwilę nad tym pomyślisz - zrozumiesz ideę takiego rozwiązania. Każdy z programów (u jednego i drugiego czatowicza) musi przecież wiedzieć, w którym okienku umieścić daną wypowiedź. ;-)

Należałoby także wspomnieć, iż jeśli nasz klient pracuje w trybie standardowym (ICeQ pozwala zmienić ten tryb), w momencie wysłania wiadomości prywatnej powinniśmy także zmienić nasz stan globalny - konkretniej flagę PRIV - na 1. Po zamknięciu priva przywracamy jej stan 0 (priv zamknięty).

2.6.2 – Polecenia

Polecenia wysyła się tak samo jak privy - za pomocą pakietu 410 o treści '/polecenie [parametry]'. Nie będę wchodził tutaj w szczegóły takiego pakietu, gdyż dostatecznie wiele razy powtarzałem jego strukturę powyżej. Chciałbym tylko wprowadzić pewne logiczne rozróżnienie ze względu na efekt polecenia: polecenia zwracające tekst (przychodzący pakietem 610), i polecenia wywołujące akcję sygnalizowaną innym typem pakietu. Do tych pierwszych zaliczyć należy:

Do tych drugich nastomiast:

2.7 – Rozmowa moderowana

Z racji tego, iż moderkę wyłączono w ogólnym czacie, pominę tutaj jej opis. Nie mam po prostu jak sprawdzić, jak działa. Zrobię, jeśli będzie nacisk ze strony użytkowników tego opisu... ;) Zasadniczo sprowadzała się do tego co powyżej, z tą różnicą, że wiadomości otrzymywał moderator a nie wszyscy - i dopiero po zatwierdzeniu tej wiadomości (nieznanym pakietem) docierała ona do wszystkich uczestników. Podejrzewam, że istniały także specjalne stany globalne (moderator, +głos etc.) dla osób moderujących oraz np. gości, którzy mogli wypowiadać się bez ograniczeń.

Występowały oczywiście wiadomości typu "** Rozpoczyna się rozmowa moderowana" etc., ale te wysyłane były trywialnym 610.

2.8 – Kategorie

Listę kategorii otrzymujemy tuż po połączeniu się z serwerem (drugi string w pakiecie 626). Aby uzyskać listę pokoi w danej kategorii, wysyłamy pakiet o ID 411 - Category_Request:

Warto zauważyć, że nazwę kategorii odbieramy w postaci /Nazwa Kategorii/, i w taki sam sposób należy ją wysłać (tj. pomiędzy znakami /).

Jeżeli podaliśmy poprawną nazwę kategorii, powinniśmy otrzymać spowrotem pakiet o ID 613, czyli Category_Reply:

Lista pokoi będzie w dość zagmatwanej postaci... na przykład:

O czym należy obowiązkowo wiedzieć w stringu powyżej (celowo pofragmentowałem jak widać, bo to jest faktycznie jeden ciąg):

• informacja o każdym pokoju zaczyna się od "- " ('myślnik spacja')
• pokoje główne są pomiędzy <b> oraz </b> (czyli pogrubione)
• opis pokoju nie musi wystąpić
  • jeśli opis pokoju wystąpi, będzie w postaci " &nbsp; [Opis pokoju]" (z frontu jest 'spacja &nbsp; spacja')
• liczba w nawiasie to aktualna ilość czatowiczów w tym pokoju (należy pamiętać, że puste pokoje użytkowników nie pojawiają się na liście, więc jedyne pokoje z "(0)" to pokoje główne)
• wszelkie spacje w nazwach pokoju (z powodu błędu lub celowo) są prezentowane w postaci np. "Czat&nbsp;Abstynencja" zarówno w linku /join, jak i w nazwie — ale takie nazwy pokoi (tudzież linki) nie dekodują się poprawnie - należy zrobić to ręcznie (tj. prowadzą do, jak w tym przykładzie, dosłownie - pokoju o nazwie 'Czat&nbsp;Abstynencja' - który oczywiście nie istnieje)

Uwaga: ze względu na to, że pakiet informujący o liście pokoi zwyczajowo przekroczy dopuszczalne MTU w sieci (średnie MTU to 1450 bajtów), należy ekstra uważać na fragmentację pakietów. Ale komu ja to mówię? :)

2.9 – Zmiana hasła (lub rejestracja nicka)

Ze względu na to, że rejestracja identyfikatora/zmiana hasła w portalu Polchat.pl jest operacją obejmującą więcej niż wpis w bazie czatu, sekcja niniejsza nie powstanie. Z tego samego względu Ikari usunął opcję 'Zmień hasło' z najnowszych wersji programu ICeQ. Aby zmienić hasło lub zarejestrować identyfikator, należy udać się na stronę www.polchat.pl.

2.10 – Zakończenie sesji, wylogowanie się

Zakończenie naszej sesji z serwerem Polchat wywołujemy za pomocą wysłania polecenia '/quit [opcjonalna wiadomość pożegnalna]' (wiadomość nie wyświetli się, jeśli nie jesteśmy w żadnym pokoju, oczywiście). Serwer odpowie nam na nią pakietem 65535 (FF FF):

Po otrzymaniu tej wiadomości powinniśmy zamknąć nasze połączenie z serwerem (serwer zapewne już to zrobił). I to wszystko, wylogowaliśmy się z sesji Polchatu.

3 – Indeks pakietów

[ w produkcji ]

4 – Pytania, korekty

Cóż... jestem tylko człowiekiem, a podobno mylić się jest rzeczą ludzką. Jak parokrotnie wspomniałem w tekście wyżej - jeśli doszukasz się błędów lub braków, bardzo gorąco proszę o kontakt mailowy (adres e-mail na górze strony) z informacją o tym, abym jak najszybciej mógł poprawić/dopisać rzeczony fragment.

Jeśli macie jakiekolwiek pytania, także dotyczące konkretnych rozwiązań które zastosowałem w swoich programach, możecie śmiało pytać, pisząc maila na adres: egonfreeman@gmail.com. W tytule wiadomości proszę na początku wpisać [Protokół Polchat].

5 – Changelog - lista zmian

• 2016.09.03 — zmiany kosmetyczne, nowy wstęp etc. etc., no i republikacja
• 2009.04.08 — przepisanie opisu pod zgodność z protokołem POLCHAT 3.0 (dzięki aTahualpa)
• 2008.10.02 — parę kosmetycznych poprawek w liście poleceń systemu, oraz ich uzupełnienie
• 2008.08.06 — wprowadzenie informacji o liście kategorii (wysyłanie zapytania i odbieranie info)
• 2008.04.26 — uzupełnienie listy komend, poprawki w nazewnictwie pakietów, różne błędy, garść nowych informacji
• 2007.09.23 — poprawki w czytelności
• 2007.09.22 — dopisałem parametry userlisty - podstawy komunikacji są skończone
• 2007.09.21 — dokument istnieje

6 – Podziękowania

Kłamałbym w żywe oczy gdybym stwierdził, że doszedłem do wszystkiego sam. Różne osoby pomogły mi w różny sposób po drodze, czy to wspomagając wysiłki, czy też wykonując dla mnie różne dziwne zadania (np. testowanie, sniffowanie), czy po prostu będąc przy mnie w chwilach załamania stresowego... Dlatego chciałbym skorzystać z jakże prestiżowej OSTATNIEJ (;P) części tego dokumentu, aby podziękować niektórym oficjalnie:

• Cezar "Ikari" Pokorski — za wyjątkowo anielską, jak na niego, cierpliwość, i ogólną chęć pomocy (czytaj: odpisywanie na co 5. wiadomość, zamiast jak u innych - na co 100tną... lub wcale xD on wie, o co chodzi xDDDDD) no i oczywiście za napisanie tak cudnie podatnego na sniffy programu ICeQ! xD Ze best klient czatowy do PolChatu, że dodam!
• Tomasz "DMC" Jaworski - za napisanie bota KCI, do którego później zezwolił mi zaglądnąć, dzięki czemu miałem jako-takie pojęcie w co się pakuję ^^'
• PiotrekXX aka Kwasek - za chwilę czasu poświęconą na przeżucie listy kategorii :)
• Sebastian "TomIgnatius" Ociepa - hm... właściwie za to, że spędziliśmy razem dłuuugie godziny szkoląc jego umiejętność obsługi pakietów - dzięki czemu i ja się czegoś nauczyłem ^^
• Sławomir "TREN" Kuć - za wskazanie mi w jaki sposób mogę uczynić dokument czytelniejszym, aby był zrozumiały dla jak największej liczby odbiorców
• aTahualpa z pokoju Terrarystyka - za podrzucenie mi zaobserwowanych zmian w protokole POLCHAT 3.0

Wszystkim wam i tym, których pominąłem - serdecznie Dziękuję! ^__^

Chciałbym też gorąco podziękować Marcinowi 'MalCom' Malichowi za prześliczny opis protokołu Tlen.pl, oraz ludziom z zespołu ekg.chmurka.net (ekg-devel) za trochę trudniejszy ale mimo to wyśmienity opis protokołu Gadu-Gadu - to dzięki ich pracy w ogóle zainteresowałem się dokumentacją protokołów komunikacyjnych.