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.

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.
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ą.
int	gg_send_message_html (struct gg_session *sess, int msgclass, uin_t recipient, const unsigned char *html_message)
	Wysyła formatowaną wiadomość HTML.
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.
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.
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.
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.
int	gg_image_request (struct gg_session *sess, uin_t recipient, int size, uint32_t crc32)
	Wysyła żądanie obrazka o podanych parametrach.
int	gg_image_reply (struct gg_session *sess, uin_t recipient, const char *filename, const char *image, int size)
	Wysyła żądany obrazek.
int	gg_typing_notification (struct gg_session *sess, uin_t recipient, int length)
	Informuje rozmówcę o pisaniu wiadomości.

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 dowyświetlania w osobny oknie były wykorzystywane w starszych wersjachGadu-Gadu, gdzie istniały osobne opcje — wiadomości i rozmowa. Obecniewykorzystuje się wiadomość typu GG_CLASS_CHAT.Wiadomość, która ma zawierać formatowanie tekstu, musi zostać wysłana zapomocą funkcji gg_send_message_richtext(). Wiadomości konferencyjne wysyłasię funkcjami gg_send_message_confer() lubgg_send_message_confer_richtext().@section messages-conference Wiadomości konferencyjneRozmowy konferencyjne w Gadu-Gadu polegają na wysyłaniu tej samej wiadomoścido 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 mamoż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 \c gg_send_message_confer() i \c 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 \ref events-list "GG_EVENT_MSG", pola \ref gg_event_msg::recipients_count "recipients_count" oraz \ref gg_event_msg::recipients "recipients" struktury zdarzenia określają listę rozmówców. @section messages-richtext Wiadomości formatowane Wiadomości formatowane zawierają metainformacje opisujące formatowanie poszczególnych fragmentów tekstu. Blok metainformacji zawiera dowolną liczbę struktur \c gg_msg_richtext_format. Pole \c position określa pierwszy znak, którego dotyczy formatowanie. Pole \c font jest sumą logiczną atrybutów: <ul> <li>\c GG_FONT_BOLD &mdash; pogrubienie,</li> <li>\c GG_FONT_ITALIC &mdash; kursywa,</li> <li>\c GG_FONT_UNDERLINE &mdash; podkreślenie,</li> <li>\c GG_FONT_COLOR &mdash; kolor,</li> <li>\c GG_FONT_IMAGE &mdash; obrazek.</li> </ul> Jeśli występuje atrybut \c GG_FONT_COLOR, zaraz za strukturą \c gg_msg_richtext_format znajduje się struktura \c gg_msg_richtext_color opisująca kolor za pomocą składowych RGB. Jeśli występuje atrybut \c GG_FONT_IMAGE, za strukturą znajduje się struktura \c gg_msg_richtext_image. Pole \c unknown1 zawiera rozmiar (0x09) oraz rodzaj struktury (0x01), ale ze względów historycznych jest liczbą 16-bitową i należy przypisać mu wartość \c 0x0109. Pola \c size i \c 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ę \ref messages-images "poniżej". \note 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 \c gg_fix16() i \c gg_fix32(), które w razie konieczności dokonają konwersji. \note Należy pamiętać, że rozmiar bloku formatowania jest określany w bajtach, nie liczbie struktur. \note 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. @section messages-receive Otrzymywanie wiadomości Wiadomości odebrane od serwera są przekazywane za pomocą zdarzenia \ref events-list "GG_EVENT_MSG" \note Serwer nie prześle zakolejkowanych wiadomości przed wysłaniem \ref contacts "listy kontaktów". @section messages-ack Potwierdzenie doręczenia Każda przesyłana wiadomość zawiera numer sekwencyjny, który może zostać użyty do potwierdzenia doręczenia. Zdarzenie \ref events-list "GG_EVENT_ACK" zawiera informację o doręczeniu lub powód niedoręczenia, chyba że wiadomość została wysłania z klasą \c GG_CLASS_ACK. Lista kodów jest opisana poniżej. @section messages-images Pobieranie i wysyłanie obrazków Po odebraniu wiadomości zawierającej strukturę \c gg_msg_richtext_image, mając informację o rozmiarze i sumie kontrolnej obrazka, należy użyć funkcji: @code gg_image_request(sesja, nadawca, rozmiar, crc); \endcode Następnie należy oczekiwać na zdarzenie \ref events-list "GG_EVENT_IMAGE_REPLY" , które będzie zawierać rozmiar pliku (\c size) i sumę kontrolą (\c crc32) do identifikacji zdarzenia, oraz nazwę obrazka (\c filename) i jego treść (\c image). Rodzaj pliku graficznego nie jest określony przy transmisji, więc należy go rozpoznać po rozszerzeniu lub treści. \note 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 \ref events-list "GG_EVENT_IMAGE_REQUEST", które w polach \c size i \c crc32 zawiera informacje o obrazku, którego potrzebuje nasz rozmówca. Obrazek wysyła się funkcją: @code gg_image_reply(sesja, odbiorca, nazwa_pliku, obrazek, długość_obrazka); \endcode @section messages-typing Powiadomienie o pisaniu Począwszy od Gadu-Gadu 10 rozmówca jest informowany o tym, że jesteśmy w trakcie pisania wiadomości: @code gg_typing_notification(sesja, odbiorca, długość_wiadomości); \endcode Informacje o pisaniu przesyłane są do aplikacji za pomocą zdarzenia \ref events-list "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