/**

\defgroup messages Wiadomości
\ingroup session

\details

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

\code
gg_send_message(sesja, GG_CLASS_CHAT, odbiorca, treść);
\endcode

Funkcja zwraca numer sekwencyjny wiadomości, który może zostać użyty do
potwierdzenia dostarczenia wiadomości za pomocą zdarzenia
\ref events-list "\c 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 \c GG_CLASS_CHAT.

Wiadomość, która ma zawierać formatowanie tekstu, musi zostać wysłana za
pomocą funkcji \c gg_send_message_richtext(). Wiadomości konferencyjne wysyła
się funkcjami \c gg_send_message_confer() lub
\c gg_send_message_confer_richtext().

\section messages-conference 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 \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 "\c 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 "\c 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 "\c 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 "\c 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 "\c 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 "\c GG_EVENT_TYPING_NOTIFICATION".

*/