libgadu 1.12.2

- Strona główna
- Dodatkowe strony
- Moduły
- Struktury Danych
- Pliki

Struktury danych | Definicje | Wyliczenia | Funkcje | Zmienne
Wiadomości
Połączenie z serwerem

## 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 polach `size` 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

  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.

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.

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.

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.

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.

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.

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.

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

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

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

struct gg_chat_left GG_PACKED