Połączenia bezpośrednie od wersji Gadu-Gadu 7.x

Diagram współpracy dla Połączenia bezpośrednie od wersji Gadu-Gadu 7.x:

Struktury danych
struct	gg_dcc7
	Połączenie bezpośrednie od wersji Gadu-Gadu 7.x. Więcej...

Funkcje
static struct gg_dcc7 *	gg_dcc7_send_file_common (struct gg_session *sess, uin_t rcpt, int fd, size_t size, const char *filename1250, const char *hash, int seek)
struct gg_dcc7 *	gg_dcc7_send_file (struct gg_session *sess, uin_t rcpt, const char *filename, const char *filename1250, const char *hash)
	Rozpoczyna wysyłanie pliku o danej nazwie. Więcej...
struct gg_dcc7 *	gg_dcc7_send_file_fd (struct gg_session *sess, uin_t rcpt, int fd, size_t size, const char *filename1250, const char *hash)
int	gg_dcc7_accept (struct gg_dcc7 *dcc, unsigned int offset)
	Potwierdza chęć odebrania pliku. Więcej...
int	gg_dcc7_reject (struct gg_dcc7 *dcc, int reason)
	Odrzuca próbę przesłania pliku. Więcej...
struct gg_event *	gg_dcc7_watch_fd (struct gg_dcc7 *dcc)
	Funkcja wywoływana po zaobserwowaniu zmian na deskryptorze połączenia. Więcej...
void	gg_dcc7_free (struct gg_dcc7 *dcc)
	Zwalnia zasoby używane przez połączenie bezpośrednie. Więcej...

Opis szczegółowy

Przesyłanie plików zgodne z Gadu-Gadu 7.x jest znacznie prostsze niż w wersji 6.x. Podobnie jak poprzednio, każde połączenie jest opisane przez strukturę gg_dcc7. Nie ma konieczności otwierania gniazda nasłuchującego, ponieważ jest tworzone dla każdego połączenia osobno.

Gdy chcemy wysłać plik, wywołujemy gg_dcc7_send_file() i obserwujemy zdarzenia zarówno z gg_session, jak i gg_dcc7. Parametry funkcji to struktura sesji, numer odbiorcy, nazwa pliku, nazwa pliku w kodowaniu CP1250 (jeśli NULL to brana jest oryginalna nazwa) i skrót pliku wyznaczony algorytmem SHA1 (jeśli NULL to biblioteka liczy, blokując na ten czas działanie aplikacji). Wysyłanie jest praktycznie bezobsługowe, wystarczy zareagować na zdarzenie GG_EVENT_DCC7_DONE i GG_EVENT_DCC7_ERROR w gg_dcc7 oraz GG_EVENT_DCC7_REJECTED i GG_EVENT_DCC7_ERROR w gg_session, żeby wiedzieć, kiedy zwolnić zasoby funkcją gg_dcc7_free().

Jeśli ktoś do nas wysyła plik, otrzymamy zdarzenie GG_EVENT_DCC7_NEW z sesji. Należy przygotować deskryptor otwarty do zapisu, wpisać jego wartość do pola file_fd struktury gg_dcc7 i wywołać gg_dcc7_accept() albo od razu wywołać gg_dcc7_reject(), jeśli nie chcemy połączenia. Tak samo jak przy wysyłaniu, wystarczy obsłużyć GG_EVENT_DCC7_DONE w strukturze gg_dcc7 i GG_EVENT_DCC7_ERROR w strukturach gg_session i gg_dcc7.

Deskryptor połączenia (pole fd struktury gg_dcc7) może zmienić się po wywołaniu funkcji gg_dcc7_accept() lub otrzymaniu jednego ze zdarzeń: GG_EVENT_DCC7_CONNECTED, GG_EVENT_DCC7_ACCEPT, GG_EVENT_DCC7_PENDING.

Opcje połączeń

Ponieważ jedna ze stron odbiera połączenie bezpośrednie, konieczne jest nasłuchiwanie na porcie TCP. Domyślne ustawienia pozwalają na poprawną pracę jeśli co najmniej jedna ze stron połączenia ma bezpośredni dostęp do sieci, bez translacji adresów i/lub portów. Pole client_addr struktury gg_login_params mówi na jakim adresie należy nasłuchiwać. Domyślna wartość 0.0.0.0 powoduje nasłuchiwanie na wszystkich dostępnych interfejsach komputera. Pole client_port mówi na którym porcie należy nasłuchiwać. Domyślna wartość 0 powoduje nasłuchiwanie na losowym dostępnym porcie. Należy zwrócić uwagę, że jeśli jedno połączenie będzie nasłuchiwać na danym porcie, inne już nie będzie w stanie, co spowoduje błąd.

Druga para ustawień dotyczy publicznego adresu i portu. Ta strona połączenia, która nasłuchuje na porcie TCP wysyła do drugiej strony swój adres i numer portu. Pole external_addr mówi jaki adres zostanie wysłany. Domyślna wartość 0.0.0.0 powoduje wysłanie adresu IP, z którego sesja łączy się z serwerem. Pole external_port mówi jaki port zostanie wysłany. Domyślna wartość 0 powoduje wysłane portu, na którym połączenie nasłuchuje.

Do zrobienia

• Rozmowy głosowe.
• Nawiązywanie połączeń przez serwer.

Dokumentacja funkcji

gg_dcc7_send_file_common()

static struct gg_dcc7* gg_dcc7_send_file_common ( struct gg_session *  sess, uin_t  rcpt, int  fd, size_t  size, const char *  filename1250, const char *  hash, int  seek  )

static

Rozpoczyna wysyłanie pliku.

Funkcja jest wykorzystywana przez gg_dcc7_send_file() oraz gg_dcc_send_file_fd().

Parametry

sess	Struktura sesji
rcpt	Numer odbiorcy
fd	Deskryptor pliku
size	Rozmiar pliku
filename1250	Nazwa pliku w kodowaniu CP-1250
hash	Skrót SHA-1 pliku
seek	Flaga mówiąca, czy można używać lseek()

Zwraca

Struktura gg_dcc7 lub NULL w przypadku błędu

gg_dcc7_send_file()

struct gg_dcc7* gg_dcc7_send_file	(	struct gg_session *	sess,
		uin_t	rcpt,
		const char *	filename,
		const char *	filename1250,
		const char *	hash
	)

Rozpoczyna wysyłanie pliku o danej nazwie.

Parametry

sess	Struktura sesji
rcpt	Numer odbiorcy
filename	Nazwa pliku w lokalnym systemie plików
filename1250	Nazwa pliku w kodowaniu CP-1250
hash	Skrót SHA-1 pliku (lub NULL jeśli ma być wyznaczony)

Zwraca

Struktura gg_dcc7 lub NULL w przypadku błędu

gg_dcc7_send_file_fd()

struct gg_dcc7* gg_dcc7_send_file_fd	(	struct gg_session *	sess,
		uin_t	rcpt,
		int	fd,
		size_t	size,
		const char *	filename1250,
		const char *	hash
	)

Rozpoczyna wysyłanie pliku o danym deskryptorze.

Nota

Wysyłanie pliku nie będzie działać poprawnie, jeśli deskryptor źródłowy jest w trybie nieblokującym i w pewnym momencie zabraknie danych.

Parametry

sess	Struktura sesji
rcpt	Numer odbiorcy
fd	Deskryptor pliku
size	Rozmiar pliku
filename1250	Nazwa pliku w kodowaniu CP-1250
hash	Skrót SHA-1 pliku

Zwraca

Struktura gg_dcc7 lub NULL w przypadku błędu

gg_dcc7_accept()

int gg_dcc7_accept	(	struct gg_dcc7 *	dcc,
		unsigned int	offset
	)

Potwierdza chęć odebrania pliku.

Parametry

dcc	Struktura połączenia
offset	Początkowy offset przy wznawianiu przesyłania pliku

Nota

Biblioteka nie zmienia położenia w odbieranych plikach. Jeśli offset początkowy jest różny od zera, należy ustawić go funkcją lseek() lub podobną.

Zwraca

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

gg_dcc7_reject()

int gg_dcc7_reject	(	struct gg_dcc7 *	dcc,
		int	reason
	)

Odrzuca próbę przesłania pliku.

Parametry

dcc	Struktura połączenia
reason	Powód odrzucenia

Zwraca

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

gg_dcc7_watch_fd()

struct gg_event* gg_dcc7_watch_fd

(

struct gg_dcc7 *

dcc

)

Funkcja wywoływana po zaobserwowaniu zmian na deskryptorze połączenia.

Funkcja zwraca strukturę zdarzenia gg_event. Jeśli rodzaj zdarzenia to GG_EVENT_NONE, nie wydarzyło się jeszcze nic wartego odnotowania. Strukturę zdarzenia należy zwolnić funkcja gg_event_free().

Parametry

dcc	Struktura połączenia

Zwraca

Struktura zdarzenia lub NULL jeśli wystąpił błąd

gg_dcc7_free()

void gg_dcc7_free

(

struct gg_dcc7 *

dcc

)

Zwalnia zasoby używane przez połączenie bezpośrednie.

Parametry

dcc	Struktura połączenia