libgadu  1.12.2
Wyliczenia | Funkcje
Katalog publiczny
Połączenie z serwerem
Diagram współpracy dla 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...
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);
gg_pubdir50_add
int gg_pubdir50_add(gg_pubdir50_t req, const char *field, const char *value)
Dodaje pole zapytania.
Definition: pubdir50.c:136
gg_pubdir50_new
gg_pubdir50_t gg_pubdir50_new(int type)
Tworzy nowe zapytanie katalogu publicznego.
Definition: pubdir50.c:48
gg_pubdir50_free
void gg_pubdir50_free(gg_pubdir50_t s)
Zwalnia zasoby po zapytaniu lub odpowiedzi katalogu publicznego.
Definition: pubdir50.c:173
gg_pubdir50
uint32_t gg_pubdir50(struct gg_session *sess, gg_pubdir50_t req)
Wysyła zapytanie katalogu publicznego do serwera.
Definition: pubdir50.c:199
GG_PUBDIR50_FIRSTNAME
@ GG_PUBDIR50_FIRSTNAME
Imię
Definition: libgadu.h:1430
GG_PUBDIR50_UIN
@ GG_PUBDIR50_UIN
Numer Gadu-Gadu.
Definition: libgadu.h:1428
GG_PUBDIR50_ACTIVE
@ GG_PUBDIR50_ACTIVE
Osoba dostępna (tylko wyszukiwanie)
Definition: libgadu.h:1436
GG_PUBDIR50_BIRTHYEAR
@ GG_PUBDIR50_BIRTHYEAR
Rok urodzenia lub przedział lat oddzielony spacją
Definition: libgadu.h:1433
GG_PUBDIR50_GENDER
@ GG_PUBDIR50_GENDER
Płeć
Definition: libgadu.h:1435
GG_PUBDIR50_START
@ GG_PUBDIR50_START
Numer początkowy wyszukiwania (tylko wyszukiwanie)
Definition: libgadu.h:1437
GG_PUBDIR50_ACTIVE_TRUE
@ GG_PUBDIR50_ACTIVE_TRUE
Wyszukaj tylko osoby dostępne.
Definition: libgadu.h:1468
GG_PUBDIR50_GENDER_FEMALE
@ GG_PUBDIR50_GENDER_FEMALE
Kobieta.
Definition: libgadu.h:1448
gg_pubdir50_s
Zapytanie lub odpowiedź katalogu publicznego.
Definition: libgadu.h:978

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);
gg_event_free
void gg_event_free(struct gg_event *e)
Zwalnia pamięć zajmowaną przez informację o zdarzeniu.
Definition: events.c:66
gg_pubdir50_count
int gg_pubdir50_count(gg_pubdir50_t res)
Zwraca liczbę wyników odpowiedzi.
Definition: pubdir50.c:495
gg_pubdir50_get
const char * gg_pubdir50_get(gg_pubdir50_t res, int num, const char *field)
Pobiera pole z odpowiedzi katalogu publicznego.
Definition: pubdir50.c:463
GG_PUBDIR50_NICKNAME
@ GG_PUBDIR50_NICKNAME
Pseudonim.
Definition: libgadu.h:1432
GG_PUBDIR50_CITY
@ GG_PUBDIR50_CITY
Miejscowość
Definition: libgadu.h:1434
GG_PUBDIR50_STATUS
@ GG_PUBDIR50_STATUS
Status (tylko wynik wyszukiwania)
Definition: libgadu.h:1429
GG_STATUS_AVAIL
@ GG_STATUS_AVAIL
Dostępny.
Definition: libgadu.h:2015
GG_STATUS_BUSY
@ GG_STATUS_BUSY
Zajęty.
Definition: libgadu.h:2017

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

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

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

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

anonymous enum

Wartość pola GG_PUBDIR50_ACTIVE.

Wartości wyliczeń
GG_PUBDIR50_ACTIVE_TRUE 

Wyszukaj tylko osoby dostępne.

◆ anonymous enum

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_new()

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.

◆ gg_pubdir50_add()

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

◆ gg_pubdir50_seq_set()

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

◆ gg_pubdir50_free()

void gg_pubdir50_free ( gg_pubdir50_t  s)

Zwalnia zasoby po zapytaniu lub odpowiedzi katalogu publicznego.

Parametry
sZapytanie lub odpowiedź

◆ gg_pubdir50()

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

◆ gg_pubdir50_get()

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

◆ gg_pubdir50_count()

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

◆ gg_pubdir50_type()

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

◆ gg_pubdir50_next()

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

◆ gg_pubdir50_seq()

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
Wygenerowano przez doxygen 1.9.1