Struktury danych
struct	gg_msg_richtext_format
	Struktura opisująca formatowanie tekstu. Więcej...

struct	gg_msg_richtext_color
	Struktura opisującą kolor tekstu dla atrybutu `GG_FONT_COLOR`. Więcej...

struct	gg_msg_richtext_image
	Strukturya opisująca obrazek wstawiony do wiadomości dla atrubutu `GG_FONT_IMAGE`. Więcej...

Definicje
#define	GG_MSG_MAXSIZE 1989
	Maksymalna długość wiadomości. Więcej...

Wyliczenia
enum	{ GG_CLASS_MSG, GG_CLASS_CHAT, GG_CLASS_CTCP, GG_CLASS_ACK, GG_CLASS_QUEUED }
	Klasy wiadomości. Więcej...

enum	{ GG_FONT_BOLD, GG_FONT_ITALIC, GG_FONT_UNDERLINE, GG_FONT_COLOR, GG_FONT_IMAGE }
	Atrybuty formatowania wiadomości. Więcej...

enum	{ GG_ACK_DELIVERED, GG_ACK_QUEUED, GG_ACK_BLOCKED, GG_ACK_MBOXFULL, GG_ACK_NOT_DELIVERED }
	Status doręczenia wiadomości. Więcej...

Funkcje
int	gg_send_message (struct gg_session sess, int msgclass, uin_t recipient, const unsigned char message)
	Wysyła wiadomość do użytkownika. Więcej...

int	gg_send_message_richtext (struct gg_session sess, int msgclass, uin_t recipient, const unsigned char message, const unsigned char *format, int formatlen)
	Wysyła wiadomość formatowaną. Więcej...

int	gg_send_message_html (struct gg_session sess, int msgclass, uin_t recipient, const unsigned char html_message)
	Wysyła formatowaną wiadomość HTML. Więcej...

int	gg_send_message_confer (struct gg_session sess, int msgclass, int recipients_count, uin_t recipients, const unsigned char *message)
	Wysyła wiadomość w ramach konferencji. Więcej...

int	gg_send_message_confer_richtext (struct gg_session sess, int msgclass, int recipients_count, uin_t recipients, const unsigned char message, const unsigned char format, int formatlen)
	Wysyła wiadomość formatowaną w ramach konferencji. Więcej...

int	gg_send_message_confer_html (struct gg_session sess, int msgclass, int recipients_count, uin_t recipients, const unsigned char *html_message)
	Wysyła formatowaną wiadomość HTML w ramach konferencji. Więcej...

int	gg_send_message_ctcp (struct gg_session sess, int msgclass, uin_t recipient, const unsigned char message, int message_len)
	Wysyła wiadomość binarną przeznaczoną dla klienta. Więcej...

int	gg_image_request (struct gg_session *sess, uin_t recipient, int size, uint32_t crc32)
	Wysyła żądanie obrazka o podanych parametrach. Więcej...

int	gg_image_reply (struct gg_session sess, uin_t recipient, const char filename, const char *image, int size)
	Wysyła żądany obrazek. Więcej...

int	gg_typing_notification (struct gg_session *sess, uin_t recipient, int length)
	Informuje rozmówcę o pisaniu wiadomości. Więcej...

Zmienne
struct gg_header	GG_PACKED

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_confer() lub gg_send_message_confer_richtext().

Wiadomości konferencyjne

Rozmowy konferencyjne w Gadu-Gadu polegają na wysyłaniu tej samej wiadomości do wszystkich uczestników wraz z metainformacją zawierającą listę uczestników. Osoba, która pierwsza wyśle wiadomość, dołącza listę rozmówców do wiadomości, z której korzysta się przy wysyłaniu odpowiedzi. Z tego powodu nie ma możliwości dołączania się lub opuszczania "pokojów" — po zamknięciu rozmowy konferencyjnej należy ignorować kolejne wiadomości, ponieważ inni uczestnicy nie są o tym fakcie informowani.

Funkcje gg_send_message_confer() i gg_send_message_confer_richtext() zajmują się wysłaniem wiadomości do wszystkich uczestników oraz dołączaniem odpowiednich metainformowacji. Aplikacja musi jedynie dołączyć listę rozmówców w postaci listy ich identyfikatorów.

Po odebraniu wiadomości konferencyjnej za pomocą zdarzenia GG_EVENT_MSG ,pola recipients_count oraz recipients struktury zdarzenia określają listę rozmówców.

Wiadomości formatowane

Wiadomości formatowane zawierają metainformacje opisujące formatowanie poszczególnych fragmentów tekstu. Blok metainformacji zawiera dowolną liczbę struktur gg_msg_richtext_format. Pole position określa pierwszy znak, którego dotyczy formatowanie. Pole font jest sumą logiczną atrybutów:

GG_FONT_BOLD — pogrubienie,
GG_FONT_ITALIC — kursywa,
GG_FONT_UNDERLINE — podkreślenie,
GG_FONT_COLOR — kolor,
GG_FONT_IMAGE — obrazek.

Jeśli występuje atrybut GG_FONT_COLOR, zaraz za strukturą gg_msg_richtext_format znajduje się struktura gg_msg_richtext_color opisująca kolor za pomocą składowych RGB.

Jeśli występuje atrybut GG_FONT_IMAGE, za strukturą znajduje się struktura gg_msg_richtext_image. Pole unknown1 zawiera rozmiar (0x09) oraz rodzaj struktury (0x01), ale ze względów historycznych jest liczbą 16-bitową i należy przypisać mu wartość 0x0109. Pola size i crc32 identyfikują obrazek, który można pobrać od nadawcy lub z dysku lokalnego, jeśli był już wcześniej pobierany (np. często używana ikonka). Opis pobierania obrazków od nadawcy znajduje się poniżej.

Nota: Biblioteka nie ingeruje w zawartość bloku formatowania, więc kolejność bajtów może się różnić od używanej na danej architekturze. By pobrać lub określić poszczególne wartości, należy użyć funkcji gg_fix16() i gg_fix32(), które w razie konieczności dokonają konwersji.; Należy pamiętać, że rozmiar bloku formatowania jest określany w bajtach, nie liczbie struktur.; Rozmiary struktur i położenie ich pól nie są wyrównywane do rozmiaru słowa. Jeśli dana architektura wymaga dostępu do pamięci z wyrównaniem, należy o to zadbać w aplikacji.

Otrzymywanie wiadomości

Wiadomości odebrane od serwera są przekazywane za pomocą zdarzenia GG_EVENT_MSG

Nota: Serwer nie prześle zakolejkowanych wiadomości przed wysłaniem listy kontaktów.

Potwierdzenie doręczenia

Każda przesyłana wiadomość zawiera numer sekwencyjny, który może zostać użyty do potwierdzenia doręczenia. Zdarzenie GG_EVENT_ACK zawiera informację o doręczeniulub powód niedoręczenia, chyba że wiadomość została wysłania z klasą GG_CLASS_ACK. Lista kodów jest opisana poniżej.

Pobieranie i wysyłanie obrazków

Po odebraniu wiadomości zawierającej strukturę gg_msg_richtext_image, mając informację o rozmiarze i sumie kontrolnej obrazka, należy użyć funkcji:

gg_image_request(sesja, nadawca, rozmiar, crc);

Następnie należy oczekiwać na zdarzenie GG_EVENT_IMAGE_REPLY , które będzie zawierać rozmiar pliku (size) i sumę kontrolą (crc32) do identifikacji zdarzenia, oraz nazwę obrazka (filename) i jego treść (image). Rodzaj pliku graficznego nie jest określony przy transmisji, więc należy go rozpoznać po rozszerzeniu lub treści.

Nota: Biblioteka ignoruje wszystkie obrazki, które nie były zamówione, żeby uniknąć zajęcia całej dostępnej pamięci, na wypadek gdyby ktoś nieustannie próbował wysyłać niekompletne obrazki.

Jeśli została wysłana wiadomość graficzną, należy obsługiwać zdarzenie GG_EVENT_IMAGE_REQUEST , które w polachsize i crc32 zawiera informacje o obrazku, którego potrzebuje nasz rozmówca. Obrazek wysyła się funkcją:

gg_image_reply(sesja, odbiorca, nazwa_pliku, obrazek, długość_obrazka);

Powiadomienie o pisaniu

Począwszy od Gadu-Gadu 10 rozmówca jest informowany o tym, że jesteśmy w trakcie pisania wiadomości:

gg_typing_notification(sesja, odbiorca, długość_wiadomości);

Informacje o pisaniu przesyłane są do aplikacji za pomocą zdarzenia GG_EVENT_TYPING_NOTIFICATION .

Dokumentacja definicji

#define GG_MSG_MAXSIZE 1989

Maksymalna długość wiadomości.

Dokumentacja typów wyliczanych

anonymous enum

Klasy wiadomości.

Wartości są maskami bitowymi, które w większości przypadków można łączyć (połączenie GG_CLASS_MSG i GG_CLASS_CHAT nie ma sensu).

Wartości wyliczeń
GG_CLASS_MSG	Wiadomość ma pojawić się w osobnym oknie.
GG_CLASS_CHAT	Wiadomość ma pojawić się w oknie rozmowy.
GG_CLASS_CTCP	Wiadomość przeznaczona dla klienta Gadu-Gadu.
GG_CLASS_ACK	Klient nie życzy sobie potwierdzenia.
GG_CLASS_QUEUED	Wiadomość zakolejkowana na serwerze (tylko przy odbieraniu)

anonymous enum

Atrybuty formatowania wiadomości.

Wartości wyliczeń
GG_FONT_BOLD
GG_FONT_ITALIC
GG_FONT_UNDERLINE
GG_FONT_COLOR
GG_FONT_IMAGE

anonymous enum

Status doręczenia wiadomości.

Wartości wyliczeń
GG_ACK_DELIVERED	Wiadomość dostarczono.
GG_ACK_QUEUED	Wiadomość zakolejkowano z powodu niedostępności odbiorcy.
GG_ACK_BLOCKED	Wiadomość zablokowana przez serwer (spam, świąteczne ograniczenia itd.)
GG_ACK_MBOXFULL	Wiadomości nie dostarczono z powodu zapełnionej kolejki wiadomości odbiorcy.
GG_ACK_NOT_DELIVERED	Wiadomości nie dostarczono (tylko dla `GG_CLASS_CTCP`).