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().
*/
|