Połączenie z serwerem
[Połączenie z serwerem]

Opis szczegółowy

Każde połączenie z serwerem jest rozpoczynane funkcją gg_login() zwracającą strukturę gg_session, opisującą dane połączenie. Funkcja 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:

struct gg_session *sesja;
struct gg_login_params parametry;
struct gg_event *zdarzenie;

memset(&parametry, 0, sizeof(parametry));
parametry.uin = 12345;
parametry.password = "hasło";
parametry.async = 1;
parametry.status = GG_STATUS_INVISIBLE;

sesja = gg_login(&parametry);

if (!sesja) {
    błąd("Nie można się połączyć");
    exit(1);
}

// ...

Lista wszystkich parametrów połączenia znajduje się w opisie struktury gg_login_params. W zależności od tego, czy łączymy się synchronicznie czy asynchronicznie (jak w przykładzie), funkcja 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 obsłudze zdarzeń.

Aby łączyć się z użyciem serwera pośredniczącego (ang. proxy), należy przed połączeniem ustawić zmienne globalne gg_proxy_enabled , gg_proxy_host , gg_proxy_port i inne.

Do korzystania z połączeń bezpośrednich wersji 6.x, konieczne jest przed połączeniem ustawienie zmiennych globalnych gg_dcc_ip i gg_dcc_port.

Procedura łączenia z serwerem

Procedura łączenia się z serwerem składa się z kilku etapów:

  1. Rozwiązywanie nazwy serwera rozdzielającego (ang. hub), domyślnie appmsg.gadu-gadu.pl
  2. Nawiązanie połączenia z serwerem rozdzielającym na porcie 80.
  3. Wysłanie zapytania o adres właściwego serwera. Parametrami zapytania są m.in. numer konta i wersja klienta.
  4. Odebranie odpowiedzi zawierającej adres IP właściwego serwera, jego port i ewentualnie wiadomość systemową.
  5. Nawiązanie połączenia z właściwym serwerem.
  6. Odebranie pakietu z ziarnem hasła do przeprowadzenia autoryzacji typu challenge-response.
  7. Wysłanie pakietu z parametrami logowania (w tym skrótem hasła).
  8. Odebranie pakietu z informacją o pomyślnym lub nieudanym logowaniu.

Wszystkimi etapami zajmuje się funkcja gg_login() w przypadku połączenia synchronicznego lub gg_login() i 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 server_addr i server_port struktury 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.

Nota:
Jeśli biblioteka używa procesu do rozwiązywania nazw, w aplikacji należy użyć funkcji systemowej 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 zombie.

Utrzymanie połączenia

Serwer oczekuje regularnego wysyłania pakietów utrzymania połączenia. W tym celu należy co minutę wywoływać funkcję gg_ping().

Zakończenie połączenia

Aby się wylogować, należy użyć funkcji gg_logoff(), a następnie zwolnić zasoby związane z sesją za pomocą funkcji gg_free_session(). Aby ustawić status z opisem, należy wcześniej wywołać funkcję gg_change_status_descr().


Struktury danych

struct  gg_session
 Sesja Gadu-Gadu. Więcej...
struct  gg_login_params
 Parametry połączenia z serwerem Gadu-Gadu. Więcej...

Funkcje

struct gg_session * gg_login (const struct gg_login_params *p)
 Łączy się z serwerem Gadu-Gadu.
int gg_ping (struct gg_session *sess)
 Wysyła do serwera pakiet utrzymania połączenia.
void gg_logoff (struct gg_session *sess)
 Kończy połączenie z serwerem.
void gg_free_session (struct gg_session *sess)
 Zwalnia zasoby używane przez połączenie z serwerem.

Dokumentacja funkcji

struct gg_session* gg_login ( const struct gg_login_params *  p  )  [read]

Łączy się z serwerem Gadu-Gadu.

Przy połączeniu synchronicznym funkcja zakończy działanie po nawiązaniu połączenia lub gdy wystąpi błąd. Po udanym połączeniu należy wywoływać funkcję gg_watch_fd(), która odbiera informacje od serwera i zwraca informacje o zdarzeniach.

Przy połączeniu asynchronicznym funkcja rozpocznie procedurę połączenia i zwróci zaalokowaną strukturę. Pole fd struktury gg_session zawiera deskryptor, który należy obserwować funkcją select, poll lub za pomocą mechanizmów użytej pętli zdarzeń (Glib, Qt itp.). Pole check jest maską bitową mówiącą, czy biblioteka chce być informowana o możliwości odczytu danych (GG_CHECK_READ) czy zapisu danych (GG_CHECK_WRITE). Po zaobserwowaniu zmian na deskryptorze należy wywołać funkcję gg_watch_fd(). Podczas korzystania z połączeń asynchronicznych, w trakcie połączenia może zostać stworzony dodatkowy proces rozwiązujący nazwę serwera -- z tego powodu program musi poprawnie obsłużyć sygnał SIGCHLD.

Nota:
Po nawiązaniu połączenia z serwerem należy wysłać listę kontaktów za pomocą funkcji gg_notify() lub gg_notify_ex().
Parametry:
p Struktura opisująca parametry połączenia. Wymagane pola: uin, password, async.
Zwraca:
Wskaźnik do zaalokowanej struktury sesji gg_session lub NULL w przypadku błędu.

int gg_ping ( struct gg_session *  sess  ) 

Wysyła do serwera pakiet utrzymania połączenia.

Klient powinien regularnie co minutę wysyłać pakiet utrzymania połączenia, inaczej serwer uzna, że klient stracił łączność z siecią i zerwie połączenie.

Parametry:
sess Struktura sesji
Zwraca:
0 jeśli się powiodło, -1 w przypadku błędu

void gg_logoff ( struct gg_session *  sess  ) 

Kończy połączenie z serwerem.

Funkcja nie zwalnia zasobów, więc po jej wywołaniu należy użyć gg_free_session(). Jeśli chce się ustawić opis niedostępności, należy wcześniej wywołać funkcję gg_change_status_descr() lub gg_change_status_descr_time().

Nota:
Jeśli w buforze nadawczym połączenia z serwerem znajdują się jeszcze dane (np. z powodu strat pakietów na łączu), prawdopodobnie zostaną one utracone przy zrywaniu połączenia.
Parametry:
sess Struktura sesji

void gg_free_session ( struct gg_session *  sess  ) 

Zwalnia zasoby używane przez połączenie z serwerem.

Funkcję należy wywołać po zamknięciu połączenia z serwerem, by nie doprowadzić do wycieku zasobów systemowych.

Parametry:
sess Struktura sesji

Wygenerowano Sun Dec 5 15:14:54 2010 dla libgadu programem  doxygen 1.5.6