Katalog publiczny
[Połączenie z serwerem]


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. Teksty muszą być oczywiście kodowane w CP1250. 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().


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.


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


Wygenerowano Sun Dec 5 02:38:45 2010 dla libgadu programem  doxygen 1.5.6