libgadu 1.12.2

- Strona główna
- Dodatkowe strony
- Moduły
- Struktury Danych
- Pliki

Struktury danych | Funkcje
Połączenia bezpośrednie od wersji Gadu-Gadu 7.x
Połączenia bezpośrednie między klientami

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

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

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

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

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

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

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

void gg_dcc7_free | ( | struct gg_dcc7 * | dcc | ) |

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

Parametry

  dcc | Struktura połączenia