libgadu 1.12.2

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

Wyliczenia | Funkcje
Katalog publiczny
Połączenie z serwerem

## Wyliczenia
enum | { GG_PUBDIR50_UIN, GG_PUBDIR50_STATUS, GG_PUBDIR50_FIRSTNAME, GG_PUBDIR50_LASTNAME, GG_PUBDIR50_NICKNAME, GG_PUBDIR50_BIRTHYEAR, GG_PUBDIR50_CITY, GG_PUBDIR50_GENDER, GG_PUBDIR50_ACTIVE, GG_PUBDIR50_START, GG_PUBDIR50_FAMILYNAME, GG_PUBDIR50_FAMILYCITY }
| Rodzaj pola zapytania. Więcej...
enum | { GG_PUBDIR50_GENDER_FEMALE, GG_PUBDIR50_GENDER_MALE }
| Wartość pola GG_PUBDIR50_GENDER przy wyszukiwaniu. Więcej...
enum | { GG_PUBDIR50_GENDER_SET_FEMALE, GG_PUBDIR50_GENDER_SET_MALE }
| Wartość pola GG_PUBDIR50_GENDER przy wysyłaniu informacji o sobie. Więcej...
enum | { GG_PUBDIR50_ACTIVE_TRUE }
| Wartość pola GG_PUBDIR50_ACTIVE. Więcej...
enum | { GG_PUBDIR50_WRITE, GG_PUBDIR50_READ, GG_PUBDIR50_SEARCH, GG_PUBDIR50_SEARCH_REPLY }
| Rodzaj zapytania lub odpowiedzi katalogu publicznego. Więcej...

## Funkcje
gg_pubdir50_t | gg_pubdir50_new (int type)
| Tworzy nowe zapytanie katalogu publicznego. Więcej...
int | gg_pubdir50_add (gg_pubdir50_t req, const char *field, const char *value)
| Dodaje pole zapytania. Więcej...
int | gg_pubdir50_seq_set (gg_pubdir50_t req, uint32_t seq)
| Ustawia numer sekwencyjny zapytania. Więcej...
void | gg_pubdir50_free (gg_pubdir50_t s)
| Zwalnia zasoby po zapytaniu lub odpowiedzi katalogu publicznego. Więcej...
uint32_t | gg_pubdir50 (struct gg_session *sess, gg_pubdir50_t req)
| Wysyła zapytanie katalogu publicznego do serwera. Więcej...
const char * | gg_pubdir50_get (gg_pubdir50_t res, int num, const char *field)
| Pobiera pole z odpowiedzi katalogu publicznego. Więcej...
int | gg_pubdir50_count (gg_pubdir50_t res)
| Zwraca liczbę wyników odpowiedzi. Więcej...
int | gg_pubdir50_type (gg_pubdir50_t res)
| Zwraca rodzaj zapytania lub odpowiedzi. Więcej...
uin_t | gg_pubdir50_next (gg_pubdir50_t res)
| Zwraca numer, od którego należy rozpocząc kolejne wyszukiwanie. Więcej...
uint32_t | gg_pubdir50_seq (gg_pubdir50_t res)
| Zwraca numer sekwencyjny zapytania lub odpowiedzi. Więcej...

## Opis szczegółowy

Funkcje katalogu publicznego pozwalają wyszukiwać znajomych oraz manipulować informacjami o sobie (imię, nazwisko, miejscowość, rok urodzenia itd.). Każda operacja na katalogu publicznym wymaga skonstruowania odpowiedniego zapytania do serwera i ewentualnej obsłudze odpowiedzi.

Wyszukiwanie może wyglądać następująco:

gg_pubdir50_t zapytanie;
zapytanie = gg_pubdir50_new(GG_PUBDIR50_SEARCH_REQUEST);
if (!zapytanie)
błąd("Brak pamięci");
// Jeśli szukamy danego numeru...
gg_pubdir50_add(zapytanie, GG_PUBDIR50_UIN, "123456");
// ...lub kobiet o imieniu Anna...
gg_pubdir50_add(zapytanie, GG_PUBDIR50_FIRSTNAME, "Anna");
gg_pubdir50_add(zapytanie, GG_PUBDIR50_GENDER, GG_PUBDIR50_GENDER_FEMALE);
// ...lub osób urodzonych w latach 1979-1985, aktualnie dostępnych...
gg_pubdir50_add(zapytanie, GG_PUBDIR50_BIRTHYEAR, "1979 1985");
gg_pubdir50_add(zapytanie, GG_PUBDIR50_START, "0");
gg_pubdir50_add(zapytanie, GG_PUBDIR50_ACTIVE, GG_PUBDIR50_ACTIVE_TRUE);
// ...to po ustaleniu parametrów wywołujemy
gg_pubdir50(sesja, zapytanie);
// Po przetworzeniu wyników zwalniamy pamięć
gg_pubdir50_free(zapytanie);

Jak widać, `gg_pubdir50_new()` tworzy obiekt opisujący operację katalogu, `gg_pubdir50_add()` dodaje kolejne pola zapytania. Pole zapytania jest w rzeczywiści stałą tekstową, np. `GG_PUBDIR50_UIN` to `"FmNumber"`. Należy pamiętać, że wszystkie argumenty są tekstami, ale nie trzeba się przejmować alokacją pamięci — biblioteka zapamięta to, co jest potrzebne. Kodowanie tekstów jest zgodne z ustawieniem sesji. Na końcu wywołujemy funkcję `gg_pubdir50()`, która zwróci numer sekwencyjny wyszukiwania (można zachować dla późniejszego rozróżnienia wyników).

Aby otrzymać wynik, należy obsłużyć zdarzenia `GG_EVENT_PUBDIR50_SEARCH_REPLY`, `GG_EVENT_PUBDIR50_WRITE` i `GG_EVENT_PUBDIR50_READ`. Dla przykładu, obsługa wyników wyszukiwania wygląda następująco:

gg_pubdir50_t wynik;
int i, ilosc;
wynik = event->event.pubdir50;
ilosc = gg_pubdir50_count(wynik);
if (ilosc < 1) {
wiadomość("Nie znaleziono");
return;
}
for (i = 0; i < ilosc; i++) {
const char *numer, *imie, *pseudo, *urodzony, *miasto, *status;
numer = gg_pubdir50_get(wynik, i, GG_PUBDIR50_UIN);
imie = gg_pubdir50_get(wynik, i, GG_PUBDIR50_FIRSTNAME);
pseudo = gg_pubdir50_get(wynik, i, GG_PUBDIR50_NICKNAME);
urodzony = gg_pubdir50_get(wynik, i, GG_PUBDIR50_BIRTHYEAR);
miasto = gg_pubdir50_get(wynik, i, GG_PUBDIR50_CITY);
status = gg_pubdir50_get(wynik, i, GG_PUBDIR50_STATUS);
printf("Numer: %s\nImię: %s\nPseudonim: %s\n"
"Urodzony: %s\nMiejscowość: %s\n",
numer, imie, pseudo, urodzony, miasto);;
switch ((status) ? atoi(status) : -1) {
case GG_STATUS_AVAIL:
printf("Dostępny\n");
break;
case GG_STATUS_BUSY:
printf("Zajęty\n");
break;
default:
printf("Niedostępny\n")
}
printf("\n");
}
gg_event_free(zdarzenie);

Jeśli chcemy wiedzieć, od jakiego numeru zacząć wyszukiwanie, żeby dostać dalszą część, używamy `gg_pubdir50_next()`. Numer sekwencyjny otrzymamy dzięki funkcji `gg_pubdir50_seq()`.

Nota
  W żadnym wypadku nie można się odwoływać do pól `gg_pubdir50_t`, ponieważ mogą się zmieniać między wersjami biblioteki. Dzięki odwoływaniu się przez funkcje, mamy pewność, że bez względu na zmiany API/ABI otrzymamy to samo. Dodatkowo, jeśli pojawią się nowe pola, wystarczy odwoływać się do nich tak jak do obecnych, za pomocą funkcji `gg_pubdir50_add()` i `gg_pubdir50_get()`.

## Dokumentacja typów wyliczanych

anonymous enum

Rodzaj pola zapytania.

Wartości wyliczeń
GG_PUBDIR50_UIN | Numer Gadu-Gadu.
GG_PUBDIR50_STATUS | Status (tylko wynik wyszukiwania)
GG_PUBDIR50_FIRSTNAME | Imię
GG_PUBDIR50_LASTNAME | Nazwisko.
GG_PUBDIR50_NICKNAME | Pseudonim.
GG_PUBDIR50_BIRTHYEAR | Rok urodzenia lub przedział lat oddzielony spacją
GG_PUBDIR50_CITY | Miejscowość
GG_PUBDIR50_GENDER | Płeć
GG_PUBDIR50_ACTIVE | Osoba dostępna (tylko wyszukiwanie)
GG_PUBDIR50_START | Numer początkowy wyszukiwania (tylko wyszukiwanie)
GG_PUBDIR50_FAMILYNAME | Nazwisko rodowe (tylko wysyłanie informacji o sobie)
GG_PUBDIR50_FAMILYCITY | Miejscowość pochodzenia (tylko wysyłanie informacji o sobie)

anonymous enum

Wartość pola GG_PUBDIR50_GENDER przy wyszukiwaniu.

Brak pola oznacza dowolną płeć.

Wartości wyliczeń
GG_PUBDIR50_GENDER_FEMALE | Kobieta.
GG_PUBDIR50_GENDER_MALE | Mężczyzna.

anonymous enum

Wartość pola GG_PUBDIR50_GENDER przy wysyłaniu informacji o sobie.

Wartości wyliczeń
GG_PUBDIR50_GENDER_SET_FEMALE | Kobieta.
GG_PUBDIR50_GENDER_SET_MALE | Mężczyzna.

anonymous enum

Wartość pola GG_PUBDIR50_ACTIVE.

Wartości wyliczeń
GG_PUBDIR50_ACTIVE_TRUE | Wyszukaj tylko osoby dostępne.

anonymous enum

Rodzaj zapytania lub odpowiedzi katalogu publicznego.

Wartości wyliczeń
GG_PUBDIR50_WRITE | Wysłanie do serwera informacji o sobie.
GG_PUBDIR50_READ | Pobranie z serwera informacji o sobie.
GG_PUBDIR50_SEARCH | Wyszukiwanie w katalogu publicznym.
GG_PUBDIR50_SEARCH_REPLY | Wynik wyszukiwania w katalogu publicznym.

## Dokumentacja funkcji

gg_pubdir50_t gg_pubdir50_new | ( | int | type | ) |

Tworzy nowe zapytanie katalogu publicznego.

Parametry

  type | Rodzaj zapytania

Zwraca
  Zmienna `gg_pubdir50_t` lub `NULL` w przypadku błędu.

int gg_pubdir50_add | ( | gg_pubdir50_t | req,
|  | const char * | field,
|  | const char * | value
| ) |  |

Dodaje pole zapytania.

Parametry

  req | Zapytanie
  field | Nazwa pola
  value | Wartość pola

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

int gg_pubdir50_seq_set | ( | gg_pubdir50_t | req,
|  | uint32_t | seq
| ) |  |

Ustawia numer sekwencyjny zapytania.

Parametry

  req | Zapytanie
  seq | Numer sekwencyjny

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

void gg_pubdir50_free | ( | gg_pubdir50_t | s | ) |

Zwalnia zasoby po zapytaniu lub odpowiedzi katalogu publicznego.

Parametry

  s | Zapytanie lub odpowiedź

uint32_t gg_pubdir50 | ( | struct gg_session * | sess,
|  | gg_pubdir50_t | req
| ) |  |

Wysyła zapytanie katalogu publicznego do serwera.

Parametry

  sess | Struktura sesji
  req | Zapytanie

Zwraca
  Numer sekwencyjny zapytania lub 0 w przypadku błędu

const char* gg_pubdir50_get | ( | gg_pubdir50_t | res,
|  | int | num,
|  | const char * | field
| ) |  |

Pobiera pole z odpowiedzi katalogu publicznego.

Parametry

  res | Odpowiedź
  num | Numer wyniku odpowiedzi
  field | Nazwa pola (wielkość liter nie ma znaczenia)

Zwraca
  Wartość pola lub `NULL` jeśli nie znaleziono

int gg_pubdir50_count | ( | gg_pubdir50_t | res | ) |

Zwraca liczbę wyników odpowiedzi.

Parametry

  res | Odpowiedź

Zwraca
  Liczba wyników lub -1 w przypadku błędu

int gg_pubdir50_type | ( | gg_pubdir50_t | res | ) |

Zwraca rodzaj zapytania lub odpowiedzi.

Parametry

  res | Zapytanie lub odpowiedź

Zwraca
  Rodzaj lub -1 w przypadku błędu

uin_t gg_pubdir50_next | ( | gg_pubdir50_t | res | ) |

Zwraca numer, od którego należy rozpocząc kolejne wyszukiwanie.

Dłuższe odpowiedzi katalogu publicznego są wysyłane przez serwer w mniejszych paczkach. Po otrzymaniu odpowiedzi, jeśli numer kolejnego wyszukiwania jest większy od zera, dalsze wyniki można otrzymać przez wywołanie kolejnego zapytania z określonym numerem początkowym.

Parametry

  res | Odpowiedź

Zwraca
  Numer lub -1 w przypadku błędu

uint32_t gg_pubdir50_seq | ( | gg_pubdir50_t | res | ) |

Zwraca numer sekwencyjny zapytania lub odpowiedzi.

Parametry

  res | Zapytanie lub odpowiedź

Zwraca
  Numer sekwencyjny lub -1 w przypadku błędu