1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
/**
\defgroup login Połączenie z serwerem
\ingroup session
\details
Każde połączenie z serwerem jest rozpoczynane funkcją \c gg_login() zwracającą
strukturę \c gg_session, opisującą dane połączenie. Funkcja \c gg_login() za
parametr przyjmuje wskaźnik strukturę zawierającą listę parametrów połączenia.
Przykładowy kod rozpoczynający łączenie wygląda następująco:
\code
struct gg_session *sesja;
struct gg_login_params parametry;
struct gg_event *zdarzenie;
memset(¶metry, 0, sizeof(parametry));
parametry.uin = 12345;
parametry.password = "hasło";
parametry.async = 1;
parametry.status = GG_STATUS_INVISIBLE;
sesja = gg_login(¶metry);
if (!sesja) {
błąd("Nie można się połączyć");
exit(1);
}
// ...
\endcode
Lista wszystkich parametrów połączenia znajduje się w opisie struktury
\c gg_login_params. W zależności od tego, czy łączymy się synchronicznie czy
asynchronicznie (jak w przykładzie), funkcja \c gg_login() zwróci wskaźnik
dopiero po udanym połączeniu lub zaraz po rozpoczęciu procedury łączenia.
Dokładny opis dalszej obsługi połączenia znajduje się w sekcji poświęconej \ref
events "obsłudze zdarzeń".
Nowe statusy (nie przeszkadzać, poGGadaj ze mną), opisy graficzne i wiadomości
kodowane UTF-8 będą dostępne dopiero po ustawieniu odpowiednich parametrów
połączenia. Jest to niezbędne, ponieważ starsze klienty mogłyby nie działać
prawidłowo, gdyby przy domyślnych parametrach połączenia zmieniłoby się
zachowanie biblioteki.
\code
parametry.encoding = GG_ENCODING_UTF8;
parametry.protocol_features = GG_FEATURE_DND_FFC | GG_FEATURE_IMAGE_DESCR;
\endcode
Aby łączyć się z użyciem serwera pośredniczącego (ang. \e proxy), należy przed
połączeniem ustawić zmienne globalne \ref proxy "\c gg_proxy_enabled"
, \ref proxy "\c gg_proxy_host"
, \ref proxy "\c gg_proxy_port"
i \ref proxy "inne."
Do korzystania z połączeń bezpośrednich wersji 6.x, konieczne jest przed
połączeniem ustawienie zmiennych globalnych \ref ip "\c gg_dcc_ip"
i \ref ip "\c gg_dcc_port."
\section login-details Procedura łączenia z serwerem
Procedura łączenia się z serwerem składa się z kilku etapów:
-# Rozwiązywanie nazwy serwera rozdzielającego (ang. \e hub), domyślnie
\c appmsg.gadu-gadu.pl
-# Nawiązanie połączenia z serwerem rozdzielającym na porcie 80.
-# Wysłanie zapytania o adres właściwego serwera. Parametrami zapytania są
m.in. numer konta i wersja klienta.
-# Odebranie odpowiedzi zawierającej adres IP właściwego serwera, jego port
i ewentualnie wiadomość systemową.
-# Nawiązanie połączenia z właściwym serwerem.
-# Odebranie pakietu z ziarnem hasła do przeprowadzenia autoryzacji typu
\e challenge-response.
-# Wysłanie pakietu z parametrami logowania (w tym skrótem hasła).
-# Odebranie pakietu z informacją o pomyślnym lub nieudanym logowaniu.
Wszystkimi etapami zajmuje się funkcja \c gg_login() w przypadku połączenia
synchronicznego lub \c gg_login() i \c gg_watch_fd() dla połączeń
asynchronicznych. Możliwe jest pominięcie pierwszych czterech kroków,
związanych z połączeniem z serwerem rozdzielającym, przez
ręczne podanie adresu i portu właściwego serwera w polach
\ref gg_login_params::server_addr "\c server_addr"
i \ref gg_login_params::server_port "\c server_port"
struktury \c gg_login_params. Jest to przydatne w sytuacjach, gdy serwer
rozdzielający jest przeciążony lub niedostępny, albo gdy zwraca nieprawidłowy
adres właściwego serwera.
Rozwiązywanie nazwy w systemach zgodnych z normą POSIX jest operacją
synchroniczną. Z tego powodu w trybie asynchronicznym konieczne jest utworzenie
dodatkowego procesu lub wątku (w zależności od opcji kompilacji), który w tle
dokona rozwiązania nazwy i zwróci wynik do procesu lub wątku nadrzędnego.
\note Jeśli biblioteka używa procesu do rozwiązywania nazw, w aplikacji należy
użyć funkcji systemowej \c wait() lub podobnej do prawidłowego zakończenia
życia procesu potomnego. W przeciwnym wypadku, w zależności od zachowania
systemu operacyjnego, mogą powstawać procesy \e zombie.
\section login-keepalive Utrzymanie połączenia
Serwer oczekuje regularnego wysyłania pakietów utrzymania połączenia. W tym
celu należy co minutę wywoływać funkcję \c gg_ping().
\section login-logoff Zakończenie połączenia
Aby się wylogować, należy użyć funkcji \c gg_logoff(), a następnie zwolnić
zasoby związane z sesją za pomocą funkcji \c gg_free_session(). Aby ustawić
status z opisem, należy wcześniej wywołać funkcję \c gg_change_status_descr().
*/
|
