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