Read Me

                                     PyGG
                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                      Pythonowa biblioteka klienta Gadu-Gadu
                     Autor: Dawid Drechny <dawiddr@gmail.com>
                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PyGG to biblioteka, której celem jest dostarczenie wygodnej platformy dla klientów
zgodnych z komunikatorem internetowym Gadu-Gadu. 

Dostarczany model obiektowy zapewnia dwie warstwy abstrakcji. Co za tym idzie, 
pozwala na stworzenie prostej aplikacji klienckiej bez znajomości używanego 
protokołu, ale także zapewnia możliwość budowy zaawansowanych aplikacji, 
które w niestandardowy sposób używają zaimplementowanych mechanizmów 
komunikacyjnych oraz struktur danych.

PyGG jest niezależne od systemu operacyjnego i może być używane wszędzie tam, 
gdzie istnieje standardowa instalacja Pythona w 2.4 lub wyższej.


PROTOKÓŁ
 
  Biblioteka używa protokołu TCP/IP. Opis struktur danych używanych 
  podczas komunikacji znajduje się pod adresem http://ekg.chmurka.net/docs/protocol.html.
 
 
BUDOWA

  PyGG składa się z dwóch podstawowych warstw abstrakcji:

	- niższego poziomu, obsługującej komunikację z serwerem (pygg.dao) za pomocą 
	  zdefiniowanych struktur danych (pygg.packets);

	- wyższego poziomu (pygg.client), która w istocie jest biblioteką kliencką;
	  zapewnia ona wykonywanie typowych dla klienta operacji (takich, jak odbieranie
	  i wysyłanie wiadomości) bez znajomości protokołu komunikacyjnego.

  Wykorzystywane są również funkcje pomocnicze (pygg.helpers), takie jak nawiązanie
  połączenia HTTP z hubem w celu pobrania adresu działającego serwera IM.

FUNKCJONALOŚĆ

  Warstwa komunikacyjna:

	- wysyłanie oraz odbieranie z użyciem socketa wszystkich znanych struktur 
	  danych wykorzystywanych przez protokół.
    
  Warstwa kliencka:

	- ustanawianie połączenia z serwerem;
	- logowanie użytkownika;
	- ustawianie statusu (również z użyciem opisu);
	- wysyłanie oraz odbieranie wiadomości w konwersacji z kontaktem;
	- sprawdzanie statusu kontaktu.

PRZYKŁADY UŻYCIA

  Plik example1.py zawiera przykład podstawowego użycia biblioteki klienckiej.
  Po szczegóły odsyłam do dokumentacji API 
  

DO ZROBIENIA

  Warstwa kliencka:

	- wysyłanie oraz pobieranie z serwera listy kontaktów;
	- sprawdzanie danych kontaktów w Katalogu Publicznym;
	- rejestracja konta;
	- zmiana hasła;
	- przypomnienie hasła poprzez zarządanie wysłania e-maila.

  a także mniej ważne sprawy, takie jak:

	- wysyłanie oraz odbieranie wiadomości obrazkowych;
	- usuwanie konta;
	- przesyłanie plików.



    
~~~~ OSTRZEŻENIE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Używanie innych klientów, niż oficjalny (dostępny na stronie 
http://www.gadu-gadu.pl) jest niezgodne z Regulamin korzystania z serwisu 
Gadu-Gadu (stan na 15 maj 2006 r.).
Biblioteka PyGG została stworzona jedynie jako kompatybilna z protokołem 
Gadu-Gadu, co znaczy, że może zostać wykorzystana z serwerami 
opartymi np. o UKG (Uniksowy Klient Gadu-Gadu; http://toxygen.net/usg/).
Użytkownik PyGG korzysta z serwerów należących do Gadu-Gadu S.A. jedynie
z własnej woli i na własną odpowiedzialność.

~~~~ LICENCJA ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Niniejszy produkt objęty jest postanowieniami licencji GNU Lesser General
Public License w wersji 2.1, dostępnej pod adresem 
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt oraz w pliku LICENSE.

~~~~ ZNAKI TOWAROWE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Gadu-Gadu jest znakiem towarowym należącym do Gadu-Gadu S.A. i został
użyty w tym dokumencie, jak i w kodach źródłowych, jedynie w celu wskazania
kompatybilności używanych protokołów.

~~~~ PODZIĘKOWANIA ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Podziękowania należą się przede wszystkim twórcom opisu protokołu 
(http://ekg.chmurka.net/docs/protocol.html#ch4), bez którego powstanie
tej biblioteki byłoby bardzo utrudnione.