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

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

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

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

Zwraca liczbę wyników odpowiedzi.

Parametry:
resOdpowiedź
Zwraca:
Liczba wyników lub -1 w przypadku błędu

Zwraca rodzaj zapytania lub odpowiedzi.

Parametry:
resZapytanie lub odpowiedź
Zwraca:
Rodzaj lub -1 w przypadku błędu

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
 All Struktury Danych Pliki Funkcje Zmienne Definicje typów Wyliczenia Wartości wyliczeń Definicje