Katalog publiczny

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.
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

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

type	Rodzaj 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

req	Zapytanie
field	Nazwa pola
value	Wartość 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

req	Zapytanie
seq	Numer 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

s	Zapytanie lub odpowiedź

gg_pubdir50()

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

gg_pubdir50_get()

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

gg_pubdir50_count()

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

gg_pubdir50_type()

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

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

res

Odpowiedź

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

res	Zapytanie lub odpowiedź

Zwraca

Numer sekwencyjny lub -1 w przypadku błędu