Wiadomości

Diagram współpracy dla Wiadomości:

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

GG_MSG_MAXSIZE

#define GG_MSG_MAXSIZE   1989

Maksymalna długość wiadomości.

Dokumentacja typów wyliczanych

anonymous enum

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

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

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).

Dokumentacja funkcji

gg_send_message()

int gg_send_message	(	struct gg_session *	sess,
		int	msgclass,
		uin_t	recipient,
		const unsigned char *	message
	)

Wysyła wiadomość do użytkownika.

Zwraca losowy numer sekwencyjny, który można zignorować albo wykorzystać do potwierdzenia.

Parametry

sess	Struktura sesji
msgclass	Klasa wiadomości
recipient	Numer adresata
message	Treść wiadomości

Zwraca

Numer sekwencyjny wiadomości lub -1 w przypadku błędu.

gg_send_message_richtext()

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ą.

Zwraca losowy numer sekwencyjny, który można zignorować albo wykorzystać do potwierdzenia.

Parametry

sess	Struktura sesji
msgclass	Klasa wiadomości
recipient	Numer adresata
message	Treść wiadomości
format	Informacje o formatowaniu
formatlen	Długość informacji o formatowaniu

Zwraca

Numer sekwencyjny wiadomości lub -1 w przypadku błędu.

gg_send_message_html()

int gg_send_message_html	(	struct gg_session *	sess,
		int	msgclass,
		uin_t	recipient,
		const unsigned char *	html_message
	)

Wysyła formatowaną wiadomość HTML.

Zwraca losowy numer sekwencyjny, który można zignorować albo wykorzystać do potwierdzenia.

Parametry

sess	Struktura sesji
msgclass	Klasa wiadomości
recipient	Numer adresata
html_message	Treść wiadomości HTML

Zwraca

Numer sekwencyjny wiadomości lub -1 w przypadku błędu.

gg_send_message_confer()

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.

Zwraca losowy numer sekwencyjny, który można zignorować albo wykorzystać do potwierdzenia.

Parametry

sess	Struktura sesji
msgclass	Klasa wiadomości
recipients_count	Liczba adresatów
recipients	Wskaźnik do tablicy z numerami adresatów
message	Treść wiadomości

Zwraca

Numer sekwencyjny wiadomości lub -1 w przypadku błędu.

gg_send_message_confer_richtext()

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.

Zwraca losowy numer sekwencyjny, który można zignorować albo wykorzystać do potwierdzenia.

Parametry

sess	Struktura sesji
msgclass	Klasa wiadomości
recipients_count	Liczba adresatów
recipients	Wskaźnik do tablicy z numerami adresatów
message	Treść wiadomości
format	Informacje o formatowaniu
formatlen	Długość informacji o formatowaniu

Zwraca

Numer sekwencyjny wiadomości lub -1 w przypadku błędu.

gg_send_message_confer_html()

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.

Zwraca losowy numer sekwencyjny, który można zignorować albo wykorzystać do potwierdzenia.

Parametry

sess	Struktura sesji
msgclass	Klasa wiadomości
recipients_count	Liczba adresatów
recipients	Wskaźnik do tablicy z numerami adresatów
html_message	Treść wiadomości HTML

Zwraca

Numer sekwencyjny wiadomości lub -1 w przypadku błędu.

gg_send_message_ctcp()

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.

Wiadomości między klientami przesyła się np. w celu wywołania zwrotnego połączenia bezpośredniego. Funkcja zwraca losowy numer sekwencyjny, który można zignorować albo wykorzystać do potwierdzenia.

Parametry

sess	Struktura sesji
msgclass	Klasa wiadomości
recipient	Numer adresata
message	Treść wiadomości
message_len	Długość wiadomości

Zwraca

Numer sekwencyjny wiadomości lub -1 w przypadku błędu.

gg_image_request()

int gg_image_request	(	struct gg_session *	sess,
		uin_t	recipient,
		int	size,
		uint32_t	crc32
	)

Wysyła żądanie obrazka o podanych parametrach.

Wiadomości obrazkowe nie zawierają samych obrazków, a tylko ich rozmiary i sumy kontrolne. Odbiorca najpierw szuka obrazków w swojej pamięci podręcznej i dopiero gdy ich nie znajdzie, wysyła żądanie do nadawcy. Wynik zostanie przekazany zdarzeniem GG_EVENT_IMAGE_REPLY.

Parametry

sess	Struktura sesji
recipient	Numer adresata
size	Rozmiar obrazka w bajtach
crc32	Suma kontrola obrazka

Zwraca

0 jeśli się powiodło, -1 w przypadku błędu

gg_image_reply()

int gg_image_reply	(	struct gg_session *	sess,
		uin_t	recipient,
		const char *	filename,
		const char *	image,
		int	size
	)

Wysyła żądany obrazek.

Parametry

sess	Struktura sesji
recipient	Numer adresata
filename	Nazwa pliku
image	Bufor z obrazkiem
size	Rozmiar obrazka

Zwraca

0 jeśli się powiodło, -1 w przypadku błędu

gg_typing_notification()

int gg_typing_notification	(	struct gg_session *	sess,
		uin_t	recipient,
		int	length
	)

Informuje rozmówcę o pisaniu wiadomości.

Parametry

sess	Struktura sesji
recipient	Numer adresata
length	Długość wiadomości lub 0 jeśli jest pusta

Zwraca

0 jeśli się powiodło, -1 w przypadku błędu

Dokumentacja zmiennych

GG_PACKED

struct gg_chat_left GG_PACKED