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

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...
// ...lub osób urodzonych w latach 1979-1985, aktualnie dostępnych...
gg_pubdir50_add(zapytanie, GG_PUBDIR50_BIRTHYEAR, "1979 1985");
// ...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:

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);
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) {
printf("Dostępny\n");
break;
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
typeRodzaj 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
reqZapytanie
fieldNazwa pola
valueWartość 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
reqZapytanie
seqNumer 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
sZapytanie lub odpowiedź
uint32_t gg_pubdir50 ( struct gg_session sess,
gg_pubdir50_t  req 
)

Wysyła zapytanie katalogu publicznego do serwera.

Parametry
sessStruktura sesji
reqZapytanie
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
resOdpowiedź
numNumer wyniku odpowiedzi
fieldNazwa 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
resOdpowiedź
Zwraca
Liczba wyników lub -1 w przypadku błędu
int gg_pubdir50_type ( gg_pubdir50_t  res)

Zwraca rodzaj zapytania lub odpowiedzi.

Parametry
resZapytanie 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
resOdpowiedź
Zwraca
Numer lub -1 w przypadku błędu
uint32_t gg_pubdir50_seq ( gg_pubdir50_t  res)

Zwraca numer sekwencyjny zapytania lub odpowiedzi.

Parametry
resZapytanie lub odpowiedź
Zwraca
Numer sekwencyjny lub -1 w przypadku błędu