Import i eksport listy kontaktów

Diagram współpracy dla Import i eksport listy kontaktów:

Wyliczenia
enum	{   GG_USERLIST_PUT ,   GG_USERLIST_GET }
	Rodzaj zapytania. Więcej...
enum	{   GG_USERLIST_PUT_REPLY ,   GG_USERLIST_GET_REPLY }
	Rodzaj odpowiedzi. Więcej...
enum	{   GG_USERLIST100_PUT ,   GG_USERLIST100_GET }
	Rodzaj zapytania (10.0). Więcej...
enum	{   GG_USERLIST100_FORMAT_TYPE_NONE ,   GG_USERLIST100_FORMAT_TYPE_GG70 ,   GG_USERLIST100_FORMAT_TYPE_GG100 }
	Typ formatu listy kontaktów (10.0). Więcej...
enum	{   GG_USERLIST100_REPLY_LIST ,   GG_USERLIST100_REPLY_UPTODATE ,   GG_USERLIST100_REPLY_ACK ,   GG_USERLIST100_REPLY_REJECT }
	Typ odpowiedzi listy kontaktów (10.0). Więcej...

Funkcje
int	gg_userlist_request (struct gg_session *sess, char type, const char *request)
	Wysyła do serwera zapytanie dotyczące listy kontaktów. Więcej...
int	gg_userlist100_request (struct gg_session *sess, char type, unsigned int version, char format_type, const char *request)
	Wysyła do serwera zapytanie dotyczące listy kontaktów (10.0). Więcej...

Opis szczegółowy

Serwer pozwala przechowywać kompletną listę kontaktów w postaci tekstowej, by móc z niej korzystać na dowolnym komputerze bez konieczności ręcznego przenoszenia. Format listy kontaktów jest narzucony przez oryginalnego klienta (obecnie istnieją dwa wspierane formaty: pola oddzielone średnikami oraz dokument XML). W celu sprawnej synchronizacji listy kontaktów między różnymi instalacjami klienta sieci, serwer wersjonuje listę kontaktów i pozwala ją nadpisać tylko w przypadku, gdy zadeklarujemy znajomość jej ostatniej wersji.

Aby wysłać listę kontaktów, wywołujemy:

gg_userlist100_request(sesja, GG_USERLIST100_PUT, wersja_listy_kontaktów, typ_formatu_listy_kontaktów, lista_kontatów);

W odpowiedzi dostaniemy od serwera zdarzenie GG_EVENT_USERLIST100_REPLY z polem type równym GG_USERLIST100_REPLY_ACK w przypadku akceptacji wysłanej listy kontaktów lub GG_USERLIST100_REPLY_REJECT w przypadku jej odrzucenia. Pole version zawiera numer aktualnie przechowywanej przez serwer listy kontaktów (w przypadku przyjęcia nowej, jest to numer tej nowej wersji).

Jeśli chcemy pobrać listę kontaktów z serwera, wywołujemy:

gg_userlist100_request(sesja, GG_USERLIST100_GET, 0, typ_formatu_listy_kontaktów, NULL);

Oczekujemy zdarzenia GG_EVENT_USERLIST100_REPLY z type równym GG_USERLIST100_REPLY_LIST. Zawartość listy kontaktów znajdziemy w polu reply, a jej wersję w polu version.

Ponadto możemy dostać od serwera informację o nowej wersji listy kontaktów. Wówczas dostaniemy zdarzenie GG_EVENT_USERLIST100_VERSION z polem version równym numerowi nowej wersji listy konktaktów.

Dokumentacja typów wyliczanych

anonymous enum

anonymous enum

Rodzaj zapytania.

Wartości wyliczeń
GG_USERLIST_PUT	Eksport listy kontaktów.
GG_USERLIST_GET	Import listy kontaktów.

anonymous enum

anonymous enum

Rodzaj odpowiedzi.

Wartości wyliczeń
GG_USERLIST_PUT_REPLY	Wyeksportowano listy kontaktów.
GG_USERLIST_GET_REPLY	Zaimportowano listę kontaktów.

anonymous enum

anonymous enum

Rodzaj zapytania (10.0).

Wartości wyliczeń
GG_USERLIST100_PUT	Eksport listy kontaktów.
GG_USERLIST100_GET	Import listy kontaktów.

anonymous enum

anonymous enum

Typ formatu listy kontaktów (10.0).

Wartości wyliczeń
GG_USERLIST100_FORMAT_TYPE_NONE	Brak treści listy kontaktów.
GG_USERLIST100_FORMAT_TYPE_GG70	Format listy kontaktów zgodny z Gadu-Gadu 7.0.
GG_USERLIST100_FORMAT_TYPE_GG100	Format listy kontaktów zgodny z Gadu-Gadu 10.0.

anonymous enum

anonymous enum

Typ odpowiedzi listy kontaktów (10.0).

Wartości wyliczeń
GG_USERLIST100_REPLY_LIST	W odpowiedzi znajduje się aktualna lista kontaktów na serwerze.
GG_USERLIST100_REPLY_UPTODATE	Komunikat o tym, że lista kontaktów jest już zsynchronizowana.
GG_USERLIST100_REPLY_ACK	Potwierdzenie odebrania nowej wersji listy kontaktów. W polu gg_userlist100_reply.version znajduje się numer nowej wersji listy kontaktów.
GG_USERLIST100_REPLY_REJECT	Odmowa przyjęcia nowej wersji listy kontaktów. W polu gg_userlist100_reply.version znajduje się numer wersji listy kontaktów aktualnie przechowywanej przez serwer.

Dokumentacja funkcji

gg_userlist_request()

int gg_userlist_request	(	struct gg_session *	sess,
		char	type,
		const char *	request
	)

Wysyła do serwera zapytanie dotyczące listy kontaktów.

Funkcja służy do importu lub eksportu listy kontaktów do serwera. W odróżnieniu od funkcji gg_notify(), ta lista kontaktów jest przez serwer jedynie przechowywana i nie ma wpływu na połączenie. Format listy kontaktów jest ignorowany przez serwer, ale ze względu na kompatybilność z innymi klientami, należy przechowywać dane w tym samym formacie co oryginalny klient Gadu-Gadu.

Program nie musi się przejmować fragmentacją listy kontaktów wynikającą z protokołu – wysyła i odbiera kompletną listę.

Parametry

sess	Struktura sesji
type	Rodzaj zapytania
request	Treść zapytania (może być równe NULL)

Zwraca

0 jeśli się powiodło, -1 w przypadku błędu

gg_userlist100_request()

int gg_userlist100_request	(	struct gg_session *	sess,
		char	type,
		unsigned int	version,
		char	format_type,
		const char *	request
	)

Wysyła do serwera zapytanie dotyczące listy kontaktów (10.0).

Funkcja służy do importu lub eksportu listy kontaktów do serwera. W odróżnieniu od funkcji gg_notify(), ta lista kontaktów jest przez serwer jedynie przechowywana i nie ma wpływu na połączenie. Format listy kontaktów jest jednak weryfikowany przez serwer, który stara się synchronizować listę kontaktów zapisaną w formatach GG 7.0 oraz GG 10.0. Serwer przyjmuje listy kontaktów przysłane w formacie niezgodnym z podanym jako format_type, ale nie zachowuje ich, a przesłanie takiej listy jest równoznaczne z usunięciem listy kontaktów.

Program nie musi się przejmować kompresją listy kontaktów zgodną z protokołem – wysyła i odbiera kompletną listę zapisaną czystym tekstem.

Parametry

sess	Struktura sesji
type	Rodzaj zapytania
version	Numer ostatniej znanej programowi wersji listy kontaktów lub 0
format_type	Typ formatu listy kontaktów
request	Treść zapytania (może być równe NULL)

Zwraca

0 jeśli się powiodło, -1 w przypadku błędu