libgadu  1.12.2
All Struktury Danych Pliki Funkcje Zmienne Definicje typów Wyliczenia Wartości wyliczeń Definicje Grupay Strony
Struktury danych | Definicje | Wyliczenia | Funkcje | Zmienne

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:

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

Dokumentacja funkcji

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
sessStruktura sesji
msgclassKlasa wiadomości
recipientNumer adresata
messageTreść wiadomości
Zwraca
Numer sekwencyjny wiadomości lub -1 w przypadku błędu.
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
sessStruktura sesji
msgclassKlasa wiadomości
recipientNumer adresata
messageTreść wiadomości
formatInformacje o formatowaniu
formatlenDługość informacji o formatowaniu
Zwraca
Numer sekwencyjny wiadomości lub -1 w przypadku błędu.
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
sessStruktura sesji
msgclassKlasa wiadomości
recipientNumer adresata
html_messageTreść wiadomości HTML
Zwraca
Numer sekwencyjny wiadomości lub -1 w przypadku błędu.
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
sessStruktura sesji
msgclassKlasa wiadomości
recipients_countLiczba adresatów
recipientsWskaźnik do tablicy z numerami adresatów
messageTreść wiadomości
Zwraca
Numer sekwencyjny wiadomości lub -1 w przypadku błędu.
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
sessStruktura sesji
msgclassKlasa wiadomości
recipients_countLiczba adresatów
recipientsWskaźnik do tablicy z numerami adresatów
messageTreść wiadomości
formatInformacje o formatowaniu
formatlenDługość informacji o formatowaniu
Zwraca
Numer sekwencyjny wiadomości lub -1 w przypadku błędu.
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
sessStruktura sesji
msgclassKlasa wiadomości
recipients_countLiczba adresatów
recipientsWskaźnik do tablicy z numerami adresatów
html_messageTreść wiadomości HTML
Zwraca
Numer sekwencyjny wiadomości lub -1 w przypadku błędu.
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
sessStruktura sesji
msgclassKlasa wiadomości
recipientNumer adresata
messageTreść wiadomości
message_lenDługość wiadomości
Zwraca
Numer sekwencyjny wiadomości lub -1 w przypadku błędu.
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
sessStruktura sesji
recipientNumer adresata
sizeRozmiar obrazka w bajtach
crc32Suma kontrola obrazka
Zwraca
0 jeśli się powiodło, -1 w przypadku błędu
int gg_image_reply ( struct gg_session sess,
uin_t  recipient,
const char *  filename,
const char *  image,
int  size 
)

Wysyła żądany obrazek.

Parametry
sessStruktura sesji
recipientNumer adresata
filenameNazwa pliku
imageBufor z obrazkiem
sizeRozmiar obrazka
Zwraca
0 jeśli się powiodło, -1 w przypadku błędu
int gg_typing_notification ( struct gg_session sess,
uin_t  recipient,
int  length 
)

Informuje rozmówcę o pisaniu wiadomości.

Parametry
sessStruktura sesji
recipientNumer adresata
lengthDługość wiadomości lub 0 jeśli jest pusta
Zwraca
0 jeśli się powiodło, -1 w przypadku błędu

Dokumentacja zmiennych

struct gg_chat_left GG_PACKED