Wiadomości
[Połączenie z serwerem]

---

Opis szczegółowy

Wysyłanie zwykłych wiadomości jest prostą operacją i większości przypadków wystarczy użycie funkcji gg_send_message:

gg_send_message(sesja, GG_CLASS_CHAT, odbiorca, treść);

Funkcja zwraca numer sekwencyjny wiadomości, który może zostać użyty do potwierdzenia dostarczenia wiadomości za pomocą zdarzenia GG_EVENT_ACK . Wiadomości przeznaczone do wyświetlania w osobny oknie były wykorzystywane w starszych wersjach Gadu-Gadu, gdzie istniały osobne opcje — wiadomości i rozmowa. Obecnie wykorzystuje się wiadomość typu GG_CLASS_CHAT.

Wiadomość, która ma zawierać formatowanie tekstu, musi zostać wysłana za pomocą funkcji gg_send_message_richtext(). Wiadomości konferencyjne wysyła się funkcjami gg_send_message_conferlogin() 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