Protokół Gadu-Gadu

© Copyright 2001-2009 Autorzy


Spis treści

  1. Protokół Gadu-Gadu
    1.1.  Format pakietów i konwencje
    1.2.  Zanim się połączymy
    1.3.  Logowanie się
    1.4.  Zmiana stanu
    1.5.  Ludzie przychodzą, ludzie odchodzą
    1.6.  Wysyłanie wiadomości
    1.7.  Otrzymywanie wiadomości
    1.8.  Ping, pong
    1.9.  Rozłączenie
    1.10.  Wiadomości systemowe
    1.11.  Wiadomości GG_XML_ACTION
    1.12.  Katalog publiczny
    1.13.  Lista kontaktów
    1.14.  Indeks pakietów
  2. Usługi HTTP
    2.1.  Format danych
    2.2.  Tokeny
    2.3.  Rejestracja konta
    2.4.  Usunięcie konta
    2.5.  Zmiana hasła
    2.6.  Przypomnienie hasła pocztą
  3. Połączenia bezpośrednie
    3.1.  Nawiązanie połączenia
    3.2.  Przesyłanie plików
    3.3.  Rozmowy głosowe
  4. Autorzy

Informacje wstępne

Opis protokołu używanego przez Gadu-Gadu bazuje na doświadczeniach przeprowadzonych przez autorów oraz informacjach nadsyłanych przez użytkowników. Żaden klient Gadu-Gadu nie został skrzywdzony podczas badań. Reverse-engineering opierał się głównie na analizie pakietów przesyłanych między klientem a serwerem.

Najnowsza wersja opisu protokołu znajduje się pod adresem http://toxygen.net/libgadu/protocol/.


1. Protokół Gadu-Gadu

1.1. Format pakietów i konwencje

Podobnie jak coraz większa ilość komunikatorów, Gadu-Gadu korzysta z protokołu TCP/IP. Każdy pakiet zawiera na początku dwa stałe pola:

struct gg_header {
	int type;	/* typ pakietu */
	int length;	/* długość reszty pakietu */
};

Wszystkie zmienne liczbowe są zgodne z kolejnością bajtów maszyn Intela, czyli Little-Endian. Wszystkie teksty są kodowane przy użyciu zestawu znaków UTF-8, chyba że zaznaczono inaczej. Linie kończą się znakami \r\n.

Przy opisie struktur, założono, że char ma rozmiar 1 bajtu, short 2 bajtów, int 4 bajtów, long long 8 bajtów, wszystkie bez znaku. Używając architektur innych niż i386, należy zwrócić szczególną uwagę na rozmiar typów zmiennych i kolejność bajtów. Poza tym, większość dostępnych obecnie kompilatorów domyślnie wyrównuje zmienne do rozmiaru słowa danej architektury, więc należy wyłączyć tą funkcję. W przypadku gcc będzie to __attribute__ ((packed)) zaraz za deklaracją każdej struktury, a dla Microsoft Visual C++ powinno pomóc:

#pragma pack(push, 1)

/* deklaracje */

#pragma pack(pop)

Pola, których znaczenie jest nieznane, lub nie do końca jasne, oznaczono przedrostkiem unknown.


1.2. Zanim się połączymy

Żeby wiedzieć, z jakim serwerem mamy się połączyć, należy za pomocą HTTP połączyć się z appmsg.gadu-gadu.pl i wysłać:

GET /appsvc/appmsg_ver8.asp?fmnumber=NUMER&fmt=FORMAT&lastmsg=WIADOMOŚĆ&version=WERSJA HTTP/1.1
Connection: Keep-Alive
Host: appmsg.gadu-gadu.pl

Gdzie:

  • NUMER jest numerem Gadu-Gadu.
  • WERSJA jest wersją klienta w postaci „A.B.C.D” (na przykład „8.0.0.7669”).
  • FORMAT określa czy wiadomość systemowa będzie przesyłana czystym tekstem (brak zmiennej „fmt”) czy w HTMLu (wartość „2”).
  • WIADOMOŚĆ jest numerem ostatnio otrzymanej wiadomości systemowej.

Na postawione w ten sposób zapytanie, serwer może odpowiedzieć w następujący sposób:

HTTP/1.0 200 OK
Connection: close

0 0 91.197.13.78:8074 91.197.13.78

Pierwsze pole jest numerem wiadomości systemowej, a trzecie i czwarte podają nam namiary na właściwy serwer. Jeśli serwer jest niedostępny, zamiast adresu IP jest zwracany tekst „notoperating”. Jeżeli połączenie z portem 8074 nie powiedzie się z jakichś powodów, można się łączyć na port 443.

Jeśli pierwsza liczba jest różna od zera, zaraz po nagłówku znajduje się wiadomość systemowa w wybranym formacie, lub jeśli linia zaczyna się od znaku „@”, adres strony, którą należy otworzyć w przeglądarce.

GET /appsvc/appmsg3.asp?fmnumber=NUMER&version=WERSJA&fmt=FORMAT&lastmsg=WIADOMOŚĆ
Host: appmsg.gadu-gadu.pl
User-Agent: PRZEGLĄDARKA
Pragma: no-cache

1.3. Logowanie się

Po połączeniu się portem 8074 lub 443 serwera Gadu-Gadu, otrzymujemy pakiet typu 0x0001, który na potrzeby tego dokumentu nazwiemy:

#define GG_WELCOME 0x0001

Reszta pakietu zawiera ziarno — wartość, którą razem z hasłem przekazuje się do funkcji skrótu:

struct gg_welcome {
	int seed;	/* ziarno */
};

Kiedy mamy już tą wartość możemy odesłać pakiet logowania:

#define GG_LOGIN80 0x0031

struct gg_login80 {
        int uin;              /* numer Gadu-Gadu */
        char language[2];     /* język: "pl" */
        char hash_type;       /* rodzaj funkcji skrótu hasła */
        char hash[64];        /* skrót hasła dopełniony \0 */
        int status;           /* początkowy status połączenia */
        int flags;            /* flagi (przeznaczenie nieznane) */
        int features;         /* opcje protokołu (0x00000007)*/
        int local_ip;         /* lokalny adres połączeń bezpośrednich (nieużywany) */
        short local_port;     /* lokalny port połączeń bezpośrednich (nieużywany) */
        int external_ip;      /* zewnętrzny adres (nieużywany) */
        short external_port;  /* zewnętrzny port (nieużywany) */
        char image_size;      /* maksymalny rozmiar grafiki w KB */
        char unknown2;        /* 0x64 */
        int version_len;      /* długość ciągu z wersją (0x21) */
        char version[];       /* "Gadu-Gadu Client build 8.0.0.7669" (bez \0) */
        int description_size; /* rozmiar opisu */
        char description[];   /* opis (nie musi wystąpić, bez \0) */
};

Pola określające adresy i port są pozostałościami po poprzednich wersjach protokołów i w obecnej wersji zawierają zera.

Pole z flagami jest przekazywane innym kontaktom, ale jego znaczenie nie jest jeszcze znane. Ustalono jedynie, że wartość 0x00100000 powoduje wyświetlenie ikony telefonu komórkowego na liście kontaktów, a bitmaska 0x00800000 wyłącza "cenzurowanie" linków

Pole opcji protokołu zawsze zawiera wartość 0x00000007 i jest mapą bitową:

BitWartośćZnaczenie
00x00000001Rodzaj pakietu informującego o zmianie stanu kontaktów (patrz bit 2)
0GG_STATUS77, GG_NOTIFY_REPLY77
1GG_STATUS80BETA, GG_NOTIFY_REPLY80BETA
10x00000002Rodzaj pakietu z otrzymają wiadomością
0GG_RECV_MSG
1GG_RECV_MSG80
20x00000004Rodzaj pakietu informującego o zmianie stanu kontaktów (patrz bit 0)
0 — wybrany przez bit 0
1GG_STATUS80, GG_NOTIFY_REPLY80

Skrót hasła można liczyć na dwa sposoby:

#define GG_LOGIN_HASH_GG32 0x01
#define GG_LOGIN_HASH_SHA1 0x02

Pierwszy algorytm (GG_LOGIN_HASH_GG32) został wymyślony na potrzeby Gadu-Gadu i zwraca 32-bitową wartość dla danego ziarna i hasła. Jego implementacja w języku C wygląda następująco:

int gg_login_hash(unsigned char *password, unsigned int seed)
{
	unsigned int x, y, z;

	y = seed;

	for (x = 0; *password; password++) {
		x = (x & 0xffffff00) | *password;
		y ^= x;
		y += x;
		x <<= 8;
		y ^= x;
		x <<= 8;
		y -= x;
		x <<= 8;
		y ^= x;

		z = y & 0x1f;
		y = (y << z) | (y >> (32 - z));
	}

	return y;
}

Ze względu na niewielki zakres wartości wyjściowych, istnieje prawdopodobieństwo, że inne hasło przy odpowiednim ziarnie da taki sam wynik. Z tego powodu zalecane jest używane algorytmu SHA-1, którego implementacje są dostępne dla większości współczesnych systemów operacyjnych. Skrót SHA-1 należy obliczyć z połączenia hasła (bez \0) i binarnej reprezentacji ziarna. Przykładowy kod może wyglądać w następujący sposób:

char *gg_sha_hash(char *password, unsigned int seed)
{
	SHA1_CTX ctx;
	static char result[20];
	  
	SHA1_Init(&ctx);  
	SHA1_Update(&ctx, password, strlen(password));
	SHA1_Update(&ctx, &seed, sizeof(seed));
	SHA1_Final(result, &ctx);

	return result;
}

Jeśli autoryzacja się powiedzie, dostaniemy w odpowiedzi pakiet:

#define GG_LOGIN80_OK 0x0035

struct gg_login80_ok {
	int unknown1;	/* 01 00 00 00 */
};

W przypadku błędu autoryzacji otrzymamy pusty pakiet:

#define GG_LOGIN_FAILED 0x0009

1.4. Zmiana stanu

Gadu-Gadu przewiduje kilka stanów klienta, które zmieniamy pakietem typu:

#define GG_NEW_STATUS80 0x0038

struct gg_new_status80 {
	int status;		/* na jaki zmienić? */
	int flags;              /* flagi (nieznane przeznaczenie) */
	int description_size;   /* rozmiar opisu */
	char description[];	/* opis (nie musi wystąpić, bez \0) */
};

Możliwe stany to:

EtykietaWartośćZnaczenie
GG_STATUS_NOT_AVAIL0x0001Niedostępny
GG_STATUS_NOT_AVAIL_DESCR0x0015Niedostępny (z opisem)
GG_STATUS_FFC0x0017PoGGadaj ze mną
GG_STATUS_FFC_DESCR0x0018PoGGadaj ze mną (z opisem)
GG_STATUS_AVAIL0x0002Dostępny
GG_STATUS_AVAIL_DESCR0x0004Dostępny (z opisem)
GG_STATUS_BUSY0x0003Zajęty
GG_STATUS_BUSY_DESCR0x0005Zajęty (z opisem)
GG_STATUS_DND0x0021Nie przeszkadzać
GG_STATUS_DND_DESCR0x0022Nie przeszkadzać (z opisem)
GG_STATUS_INVISIBLE0x0014Niewidoczny
GG_STATUS_INVISIBLE_DESCR0x0016Niewidoczny (z opisem)
GG_STATUS_BLOCKED0x0006Zablokowany
GG_STATUS80_DESCR_MASK0x0100Maska bitowa oznaczająca ustawiony opis graficzny
GG_STATUS80_DESCR_MASK0x4000Maska bitowa oznaczająca ustawiony opis
GG_STATUS_FRIENDS_MASK0x8000Maska bitowa oznaczająca tryb tylko dla przyjaciół

Należy pamiętać, żeby przed rozłączeniem się z serwerem należy zmienić stan na GG_STATUS_NOT_AVAIL lub GG_STATUS_NOT_AVAIL_DESCR. Jeśli ma być widoczny tylko dla przyjaciół, należy dodać GG_STATUS_FRIENDS_MASK do normalnej wartości stanu.

Maksymalna długość opisu wynosi 255 bajtów, jednak należy pamiętać że znak w UTF-8 czasami zajmuje więcej niż 1 bajt.


1.5. Ludzie przychodzą, ludzie odchodzą

Zaraz po zalogowaniu możemy wysłać serwerowi naszą listę kontaktów, żeby dowiedzieć się, czy są w danej chwili dostępni. Lista kontaktów jest dzielona na pakiety po 400 wpisów. Pierwsze wpisy są typu GG_NOTIFY_FIRST, a ostatni typu GG_NOTIFY_LAST, żeby serwer wiedział, kiedy kończymy. Jeśli lista kontaktów jest mniejsza niż 400 wpisów, wysyłamy oczywiście tylko GG_NOTIFY_LAST. Pakiety te zawierają struktury gg_notify:

#define GG_NOTIFY_FIRST 0x000f
#define GG_NOTIFY_LAST 0x0010
	
struct gg_notify {
	int uin;	/* numer Gadu-Gadu kontaktu */
	char type;	/* rodzaj użytkownika */
};

Gdzie pole type jest mapą bitową następujących wartości:

EtykietaWartośćZnaczenie
GG_USER_BUDDY0x01Każdy użytkownik dodany do listy kontaktów
GG_USER_FRIEND0x02Użytkownik, dla którego jesteśmy widoczni w trybie „tylko dla przyjaciół”
GG_USER_BLOCKED0x04Użytkownik, którego wiadomości nie chcemy otrzymywać

Jednak dla zachowania starego nazewnictwa stałych można używać najczęściej spotykane wartości to:

EtykietaWartośćZnaczenie
GG_USER_OFFLINE0x01Użytkownik, dla którego będziemy niedostępni, ale mamy go w liście kontaktów
GG_USER_NORMAL0x03Zwykły użytkownik dodany do listy kontaktów
GG_USER_BLOCKED0x04Użytkownik, którego wiadomości nie chcemy otrzymywać

Jeśli nie mamy nikogo na liście wysyłamy następujący pakiet o zerowej długości:

#define GG_LIST_EMPTY 0x0012

Jeśli ktoś jest, serwer odpowie pakietem GG_NOTIFY_REPLY80 zawierającym jedną lub więcej struktur gg_notify_reply80:

#define GG_NOTIFY_REPLY80 0x37
	
struct gg_notify_reply80 {
	int uin;		/* numer Gadu-Gadu kontaktu */
	int status;		/* status */
	int flags;		/* flagi (nieznane przeznaczenie) */
	int remote_ip;		/* adres IP bezpośrednich połączeń (nieużywane) */
	short remote_port;	/* port bezpośrednich połączeń (nieużywane) */
	char image_size;	/* maksymalny rozmiar obrazków w KB */
	char unknown2;		/* 0x00 */
	int unknown3;		/* 0x00000000 */
	int description_size;	/* rozmiar opisu */
	char description[];	/* opis (nie musi wystąpić, bez \0) */
};

Zdarzają się też inne „nietypowe” wartości, ale ich znaczenie nie jest jeszcze do końca znane.

Aby dodać do listy kontaktów numer w trakcie połączenia, należy wysłać niżej opisany pakiet. Jego format jest identyczny jak GG_NOTIFY_*, z tą różnicą, że zawiera jeden numer.

#define GG_ADD_NOTIFY 0x000d
	
struct gg_add_notify {
	int uin;	/* numerek */
	char type;	/* rodzaj użytkownika */
};

Poniższy pakiet usuwa z listy kontaktów:

#define GG_REMOVE_NOTIFY 0x000e
	
struct gg_remove_notify {
	int uin;	/* numerek */
	char type;	/* rodzaj użytkownika */
};

Należy zwrócić uwagę, że pakiety GG_ADD_NOTIFY i GG_REMOVE_NOTIFY dodają i usuwają flagi będące mapą bitową. Aby zmienić status użytkownika z normalnego na blokowanego, należy najpierw usunąć rodzaj GG_USER_NORMAL, a następnie dodać rodzaj GG_USER_BLOCKED.

Jeśli ktoś opuści Gadu-Gadu lub zmieni stan, otrzymamy poniższy pakiet, którego struktura jest identyczna z GG_NOTIFY_REPLY80.

#define GG_STATUS80 0x0036

1.6. Wysyłanie wiadomości

Wiadomości wysyła się następującym typem pakietu:

#define GG_SEND_MSG80 0x002d

struct gg_send_msg80 {
	int recipient;		/* numer odbiorcy */
	int seq;		/* numer sekwencyjny */
	int class;		/* klasa wiadomości */
	int offset_plain;	/* położenie treści czystym tekstem */
	int offset_attributes;	/* położenie atrybutów */
	char html_message[];	/* treść w formacie HTML (zakończona \0) */
	char plain_message[];	/* treść czystym tekstem (zakończona \0) */
	char attributes[];	/* atrybuty wiadomości */
};

Numer sekwencyjny w poprzednich wersjach protokołu był losową liczbą pozwalającą przypisać potwierdzenie do wiadomości. Obecnie jest znacznikiem czasu w postaci uniksowej (liczba sekund od 1 stycznia 1970r. UTC).

Klasa wiadomości jest mapą bitową (domyślna wartość to 0x08):

EtykietaWartośćZnaczenie
GG_CLASS_QUEUED0x0001Bit ustawiany wyłącznie przy odbiorze wiadomości, gdy wiadomość została wcześniej zakolejkowania z powodu nieobecności
GG_CLASS_MSG0x0004Wiadomość ma się pojawić w osobnym okienku (nieużywane)
GG_CLASS_CHAT0x0008Wiadomość jest częścią toczącej się rozmowy i zostanie wyświetlona w istniejącym okienku
GG_CLASS_CTCP0x0010Wiadomość jest przeznaczona dla klienta Gadu-Gadu i nie powinna być wyświetlona użytkownikowi (nieużywane)
GG_CLASS_ACK0x0020Klient nie życzy sobie potwierdzenia wiadomości

Długość treści wiadomości nie powinna przekraczać 2000 znaków. Oryginalny klient zezwala na wysłanie do 1989 znaków. Treść w formacie HTML jest kodowana UTF-8. Treść zapisana czystym tekstem jest kodowana zestawem znaków CP1250. W obu przypadkach, mimo domyślnych atrybutów tekstu, oryginalny klient dodaje informacje o formatowaniu tekstu. Dla HTML wygląda to następująco:

<span style="color:#000000; font-family:'MS Shell Dlg 2'; font-size:9pt; ">Treść</span>

Dla czystego tekstu dodawane są informacje o tym, że tekst ma kolor czarny:

BajtyOpis
0x02Flaga formatowania tekstu
0x06 0x00Długość bloku formatowania wynosi 6 bajtów
0x00 0x00Atrybut tekstu od pozycji 0
0x08Tekst kolorowy
0x00 0x00 0x00Kolor czarny

1.6.1. Konferencje

Podczas konferencji ta sama wiadomość jest wysyłana do wszystkich odbiorców, a do sekcji atrybutów dołączana jest lista pozostałych uczestników konferencji. Dla przykładu, jeśli w konferencji biorą udział Ala, Bartek, Celina i Darek, to osoba Ala wysyła wysyła do Bartka wiadomość z listą zawierającą numery Celiny i Darka, do Celiny z numerami Bartka i Darka, a do Darka z numerami Bartka i Celiny. Lista pozostałych uczestników konferencji jest przekazywana za pomocą struktury:

struct gg_msg_recipients {
	char flag;		/* 0x01 */
	int count;		/* liczba odbiorców */
	int recipients[];	/* lista odbiorców */
};

Na przykład, by wysłać wysłać do do dwóch osób, należy wysłać pakiet z wiadomością o treści:

BajtyOpis
0x01Flaga wiadomości konferencyjnej
0x02 0x00 0x00 0x00Liczba pozostałych uczestników
0xXX 0xXX 0xXX 0xXXNumer uczestnika #2
0xYY 0xYY 0xYY 0xYYNumer uczestnika #3

1.6.2. Formatowanie tekstu

Możliwe jest również dodawanie do wiadomości różnych atrybutów tekstu, jak pogrubienie czy kolory. Niezbędne jest dołączenie następującej struktury:

struct gg_msg_richtext {
	char flag;	/* 0x02 */
	short length;	/* długość dalszej części */
};

Dalsza część pakietu zawiera odpowiednią ilość struktur o łącznej długości określonej polem length:

struct gg_msg_richtext_format {
	short position;	/* pozycja atrybutu w tekście */
	char font;	/* atrybuty czcionki */
	char rgb[3];	/* kolor czcionki (nie musi wystąpić) */
	struct gg_msg_richtext_image image; /* obrazek (nie musi wystąpić) */
};

Każda z tych struktur określa kawałek tekstu począwszy od znaku określonego przez pole position (liczone od zera) aż do następnego wpisu lub końca tekstu. Pole font jest mapą bitową i kolejne bity mają następujące znaczenie:

EtykietaWartośćZnaczenie
GG_FONT_BOLD0x01Pogrubiony tekst
GG_FONT_ITALIC0x02Kursywa
GG_FONT_UNDERLINE0x04Podkreślenie
GG_FONT_COLOR0x08Kolorowy tekst. Tylko w tym wypadku struktura gg_msg_richtext_format zawiera pole rgb[] będące opisem trzech składowych koloru, kolejno czerwonej, zielonej i niebieskiej.
GG_FONT_IMAGE0x80Obrazek. Tylko w tym wypadku struktura gg_msg_richtext_format zawiera pole image.

Jeśli wiadomość zawiera obrazek, przesyłana jest jego suma kontrolna CRC32 i rozmiar. Dzięki temu nie trzeba za każdym razem wysyłać każdego obrazka — klienty je zachowują. Struktura gg_msg_richtext_image opisująca obrazek umieszczony w wiadomości wygląda następująco:

struct gg_msg_richtext_image {
	short unknown1;	/* 0x0109 */
	int size;	/* rozmiar obrazka */
	int crc32;	/* suma kontrolna obrazka */
};

Przykładowo, by przesłać tekst „ala ma kota”, należy dołączyć do wiadomości następującą sekwencję bajtów:

BajtyOpis
0x02Flaga formatowania tekstu
0x06 0x00Długość bloku formatowania wynosi 6 bajtów
0x04 0x00Atrybut tekstu od pozycji 4
0x01Tekst pogrubiony
0x06 0x00Atrybut tekstu od pozycji 6
0x00Tekst normalny

W przypadku gdy wiadomość zawiera zarówno informacje o uczestnikach konferencji, jaki i o formatowaniu, najpierw informacje o konferencji powinny znajdować się przed formatowaniem.

Jeśli obrazek jest przesyłany w wiadomości bez tekstu, jej treść powinna zawierać znak niełamliwej spacji (kod 160 w kodowaniu CP1250). W innym przypadku nowsze klienty (np. Nowe Gadu-Gadu) nie wyświetlą obrazka.

1.6.3. Przesyłanie obrazków

Gdy klient nie posiada w pamięci podręcznej obrazka o podanych parametrach, wysyła pustą wiadomość o klasie GG_CLASS_MSG z dołączoną strukturą gg_msg_image_request:

struct gg_msg_image_request {
	char flag;	/* 0x04 */
	int size;	/* rozmiar */
	int crc32;	/* suma kontrolna */
};

Przykładowa treść wiadomości z prośbą o wysłanie obrazka o długości 10000 bajtów i sumie kontrolnej 0x12345678 to:

BajtyOpis
0x04Flaga pobrania obrazka
0x10 0x27 0x00 0x00Rozmiar obrazka w bajtach
0x78 0x56 0x34 0x12Suma kontrolna

W odpowiedzi, drugi klient wysyła obrazek za pomocą wiadomości o zerowej długości (należy pamiętać o kończącym bajcie o wartości 0x00) z dołączoną strukturą gg_msg_image_reply:

struct gg_msg_image_reply {
	char flag;      	/* 0x05 lub 0x06 */
	int size;       	/* rozmiar */
	int crc32;      	/* suma kontrolna */
	char filename[];	/* nazwa pliku (nie musi wystąpić) */
	char image[];		/* zawartość obrazka (nie musi wystąpić) */
};

Jeśli długość struktury gg_msg_image_reply jest dłuższa niż 1909 bajtów, treść obrazka jest dzielona na kilka pakietów nie przekraczających 1909 bajtów. Pierwszy pakiet ma pole flag równe 0x05 i ma wypełnione pole filename, a w kolejnych pole flag jest równe 0x06 i pole filename w ogóle nie występuje (nawet bajt zakończenia ciągu znaków).

Jeśli otrzymamy pakiet bez pola filename oraz image, oznacza to, że klient nie posiada żądanego obrazka.

1.6.4. Potwierdzenie

Serwer po otrzymaniu wiadomości odsyła potwierdzenie, które przy okazji mówi nam, czy wiadomość dotarła do odbiorcy czy została zakolejkowana z powodu nieobecności. Otrzymujemy je w postaci pakietu:

#define GG_SEND_MSG_ACK 0x0005
	
struct gg_send_msg_ack {
	int status;	/* stan wiadomości */
	int recipient;	/* numer odbiorcy */
	int seq;	/* numer sekwencyjny */
};

Numer sekwencyjny i numer adresata są takie same jak podczas wysyłania, a stan wiadomości może być jednym z następujących:

EtykietaWartośćZnaczenie
GG_ACK_BLOCKED0x0001Wiadomości nie przesłano (zdarza się przy wiadomościach zawierających adresy internetowe blokowanych przez serwer GG gdy odbiorca nie ma nas na liście)
GG_ACK_DELIVERED0x0002Wiadomość dostarczono
GG_ACK_QUEUED0x0003Wiadomość zakolejkowano
GG_ACK_MBOXFULL0x0004Wiadomości nie dostarczono. Skrzynka odbiorcza na serwerze jest pełna (20 wiadomości maks). Występuje tylko w trybie offline
GG_ACK_NOT_DELIVERED0x0006Wiadomości nie dostarczono. Odpowiedź ta występuje tylko w przypadku wiadomości klasy GG_CLASS_CTCP

1.7. Otrzymywanie wiadomości

Wiadomości serwer przysyła za pomocą pakietu:

#define GG_RECV_MSG80 0x002e

struct gg_recv_msg80 {
	int sender;		/* numer nadawcy */
	int seq;		/* numer sekwencyjny */
	int time;		/* czas nadania */
	int class;		/* klasa wiadomości */
	int offset_plain;	/* położenie treści czystym tekstem */
	int offset_attributes;	/* położenie atrybutów */
	char html_message[];	/* treść w formacie HTML (zakończona \0) */
	char plain_message[];	/* treść czystym tekstem (zakończona \0) */
	char attributes[];	/* atrybuty wiadomości */
};

Czas nadania jest zapisany w postaci UTC, jako ilości sekund od 1 stycznia 1970r.

W przypadku pakietów „konferencyjnych” na końcu pakietu doklejona jest struktura identyczna z gg_msg_recipients zawierająca pozostałych rozmówców.


1.8. Ping, pong

Od czasu do czasu klient wysyła pakiet do serwera, by oznajmić, że połączenie jeszcze jest utrzymywane. Jeśli serwer nie dostanie takiego pakietu w przeciągu 5 minut, zrywa połączenie. To, czy klient dostaje odpowiedź zmienia się z wersji na wersję, więc najlepiej nie polegać na tym.

#define GG_PING 0x0008

#define GG_PONG 0x0007

1.9. Rozłączenie

Jeśli serwer zechce nas rozłączyć, wyśle wcześniej pusty pakiet:

#define GG_DISCONNECTING 0x000b

Ma to miejsce, gdy próbowano zbyt wiele razy połączyć się z nieprawidłowym hasłem (wtedy pakiet zostanie wysłany w odpowiedzi na GG_LOGIN70), lub gdy równocześnie połączy się drugi klient z tym samym numerem (nowe połączenie ma wyższy priorytet).

W nowych wersjach protokołu (prawdopodobnie od 0x29), po wysłaniu pakietu zmieniającego status na niedostępny, serwer przysyła pakiet:

#define GG_DISCONNECT_ACK 0x000d

Jest to potwierdzenie, że serwer odebrał pakiet zmiany stanu i klient może zakończyć połączenie mając pewność, że zostanie ustawiony żądany opis.


1.10. Wiadomości systemowe

Od wersji 7.7 serwer może wysyłać nam wiadomości systemowe przy pomocy pakietu:

#define GG_XML_EVENT 0x0027

Wiadomość systemowa zawiera kod XML zakodowany w UTF-8 z informacjami dotyczącymi np. przedłużenia konta w mobilnym GG, czy nowej wiadomości na poczcie głosowej. Przykładowy kod:

<?xml version="1.0" encoding="utf-8"?>
<event xmlns:ev="www.gadu-gadu.pl/Event/1.0" id ="" type="realtime" creation_time="1194732873" ttl="60">
  <ev:actions>
    <ev:showMessage>
      <ev:text>Wejdź na stronę EKG</ev:text>

      <ev:executeHtml url="ekg.chmurka.net" />
   </ev:showMessage>
  </ev:actions>
</event>

1.11. Wiadomości GG_XML_ACTION

#define GG_XML_ACTION 0x002c

1.11.1 Wiadomości GGLive

Opisać usługi http://life.gadu-gadu.pl/
Logowanie OAuth: /login?oauth_consumer_key=UIN&oauth_nonce=....&oauth_signature=...&oauth_signature_method=HMAC-SHA1&oauth_timestamp=...&oauth_token=....&oauth_version=1.0
Wysyłanie: POST /send/message/?USER_IS_AUTHENTICATED=1&uin=UIN&token=TOKEN
message=Testowa+wiadomo%C5%9B%C4%87&send=Wy%C5%9Blij

Przykładowa otrzymana wiadomość:

<events>
  <event id="13106118792229117994">
  <type>1</type>
  <sender>7496195</sender>
  <time>1243461221</time>
  <bodyXML>
    <serviceID>lifestreaming</serviceID>
    <msg><![CDATA[Testowa wiadomość]]></msg>
    <link isLogin="0"></link>
    <creationTime>1243461221</creationTime>
  </bodyXML>
 </event>
</events>

1.11.2 Zmiana avatara przez znajomego

Przykładowa informacja:

<events>
  <event id="13095886332244853765">
    <type>28</type>
    <sender>3732</sender>
    <time>1245843651</time>
    <body></body>
    <bodyXML>
      <smallAvatar>http://media6.mojageneracja.pl/oiytwyurtp/avatar/ueuivsp.jpg</smallAvatar>
    </bodyXML>
  </event>
</events>

1.11.3 Nowy wpis na blogu znajomego

Przykładowa informacja:

<events>
  <event id="13095868082578904423">
    <type>7</type>
    <sender>3732</sender>
    <time>1245847900</time>
    <bodyXML>
      <serviceID>MG</serviceID>
      <msg><![CDATA[Doda\u0139, wpis do bloga]]></msg>
      <link isLogin="1">http://www.mojageneracja.pl/7233258/blog/4877775414a42215b91fd7/0</link>
      <creationTime>1245847900</creationTime>
    </bodyXML>
 </event>
</events>

1.11.4 Opisy graficzne

Osobny rozdział XXX?

Serwer Gadu-Gadu po kupnie opisu graficznego na stronie GaduDodatki przesyła nam pakiet GG_XML_EVENT

Przykładowy opis graficzny: Krol Popu

<?xml version="1.0" encoding="utf-8" ?>
<activeUserbarEventList>
  <activeUserbarEvent>
     <userbarId>Krol Popu</userbarId>
     <beginTime>2009-07-06T12:30:43+02:00</beginTime>
     <expireTime>2009-08-05T12:30:43+02:00</expireTime>
     <userbarOwner>7496195</userbarOwner>
     <userbarBuyer>7496195</userbarBuyer>
   </activeUserbarEvent>
</activeUserbarEventList>

Użytkownik powinien zostać zapytany czy chce ustawić ten opis i jeśli tak, to wysyłany jest pakiet GG_NEW_STATUS80

Przykładowe ustawienie opisu graficznego: Krol Popu

struct gg_new_status80 krol_popu = { 
	.status           = GG_STATUS80_DESCR_MASK | GG_STATUS80_GRAPH_MASK | docelowy_opisowy_status; /* 0x4100 | opis */
	.flags            = 0x03;
	.description_size = 9;
	.description      = "Krol Popu"
};

Gdy użytkownik ma ustawiony opis graficzny (.status & GG_STATUS80_GRAPH_MASK) możemy pobrać ZIP-paczkę z http://www.gadudodatki.pl/userbar/get/id/

Dla przykładowego Króla Popu jest to adres: http://www.gadudodatki.pl/userbar/get/id/Krol%20Popu


1.12. Katalog publiczny

Nowe Gadu-Gadu korzysta z OAutha do odczytu oraz zmian danych w katalogu, API opisane jest na: http://dev.gadu-gadu.pl/api/pages/gaduapi.html

Nowe Gadu-Gadu korzysta z wyszukiwarki dostępnej na: http://ipubdir.gadu-gadu.pl

Od wersji 5.0.2 zmieniono sposób dostępu do katalogu publicznego — stał się częścią sesji, zamiast osobnej sesji HTTP. Aby obsługiwać wyszukiwanie osób, odczytywanie własnych informacji lub ich modyfikację należy użyć następującego typu pakietu:

#define GG_PUBDIR50_REQUEST 0x0014
	
struct gg_pubdir50 {
	char type;
	int seq;
	char request[];
};

Pole type oznacza rodzaj zapytania:

#define GG_PUBDIR50_WRITE 0x01
#define GG_PUBDIR50_READ 0x02
#define GG_PUBDIR50_SEARCH 0x03

Pole seq jest numerem sekwencyjnym zapytania, różnym od zera, zwracanym również w wyniku. Oryginalny klient tworzy go na podstawie aktualnego czasu. request zawiera parametry zapytania. Ilość jest dowolna. Każdy parametr jest postaci "nazwa\0wartość\0", tzn. nazwa od wartości są oddzielone znakiem o kodzie 0, podobnie jak kolejne parametry od siebie. Możliwe parametry zapytania to:

EtykietaWartośćZnaczenie
GG_PUBDIR50_UINFmNumberNumer szukanej osoby
GG_PUBDIR50_FIRSTNAMEfirstnameImię
GG_PUBDIR50_LASTNAMElastnameNazwisko
GG_PUBDIR50_NICKNAMEnicknamePseudonim
GG_PUBDIR50_BIRTHYEARbirthyearRok urodzenia. Jeśli chcemy szukać osób z danego przedziału, podajemy rok początkowy i końcowy, oddzielone spacją. Na przykład „1980 1985”.
GG_PUBDIR50_CITYcityMiejscowość
GG_PUBDIR50_GENDERgenderPłeć. Jeśli szukamy kobiet, ma wartość „1” (stała GG_PUBDIR50_GENDER_FEMALE). Jeśli mężczyzn, ma wartość „2” (stała GG_PUBDIR50_GENDER_MALE). W przypadku pobierania lub ustawiania informacji o sobie stałe mają odwrócone znaczenia (stałe GG_PUBDIR50_GENDER_SET_FEMALE i GG_PUBDIR50_GENDER_SET_MALE)
GG_PUBDIR50_ACTIVEActiveOnlyJeśli szukamy tylko dostępnych osób, ma mieć wartość „1” (stała GG_PUBDIR50_ACTIVE_TRUE).
GG_PUBDIR50_FAMILYNAMEfamilynameNazwisko panieńskie. Ma znaczenie tylko przy ustawianiu własnych danych.
GG_PUBDIR50_FAMILYCITYfamilycityMiejscowość pochodzenia. Ma znaczenie tylko przy ustawianiu własnych danych.
GG_PUBDIR50_STARTfmstartNumer, od którego rozpocząć wyszukiwanie. Ma znaczenie, gdy kontynuujemy wyszukiwanie.

Treść przykładowego zapytania (pomijając pola type i seq) znajduje się poniżej. Szukano dostępnych kobiet o imieniu Ewa z Warszawy. Znaki o kodzie 0 zastąpiono kropkami.

firstname.Ewa.city.Warszawa.gender.1.ActiveOnly.1.

Wynik zapytania zostanie zwrócony za pomocą pakietu:

#define GG_PUBDIR50_REPLY 0x000e
	
struct gg_pubdir50_reply {
	char type;
	int seq;
	char reply[];
};

Pole type poza wartościami takimi jak przy pakiecie typu GG_PUBDIR50_REQUEST może przyjąć jeszcze wartość oznaczającą odpowiedź wyszukiwania:

#define GG_PUBDIR50_SEARCH_REPLY 0x05

Wyniki są zbudowane identycznie jak w przypadku zapytań, z tą różnicą, że kolejne osoby oddzielane pustym polem: "parametr\0wartość\0\0parametr\0wartość\0".

EtykietaWartośćZnaczenie
GG_PUBDIR50_STATUSFmStatusStan szukanej osoby
 nextstartPole występujące w ostatnim wyniku, określające, od jakiego numeru należy rozpocząć wyszukiwanie, by otrzymać kolejną porcję danych. Podaje się go w zapytaniu jako parametr „start”.

Przykładowy wynik zawierający dwie znalezione osoby:

FmNumber.12345.FmStatus.1.firstname.Adam.nickname.Janek.birthyear.1979.city.Wzdów
..FmNumber.3141592.FmStatus.5.firstname.Ewa.nickname.Ewcia.birthyear.1982.city.Gd
dańsk..nextstart.0.

Wyszukiwanie nie zwraca nazwisk i płci znalezionych osób.


1.13. Lista kontaktów

Sprawdzić czy wszystkie #define dalej są potrzebne

Od wersji 6.0 lista kontaktów na serwerze stała częścią sesji, zamiast osobnej sesji HTTP. Aby wysłać lub pobrać listę kontaktów z serwera należy użyć pakietu:

#define GG_USERLIST_REQUEST80 0x002f
	
struct gg_userlist_request {
	char type;		/* rodzaj zapytania */
	char request[];		/* treść (nie musi wystąpić) */
};

Pole type oznacza rodzaj zapytania:

#define GG_USERLIST_PUT 0x00            /* początek eksportu listy */
#define GG_USERLIST_PUT_MORE 0x01       /* dalsza część eksportu listy */
#define GG_USERLIST_GET 0x02            /* import listy */

W przypadku eksportu listy kontaktów, pole request zawiera dokument XML opisany na stronie http://dev.gadu-gadu.pl/api/pages/formaty_plikow.html skompresowany algorytmem Deflate. Wolnodostępna implementacja algorytmu, używana również przez oryginalnego klienta, znajduje się w biblotece zlib.

Podczas przesyłania lista kontaktów jest dzielona na pakiety po 2048 bajtów. Pierwszy jest wysyłany pakietem typu GG_USERLIST_PUT, żeby uaktualnić plik na serwerze, pozostałe typu GG_USERLIST_PUT_MORE, żeby dopisać do pliku.

Na zapytania dotyczące listy kontaktów serwer odpowiada pakietem:

#define GG_USERLIST_REPLY80 0x0030
	
struct gg_userlist_reply {
	char type;		/* rodzaj zapytania */
	char reply[];		/* treść (nie musi wystąpić) */
};

Pole type oznacza rodzaj odpowiedzi:

#define GG_USERLIST_PUT_REPLY 0x00         /* początek eksportu listy */
#define GG_USERLIST_PUT_MORE_REPLY 0x02    /* kontynuacja */
#define GG_USERLIST_GET_MORE_REPLY 0x04    /* początek importu listy */
#define GG_USERLIST_GET_REPLY 0x06         /* ostatnia część importu */

W przypadku importu w polu request znajdzie się lista kontaktów w takiej samej postaci, w jakiej ją umieszczono. Serwer nie ingeruje w jej treść. Podobnie jak przy wysyłaniu, przychodzi podzielona na mniejsze pakiety. Pobieranie krótkiej listy kontaktów zwykle powoduje wysłanie pojedynczego pakietu GG_USERLIST_GET_REPLY, a gdy lista jest długa, serwer może przysłać dowolną ilość pakietów GG_USERLIST_GET_MORE_REPLY przed pakietem GG_USERLIST_GET_REPLY.

Aby usunąć listę kontaktów z serwera oryginalny klient wysyła spację jako listę kontaktów czego wynikiem jest pole request o zawartości:

78 da 53 00 00 00 21 00 21

1.14. Indeks pakietów

Pakiety wysyłane:

WartośćEtykietaZnaczenie
0x0002GG_NEW_STATUSZmiana stanu przed GG 8.0
0x0007GG_PONGPong
0x0008GG_PINGPing
0x000bGG_SEND_MSGWysłanie wiadomości przed GG 8.0
0x000cGG_LOGINLogowanie przed GG 6.0
0x000dGG_ADD_NOTIFYDodanie do listy kontaktów
0x000eGG_REMOVE_NOTIFYUsunięcie z listy kontaktów
0x000fGG_NOTIFY_FIRSTPoczątkowy fragment listy kontaktów większej niż 400 wpisów
0x0010GG_NOTIFY_LASTOstatni fragment listy kontaktów
0x0012GG_LIST_EMPTYLista kontaktów jest pusta
0x0013GG_LOGIN_EXTLogowanie przed GG 6.0
0x0014GG_PUBDIR50_REQUESTZapytanie katalogu publicznego
0x0015GG_LOGIN60Logowanie przed GG 7.7
0x0016GG_USERLIST_REQUESTZapytanie listy kontaktów na serwerze przed Nowym Gadu-Gadu
0x0019GG_LOGIN70Logowanie przed GG 8.0
0x001fGG_DCC7_INFO
0x0020GG_DCC7_NEWInformacje o chęci nawiązania połączenia DCC
0x0021GG_DCC7_ACCEPTZaakceptowanie połączenia DCC
0x0022GG_DCC7_REJECTOdrzucenie połączenia DCC
0x0023GG_DCC7_ID_REQUEST
0x0024GG_DCC7_DUNNO1
0x0025GG_DCC7_ABORT
0x0028GG_NEW_STATUS80BETAZmiana stanu przed Nowym Gadu-Gadu
0x0029GG_LOGIN80BETALogowanie przed Nowym Gadu-Gadu
0x002dGG_SEND_MSG80Wysłanie wiadomości
0x002fGG_USERLIST_REQUEST80Zapytanie listy kontaktów na serwerze
0x0031GG_LOGIN80Logowanie
0x0038GG_NEW_STATUS80Zmiana stanu

Pakiety odbierane:

WartośćEtykietaZnaczenie
0x0001GG_WELCOMELiczba do wyznaczenie hashu hasła
0x0002GG_STATUSZmiana stanu przed GG 6.0
0x0003GG_LOGIN_OKLogowanie powiodło się przed Nowym Gadu-Gadu
0x0005GG_SEND_MSG_ACKPotwierdzenie wiadomości
0x0007GG_PONGPong
0x0008GG_PINGPing
0x0009GG_LOGIN_FAILEDLogowanie nie powiodło się
0x000aGG_RECV_MSGPrzychodząca wiadomość przed GG 8.0
0x000bGG_DISCONNECTINGZerwanie połączenia
0x000cGG_NOTIFY_REPLYStan listy kontaktów przed GG 6.0
0x000dGG_DISCONNECT_ACKZerwanie połączenia po zmianie stanu na niedostępny
0x000eGG_PUBDIR50_REPLYOdpowiedź katalogu publicznego
0x000fGG_STATUS60Zmiana stanu przed GG 7.7
0x0010GG_USERLIST_REPLYOdpowiedź listy kontaktów na serwerze przed nowym Gadu-Gadu
0x0011GG_NOTIFY_REPLY60Stan listy kontaktów przed GG 7.7
0x0014GG_NEED_EMAILLogowanie powiodło się, ale powinniśmy uzupełnić adres e-mail w katalogu publicznym
0x0016GG_LOGIN_HASH_TYPE_INVALIDDany rodzaj hashowania hasła jest nieobsługiwany przez serwer
0x0017GG_STATUS77Zmiana stanu przed GG 8.0
0x0018GG_NOTIFY_REPLY77Stan listy kontaktów przed GG 8.0
0x001fGG_DCC7_INFO
0x0020GG_DCC7_NEWInformacje o chęci nawiązania połączenia DCC
0x0021GG_DCC7_ACCEPTZaakceptowanie połączenia DCC
0x0022GG_DCC7_REJECTOdrzucenie połączenia DCC
0x0023GG_DCC7_ID_REPLY
0x0025GG_DCC7_ABORTED
0x0027GG_XML_EVENTOdebrano wiadomość systemową
0x002aGG_STATUS80BETAZmiana stanu przed Nowym Gadu-Gadu
0x002bGG_NOTIFY_REPLY80BETAStan listy kontaktów przed Nowym Gadu-Gadu
0x002cGG_XML_ACTION
0x002eGG_RECV_MSG80Przychodząca wiadomość
0x0030GG_USERLIST_REPLY80Odpowiedź listy kontaktów na serwerze
0x0035GG_LOGIN_OK80Logowanie powiodło się
0x0036GG_STATUS80Zmiana stanu
0x0037GG_NOTIFY_REPLY80Stan listy kontaktów

2. Usługi HTTP

2.1. Format danych

Komunikacja z appmsg.gadu-gadu.pl metodą GET HTTP/1.0 została opisana w poprzednim rozdziale, pozostałe pakiety używają POST dla HTTP/1.0, a w odpowiedzi 1.1. Mają one postać:

POST ŚCIEŻKA HTTP/1.0
Host: HOST
Content-Type: application/x-www-form-urlencoded
User-Agent: AGENT
Content-Length: DŁUGOŚĆ
Pragma: no-cache

DANE

Gdzie AGENT to nazwa przeglądarki (na przykład Mozilla/4.0 (compatible; MSIE 5.0; Windows 98) lub inne, wymienione w rozdziale 1.2), DŁUGOŚĆ to długość bloku DANE w znakach.

Jeśli będzie mowa o wysyłaniu danych do serwera, to chodzi o cały powyższy pakiet, opisane zostaną tylko: HOST, ŚCIEŻKA i DANE. Pakiet jest wysyłany na port 80. Gdy mowa o wysyłaniu pól zapytania, mowa o DANE o wartości:

pole1=wartość1&pole2=wartość2&...

Pamiętaj o zmianie kodowania na CP1250 i zakodowaniu danych do postaci URL (na przykład funkcją typu urlencode).

Odpowiedzi serwera na powyższe zapytania mają mniej więcej postać:

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Mon, 01 Jul 2002 22:30:31 GMT
Connection: Keep-Alive
Content-Length: DŁUGOŚĆ
Content-Type: text/html
Set-Cookie: COOKIE
Cache-control: private

ODPOWIEDŹ

Nagłówki nie są dla nas ważne. Można zauważyć tylko to, że czasami serwer ustawia COOKIE np. „ASPSESSIONIDQQGGGLJC=CAEKMBGDJCFBEOKCELEFCNKH; path=/”. Pisząc dalej, że serwer „odpowie wartością” mowa tylko o polu ODPOWIEDŹ. Kodowanie znaków w odpowiedzi to CP1250.


2.2. Tokeny

Prawdopodobnie ze względu na nadużycia i wykorzystywanie automatów rejestrujących do polowań na „złote numery GG”, wprowadzono konieczność autoryzacji za pomocą tokenu. Każda operacja zaczyna się od pobrania tokenu z serwera, wyświetlenia użytkownikowi, odczytaniu jego wartości i wysłania zapytania z identyfikatorem i wartością tokenu. Pobranie tokenu wygląda następująco:

Pole nagłówkaWartość
HOSTregister.gadu-gadu.pl
ŚCIEŻKA/appsvc/regtoken.asp

Nie są wysyłane żadne parametry. Przykład:

POST /appsvc/regtoken.asp HTTP/1.0
Host: register.gadu-gadu.pl
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 98)
Content-Length: 0
Pragma: no-cache

Serwer w odpowiedzi odeśle:

SZEROKOŚĆ WYSOKOŚĆ DŁUGOŚĆ
IDENTYFIKATOR
ŚCIEŻKA

Gdzie SZEROKOŚĆ i WYSOKOŚĆ opisują wymiary obrazka z wartością tokenu, DŁUGOŚĆ mówi ile znaków zawiera token, IDENTYFIKATOR jest identyfikatorem tokenu (tylko do niego pasuje wartość tokenu), a ŚCIEŻKA to ścieżka do skryptu zwracającego obrazek z wartością tokenu. Przykładowa odpowiedź:

60 24 6
06C05A44
http://register.gadu-gadu.pl/appsvc/tokenpic.asp

Możemy teraz pobrać metodą GET z podanej ścieżki obrazek z tokenem, doklejając do ścieżki parametr tokenid o wartości będącej identyfikatorem uzyskanym przed chwilą. Adres obrazka z wartością tokenu dla powyższego przykładu to:

http://register.gadu-gadu.pl/appsvc/tokenpic.asp?tokenid=06C05A44

Pobrany obrazek (w tej chwili jest w formacie JPEG, ale prawdopodobnie może się to zmienić na dowolny format obsługiwany domyślnie przez system Windows) najlepiej wyświetlić użytkownikowi, prosząc o podanie wartości na nim przedstawionej. Będzie ona niezbędna do przeprowadzenia kolejnych operacji.


2.3. Rejestracja konta

Pole nagłówkaWartość
HOSTregister.gadu-gadu.pl
ŚCIEŻKA/appsvc/fmregister3.asp

Wysyłamy poleZnaczenie
pwdhasło dla nowego numeru
emaile-mail na który będzie przesyłane przypomnienie hasła
tokenididentyfikator tokenu
tokenvalwartość tokenu
codehash liczony z pól email i pwd. Algorytmu szukaj w źródłach libgadu w lib/common.c

Przykład:

POST /appsvc/fmregister3.asp HTTP/1.0
Host: register.gadu-gadu.pl
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 98)
Content-Length: 76
Pragma: no-cache
		
pwd=sekret&email=abc@xyz.pl&tokenid=06C05A44&tokenval=e94d56&code=1104465363

Jeśli wszystko przebiegło poprawnie, serwer odpowie:

Tokens okregisterreply_packet.reg.dwUserId=UIN

Gdzie UIN to nowy numer, który właśnie otrzymaliśmy.

Jeśli został podany nieprawidłowy token, serwer odpowie:

bad_tokenval

2.4. Usunięcie konta

Pole nagłówkaWartość
HOSTregister.gadu-gadu.pl
ŚCIEŻKA/appsvc/fmregister3.asp

Wysyłamy poleZnaczenie
fmnumberusuwany numer
fmpwdhasło
deletewartość „1
pwdlosowa liczba
emailwartość „deletedaccount@gadu-gadu.pl
tokenididentyfikator tokenu
tokenvalwartość tokenu
codehash liczony z pól pwd i email

Przykład:

POST /appsvc/fmregister2.asp HTTP/1.0
Host: register.gadu-gadu.pl
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 98)
Content-Length: 137
Pragma: no-cache
		
fmnumber=4969256&fmpwd=haslo&delete=1&email=deletedaccount@gadu-gadu.pl&pwd=%2D38
8046464&tokenid=06C05A44&tokenval=e94d56&code=1483497094

Jeśli wszystko przebiegło poprawnie, serwer odpowie:

reg_success:UIN

Gdzie UIN to numer, który skasowaliśmy.


2.5. Zmiana hasła

Pole nagłówkaWartość
HOSTregister.gadu-gadu.pl
ŚCIEŻKA/appsvc/fmregister3.asp

Wysyłamy poleZnaczenie
fmnumbernumer
fmpwdstare hasło
pwdnowe hasło
emailnowe adres e-email
tokenididentyfikator tokenu
tokenvalwartość tokenu
codehash liczony z pól pwd i email

Jeśli wszystko przebiegło poprawnie, serwer odpowie:

reg_success:UIN

2.6. Przypomnienie hasła pocztą

Pole nagłówkaWartość
HOSTretr.gadu-gadu.pl
ŚCIEŻKA/appsvc/fmsendpwd3.asp

Wysyłamy poleZnaczenie
useridnumer
tokenididentyfikator tokenu
tokenvalwartość tokenu
codehash liczony z pola userid

Jeśli się udało, serwer odpowie:

pwdsend_success

3. Połączenia bezpośrednie

3.1. Nawiązanie połączenia

Połączenia bezpośrednie pozwalają przesyłać pliki lub prowadzić rozmowy głosowe bez pośrednictwa serwera. Początkowe wersje Gadu-Gadu potrafiły przesyłać bezpośrednio również wiadomości tekstowe, ale funkcjonalność ta została zarzucona.

Dla każdego połączenia musimy zdobyć od serwera 8 bajtowy identyfikator. Aby pobrać identyfikator należy użyć pakietu:

#define GG_DCC7_ID_REQUEST 0x0023

struct gg_dcc7_id_request {
	int type;		/* rodzaj transmisji */
};

Pole type oznacza rodzaj transmisji:

#define GG_DCC7_TYPE_VOICE 0x00000001	/* Rozmowa głosowa (już nieużywane) */
#define GG_DCC7_TYPE_FILE 0x00000004	/* Przesyłanie plików */

Na co serwer odpowie:

#define GG_DCC7_ID_REPLY 0x0023

struct gg_dcc7_id_reply {
	int type;	/* Rodzaj transmisji */
	long long id;	/* przyznany identyfikator */
};

3.2. Przesyłanie plików

W rodzaju transmisji (type) GG_DCC7_TYPE_FILE

3.2.1 GG_DCC7_TYPE_FILE - Jak powiadamiać, jak akceptować oraz jak odrzucać

Aby powiadomić o chęci przesłania pliku, należy wysłać następujący pakiet.

#define GG_DCC7_NEW 0x0020

struct gg_dcc7_new {
	long long id;		/* identyfikator połączenia */
	int uin_from;		/* numer nadawcy */
	int uin_to;		/* numer odbiorcy */
	int type;		/* rodzaj transmisji */
	char filename[255];	/* nazwa pliku */
	long long size;		/* rozmiar pliku */
	char hash[20];		/* hash SHA1 (już nieużywane 00 00 00) */
};

Strona wywoływana po otrzymaniu pakietu GG_DCC7_NEW, może zaakceptować pobieranie pliku, wysyła pakiet:

#define GG_DCC7_ACCEPT 0x0021

struct gg_dcc7_accept {
	int uin;	/* numer przyjmującego połączenie */
	long long id;	/* identyfikator połączenia */
	int offset;	/* offset przy wznawianiu transmisji */
	int dunno1;	/* 0x00000000 (na 99% kontynuacja offsetu) */
};

Jeśli plik został już częściowo odebrany i chcemy wznowić przesyłanie, w polu offset wystarczy podać ile bajtów już mamy, a odebrane dane dopisać na końcu pliku.

Jeśli strona wywołana chce odrzucić plik wysyła pakiet:

#define GG_DCC7_REJECT 0x0022

struct gg_dcc7_reject {
	int uin;	/* Numer odrzucającego połączenie */
	long long id;	/* Identyfikator połączenia */
	int reason;	/* Powód rozłączenia */
};

Dla pola reason znane są wartości:

#define GG_DCC7_REJECT_BUSY	0x00000001	/* Połączenie bezpośrednie już trwa, nie umiem obsłużyć więcej */
#define GG_DCC7_REJECT_USER	0x00000002	/* Użytkownik odrzucił połączenie */
#define GG_DCC7_REJECT_VERSION	0x00000006	/* Druga strona ma wersję klienta nieobsługującą połączeń bezpośrednich tego typu */

Przed akceptacją pliku przez stronę wywoływaną, użytkownik może przerwać żądanie wysyłając pakiet:

#define GG_DCC7_ABORT 0x0025
struct gg_dcc7_abort {
	long long id;		/* identyfikator połączenia */
	int uin_from;		/* numer nadawcy */
	int uin_to;		/* numer odbiorcy */
};

Strona wywoływana w takim przypadku powinna otrzymać pakiet:

#define GG_DCC7_ABORTED 0x0025
struct gg_dcc7_aborted {
	long long id;		/* identyfikator połączenia */
};

Po zaakceptowaniu pliku, obie strony zaczynają nasłuchiwać na losowo wybranym porcie i wysyłają pakiet GG_DCC7_INFO z informacjami potrzebnymi do połączenia.

3.2.2 relay.gadu-gadu.pl - 91.197.13.102 albo tajemniczy host w podsieci 91.197.12.0/22

Oba hosty łączą się również z relay.gadu-gadu.pl:80 aby uzyskać listę serwerów które mogą pośredniczyć w wymianie plików.

#define GG_DCC7_RELAY_REQUEST 0x0a
struct gg_dcc7_relay_req {
	int magic;	/* 0x0a */
	int len;	/* długość całego pakietu */
	long long id;	/* identyfikator połączenia */
	short dunno1;	/* 0x01 0x00 */
	short dunno2;	/* 0x02 0x00 */
};
Czy wysyła zapytania DNS o relay.gadu-gadu.pl U mnie łączy się z 91.197.13.102, zapytań nie widziałem (cache?)
Tak naprawdę z relay.gadu-gadu.pl łączą się dwa razy. Za pierwszym razem łączą się wysyłając w dunno1: 08 00. Odpowiada też dwoma rekordami, ale w port jest 00 00

Przykładowe pytanie o serwery dla połączenia 0x160600000bd4

0000  0a 00 00 00 14 00 00 00 d4 0b 00 00 06 16 00 00
0010  01 00 02 00

Serwer odpowiada:

#define GG_DCC7_RELAY_REPLY 0x0b
struct gg_dcc7_relay_reply {
	int magic;	/* 0x0b */
	int len;	/* długość całego pakietu */
	int rcount;	/* prawdopodobnie ilość pośredniczących serwerów */
	struct {
		int ip;		/* adres ip serwera */
		short port;	/* port serwera */
		char family;	/* rodzina adresów (na końcu?!) AF_INET=2 */
	} proxies[rcount];
};

Przykładowa odpowiedź serwera zawierająca 2 rekordy:

  1. 91.197.13.104:80
  2. 91.197.13.104:443
0000  0b 00 00 00 1a 00 00 00 02 00 00 00 5b c5 0d 68
0010  50 00 02 5b c5 0d 68 bb 01 02

3.2.3 GG_DCC7_INFO - Jak się odnaleźć w mroku

#define GG_DCC7_INFO 0x001f

struct gg_dcc7_info {
	int uin;	/* numer nadawcy */
	int type;	/* sposób połączenia */
	long long id;	/* identyfikator połączenia */
	char info[64];	/* informacje o połączeniu */
};
Rodzielić info na info1, info2

W polu type sposób połączenia:

#define GG_DCC7_TYPE_P2P 0x00000001	/* Połączenie bezpośrednie */
#define GG_DCC7_TYPE_SERVER 0x00000002	/* Połączenie przez serwer */

Dla połączeń bezpośrednich:

  • pierwsze 32bajty pola info to IP <SPACJA> PORT
  • drugie 32bajty pola info to ip oraz port w innej postaci, niestety nie mamy informacji o algorytmie :)

Przykładowa zawartość pola info dla 10.0.0.2:22563

0000   31 30 2e 30 2e 30 2e 32 20 32 32 35 36 33 00 00  10.0.0.2 22563..
0010   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
0020   31 37 36 34 36 38 34 38 34 00 00 00 00 00 00 00  176468484.......
0030   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................

Po udanym połączeniu na podany adres w GG_DCC7_INFO wysyłamy pakiet powitalny:

struct gg_dcc7_welcome_p2p {
	long long id;	/* identyfikator połączenia */
};

Druga strona powinna odpowiedzieć tym samym. Teraz już możemy albo wysyłać albo odbierać plik.

Z powodu tego że obie strony łączą się w tym samym momencie możliwy jest wyścig. Z tego co zauważyłem gdy jednak ze stron zorientuje się że na innym połączeniu dostaliśmy już ten id, to połączenie jest zrywane - ale czy taki sposób rozwiązywania nie powoduje możliwych wyścigów?

Dla połączeń przez serwer:
- pierwsze 32bajty pola info to GGidCHnumerek

Gdzie:
id to identyfikator połączenia zapisany w cyferkach ASCII
numerek TBD

GG7.7 wysyła: GGidSHnumerek
Protokół jest inny, i raczej nie będzie działać.

Przykładowa zawartość pola info dla połączenia 0x00000a0600000b27

$ echo 'ibase=16; 00000A0600000B27' | bc
11020886084391

0000   47 47 31 31 30 32 30 38 38 36 30 38 34 33 39 31  GG11020886084391
0010   43 48 36 39 36 32 00 00 00 00 00 00 00 00 00 00  CH6962..........
0020   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
0030   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................

Po połączeniu do serwera pośredniczącego wysyłamy pakiet powitalny:

struct gg_dcc7_welcome_server {
	int dunno1;	/* 0xc0debabe */
	long long id;	/* identyfikator połączenia */
};

Serwer powinien odpowiedzieć tym samym. Teraz już możemy albo wysyłać albo odbierać plik.


3.3. Rozmowy głosowe

ZTCP to leci po SIP

Aby powiadomić o chęci rozmowy głosowej należy wysłać pakiet:

#define GG_DCC_REQUEST_VOICE 0x0002

struct gg_dcc_request {
	int type;	/* GG_DCC_REQUEST_VOICE */
};

Strona wywołana może potwierdzić chęć przeprowadzenia rozmowy za pomocą pakietu:

#define GG_DCC_VOICE_ACK 0x01

struct gg_dcc_voice_ack {
	char type;	/* GG_DCC_VOICE_ACK */
};

Jeśli strona wywołana chce odrzucić rozmowę głosową, zrywa połączenie. Mimo tego, strona wywołująca nie powinna ignorować wartości potwierdzenia.

Następnie przesyłane są próbki dźwiękowe kodowane microsoftowym wariantem GSM. Pod systemem Windows wystarczy użyć standardowego kodeka, pod innymi można skorzystać z biblioteki libgsm z opcją WAV49. Pakiet danych wygląda następująco:

#define GG_DCC_VOICE_DATA 0x03

struct gg_dcc_voice_data {
	char type;	/* GG_DCC_VOICE_DATA */
	int length;	/* długość pakietu */
	char data[];	/* dane */
};

W celu zakończenia rozmowy głosowej, zamiast powyższej ramki wysyła się:

#define GG_DCC_VOICE_TERMINATE 0x04

struct gg_dcc_voice_terminate {
	char type;	/* GG_DCC_VOICE_TERMINATE */
};

Do wersji 5.0.5 w jednym pakiecie było umieszczone 6 ramek GSM (6 * 32,5 = 195 bajtów), a począwszy od tej wersji przesyła się po 10 ramek GSM, poprzedzając je bajtem zerowym (1 + 10 * 32,5 = 326 bajtów).


4. Autorzy

Lista autorów tego tekstu znajduje się poniżej. Ich adresy e-mail nie służą do zadawania pytań o podstawy programowania albo jak się połączyć z serwerem i co zrobić dalej. Jeśli masz pytania dotyczące protokołu, napisz na listę dyskusyjną libgadu-devel.

  • Wojtek Kaniewski (wojtekka%irc.pl): pierwsza wersja opisu, poprawki, utrzymanie wszystkiego w porządku.
  • Robert J. Woźny (speedy%atman.pl): opis nowości w protokole GG 4.6, poprawki.
  • Tomasz Jarzynka (tomee%cpi.pl): badanie timeoutów.
  • Adam Ludwikowski (adam.ludwikowski%wp.pl): wiele poprawek, wersje klientów, rozszerzone wiadomości, powody nieobecności.
  • Marek Kozina (klith%hybrid.art.pl): czas otrzymania wiadomości.
  • Rafał Florek (raf%regionet.regionet.pl): opis połączeń konferencyjnych.
  • Igor Popik (igipop%wsfiz.edu.pl): klasy wiadomości przy odbieraniu zakolejkowanej.
  • Rafał Cyran (ajron%wp.pl): informacje o remote_port, rodzaje potwierdzeń przy ctcp, GG_LOGIN_EXT.
  • Piotr Mach (pm%gadu-gadu.com): ilość kontaktów, pełna skrzynka, pusta lista, maska audio, usługi HTTP, GG_LOGIN_EXT.
  • Adam Czyściak (acc%interia.pl): potwierdzenie wiadomości GG_CLASS_ACK.
  • Kamil Dębski (kdebski%kki.net.pl): czas w stanach opisowych.
  • Paweł Piwowar (alfapawel%go2.pl): format czasu.
  • Tomasz Chiliński (chilek%chilan.com): nowości w 5.0.2.
  • Radosław Nowak (rano%ranosoft.net): uzupełnienie statusu opisowego, wersja 5.0.3.
  • Walerian Sokołowski: pierwsza wersja opisu protokołu bezpośrednich połączeń.
  • Nikodem (n-d%tlen.pl): flagi rodzaju użytkownika.
  • Adam Wysocki (gophi%ekg.chmurka.net): poprawki, utrzymanie wszystkiego w porządku, GG_XML_EVENT.
  • Marcin Krupowicz (marcin.krupowicz%gmail.com): informacja na temat tego, że pakiet GG_LOGIN_OK nie zawsze jest zerowej długości.
  • Jakub Zawadzki (darkjames%darkjames.ath.cx): nowości w 7.x i 8.x.
  • Krystian Kołodziej (krystiankolodziej%gmail.com): znaczenie GG_DISCONNECT_ACK.
  • Adrian Warecki (bok%kokosoftware.pl): Przykładowe pakiety GG_XML_ACTION

$Id$