1<chapter> 2 <title>API biblioteki.</title> 3 <sect1> 4 <title>Zaczynamy.</title> 5 <para> 6 Bibliotek� libtlen mo�na wykorzysta� w programach pisanych w C oraz C++. 7 Nale�y tylko do��cza� plik nag��wkowy biblioteki jak na przyk�adzie poni�ej 8 </para> 9 <screen> 10 #include <libtlen/libtlen.h> 11 </screen> 12 <para> 13 oraz linkowa� z bibliotek� tlen, np: 14 </para> 15 <screen> 16 gcc -g -Wall -O2 -ltlen main.c -o main 17 </screen> 18 <para> 19 Wszystkie funkcje oraz nazwy struktur z biblioteki dost�pne dla 20 programisty maj� przedrostek tlen_, natomiast sta�e zdefiniowane 21 przedrostek TLEN_. 22 Przed po��czeniem z serwerem nale�y zadeklarowa� wska�nik na struktur� 23 tlen_session. W tej strukturze przechowywane s� informacje o danej sesji. 24 Je�li chcemy, aby biblioteka wypisywa�a informacje o wykonywanych 25 operacjach (np. ��czenie z serwerem, autoryzacja) uruchamiamy funkcj� 26 </para> 27 <screen> 28 tlen_setdebug(1); 29 </screen> 30 <para> 31 Teraz mo�na przej�� do logowania. Dost�pne s� dwie funkcje: tlen_login 32 oraz tlen_login_nb. Obie wymagaj� podania dw�ch parametr�w, odpowiednio 33 loginu i has�a w postaci 'const char *'. R�ni� si� tym, �e pierwsza 34 z nich blokuje program zanim po��czy si� z serwerem, druga natomiast 35 ��czy si� z serwerem w oddzielnym procesie, dzi�ki czemu program nie jest 36 blokowany i przechodzi do obs�ugi zdarze� (o tym p�niej). Obie funkcj� 37 zwracaj� wska�nik na struktur� tlen_session, kt�ry nale�y zachowa� 38 (b�dzie potrzebny we wszystkich dalej opisanych funkcjach), lub NULL je�li 39 logowanie nie powiod�o si�. Po wywo�aniu jednej z tych funkcji przechodzimy 40 do obs�ugi zdarze�. 41 </para> 42 </sect1> 43 <sect1> 44 <title>Zdarzenia.</title> 45 <para> 46 O wszystkich zdarzeniach (nowa wiadomo��, zmiana statusu kogo� z listy 47 u�ytkownik�w, itp) program jest powiadamiany za pomoc� event�w, kt�rych 48 nazwy maj� przedrostek TLEN_EVENT_. Poni�ej opisz� poszczeg�lne eventy, a 49 potem poka�� przyk�adow� p�tl� obs�uguj�c� je. 50 </para> 51 <sect2> 52 <title>Zdarzenia obs�ugiwane jeden raz na pocz�tku sesji.</title> 53 <para> 54 Pierwszym zdarzeniem jest TLEN_EVENT_NOWGETID. M�wi nam ono o gotowo�ci 55 serwera, teraz mo�na wys�a� ��danie o identyfikator sesji. S�u�y do tego 56 funkcja tlen_getid, kt�rej jako jedyny parametr przekazujemy wska�nik 57 do sesji. W rezultacie otrzymujemy event TLEN_EVENT_GOTID, a wi�c mamy ju� 58 id sesji, czas na autoryzacj�. W tym celu wywo�ujemy funkcj� tlen_authorize 59 z tym samym parametrem co poprzednio. Je�li ta operacja si� powiedzie 60 program otrzyma zdarzenie TLEN_EVENT_AUTHORIZED, w kt�rego obs�udze mo�na 61 wys�a� ��danie o ksi��k� adresow�, tlen_getroster (wywo�anie r�wnie� z 62 jednym parametrem). O niepowodzeniu autoryzacji jeste�my informowani 63 zdarzeniem TLEN_EVENT_UNAUTHORIZED, w tym przypadku nale�y zako�czy� 64 dzia�anie programu lub spr�bowa� zalogowa� sie ponownie. Zdarzenie 65 TLEN_EVENT_GOTROSTERITEM to pojedynczy wpis w naszej ksi��ce adresowej. Aby 66 dosta� si� do tych informacji odwo�ujemy si� do pola roster w strukturze 67 tlen_event (o niej po�niej w opisie p�tli). Pole te jest struktur� o nazwie 68 tlen_user, zawiera nazw� osoby (name), identyfikator (jid) w postaci 69 login@tlen.pl, nazw� grupy (group), rodzaj subskrypcji (subscription) oraz 70 pole ask, kt�re je�li zawiera napis "subscribe", to znaczy, �e czekamy na 71 pozwolenie o subskrypcj� u danej osoby. W przeciwnym razie pole ask 72 zawiera NULL. Je�li chcemy doda� kogo� do naszej listy, to musimy j� 73 poprosi� o subskrypcj�, inaczej dana osoba nie b�dzie widoczna. Pole 74 subscription natomiast okre�la poziom subskrypcji, je�li zawiera napis 75 "none" 76 to oznacza brak subskrypcji u obu stron, "from" oznacza subskrypcj� danej 77 osoby w naszej ksi��ce (np. gdy czekamy na pozwolenie na subskrypcj�), "to" 78 oznacza, �e jeste�my zapisani u danej osoby ale ta osoba nie jest zapisana 79 u nas (np. gdy zrezygnowali�my z kontaktu). Najwy�szy poziom subskrypcji to 80 "both", oznacza, �e obie strony s� zapisane w ksi��ce partnera. O ko�cu 81 ksi��ki adresowej jeste�my powiadamiani zdarzeniem TLEN_EVENT_ENDROSTER. Na 82 tym ko�czy si� obs�uga tej cz�ci zdarze�, teraz wywo�ujemy funkcj� 83 tlen_presence jak na przyk�adzie: 84 </para> 85 <screen> 86 tlen_presence(sesja,TLEN_STATUS_AVAILABLE,"Dost�pny"); 87 </screen> 88 <para> 89 gdzie pierwszy parametr jest wska�nikiem na sesj�, drugi oznacza status 90 (w tym przypadku dost�pny), w trzecim za� podajemy w�asny opis. 91 </para> 92 </sect2> 93 <sect2> 94 <title>Pozosta�e zdarzenia.</title> 95 <para> 96 Gdy kto� dodaje nas do swojej listy kontakt�w, jego program wysy�a do nas 97 pro�b� o subskrypcj�, wtedy otrzymujemy event SUBSCRIBE (dok�adnie 98 TLEN_EVENT_SUBSCRIBE). Aby subskrypcja przebieg�a prawid�owo, nale�y 99 najpierw zaakceptowa� nowy kontakt, nawet je�li chcemy odrzuci� pro�b�. 100 Inaczej druga strona nie dowie si� o naszej decyzji. Je�li dodatkowo nie 101 mamy tej osoby na li�cie kontakt�w, to nale�y j� doda�. S�u�� do tego 102 funkcje odpowiednio "tlen_accept_subscribe" oraz "tlen_addcontact". Teraz 103 nale�y zapyta� u�ytkownika czy chce subskrybowa� dan� osob�. Je�li nie, to 104 wywo�ujemy funkcje "tlen_removecontact" oraz "tlen_accept_unsubscribe". 105 </para> 106 <para> 107 Event SUBSCRIBED powiadamia nas o tym, �e otrzymali�my pozwolenie na 108 subskrypcj� u danej osoby. Teraz mo�emy od�wie�y� list� kontakt�w. 109 </para> 110 <para> 111 Event UNSUBSCRIBE otrzymujemy, gdy kto� usunie nas ze swojej listy 112 kontakt�w. Nie mamy wyboru, musimy ten fakt zaakceptowa�, wywo�uj�c funkcj� 113 "tlen_accept_unsubscribe". Zmieniamy pole "subscribe" na "none", od�wie�amy 114 list� i ��damy tego samego, czyli "tlen_request_unsubscribe". W rezultacie 115 powinni�my otrzyma� event UNSUBSCRIBED. 116 </para> 117 <para> 118 Przechodzimy do ciekawszych rzeczy, czyli wiadomo�ci. MESSAGE powiadamia nas 119 o nowej wiadomo�ci, kt�ra mo�e by� w postaci rozmowy (TLEN_CHAT) lub 120 pojedynczej wiadomo�ci. 121 </para> 122 <para> 123 Kiedy osoba zapisana na naszej li�cie zmienia sw�j status lub opis 124 otrzymujemy event PRESENCE. 125 </para> 126 <para> 127 Event NEWMAIL to powiadomienie o nowej poczcie na skrzynce tlen.pl 128 </para> 129 <para> 130 Event GOTPUBDIRDATA informuje nas o nadej�ciu naszych danych z katalogu 131 publicznego. Jest rezultatem wywo�ania funkcji "tlen_get_pubdir". 132 </para> 133 <para> 134 Aby zmieni� nasze dane publiczne wywo�ujemy funkcj� "tlen_change_pubdir". 135 Je�li ta operacja si� powiedzie otrzymujemy event GOTPUBDIRUPDATEOK. 136 </para> 137 <para> 138 Funkcja "tlen_search" s�u�y do przeszukiwania katalogu publicznego. O 139 znalezionych pozycjach informuje nas event GOTSEARCHITEM. Event ENDSEARCH 140 oznacza koniec znalezionych rekord�w. 141 </para> 142 <para> 143 Ka�de zdarzenie uzupe�nia odpowiednio struktur� tlen_event. Np. event 144 MESSAGE musi gdzie� zapisywa� informacje od kogo jest wiadomo�� i jak� ma 145 tre��. O tym m�wi nast�pna sekcja. 146 </para> 147 </sect2> 148 <sect2> 149 <title>Zawarto�� struktury tlen_event</title> 150 <para> 151 Poniewa� mamy kilka rodzaji zdarze�, struktura musi zawiera� pole 152 okre�laj�ce typ, jest nim "type", kt�re przyjmuje warto�ci TLEN_EVENT_* 153 (dok�adny opis znajduje si� w pliku nag��wkowym biblioteki). Poza tym, 154 znajdziemy wska�niki do struktur odpowiednich typ�w. Dla danego zdarzenia 155 alokowana jest pamie� dla struktury odpowiadaj�cej temu zdarzeniu, na kt�r� 156 wskazuje odpowiedni wska�nik. Dokladny opis tej struktury, jak i innych dla 157 konkretnych zdarze�, znajduje si� w samym pliku nag��wkowym. 158 </para> 159 </sect2> 160 </sect1> 161 <sect1> 162 <title>Po��czmy si�.</title> 163 <para> 164 Za��my, �e mamy ju� zadeklarowany w programie wska�nik na struktur� 165 tlen_session, czyli "struct tlen_session *sesja". Aby pobra� z kolejki 166 zdarzenie potrzebujemy nast�puj�cych zmiennych: 167 </para> 168 <screen> 169 fd_set rd, wr; // obserwowane deskryptory socket�w 170 struct tlen_event *event; // wska�nik na zdarzenie 171 struct timeval tv; // czas blokowania programu przez select 172 </screen> 173 <para> 174 Inicjalizujemy te zmienne: 175 </para> 176 <screen> 177 tv.tv_sec = 0; 178 tv.tv_usec = 1; // je�li brak danych to funkcja select nie blokuje programu 179 FD_ZERO (&rd); 180 FD_ZERO (&wr); 181 if ((sesja->check & TLEN_CHECK_READ)) // je�li czytamy dane 182 FD_SET (sesja->fd, &rd); 183 if ((sesja->check & TLEN_CHECK_WRITE)) // je�li wysy�amy dane 184 FD_SET (sesja->fd, &wr); 185 </screen> 186 <para> 187 Sprawdzamy obecno�� danych: 188 </para> 189 <screen> 190 if (select (sesja->fd + 1, &rd, &wr, NULL, &tv) == -1) 191 { 192 perror("select"); // b��d z deskryptorem? 193 exit(1); //wychodzimy z programu 194 } 195 </screen> 196 <para> 197 Pobieramy zdarzenie: 198 </para> 199 <screen> 200 if (sesja && (FD_ISSET (sesja->fd, &rd) || FD_ISSET (sesja->fd, 201 &wr))) 202 { 203 tlen_watch_fd (sesja); 204 while ((event=tlen_getevent(sesja))!=NULL) 205 { 206 switch (event->type) 207 { 208 case TLEN_EVENT_NOWGETID: 209 //... 210 } 211 tlen_freeevent(event); //zwalniamy pami�� 212 } 213 </screen> 214 <para> 215 Tu zaczyna si� obs�uga zdarze�, o kt�rej by�a mowa wcze�niej. Powy�szy kod 216 nale�y umie�cic w funkcji, kt�r� wywo�ujemy np. co sekund�. Ponadto aby serwer 217 nie zerwa� po��czenia nale�y co jedn� minut� wywo�ywa� funkcj� 218 "tlen_ping(sesja)". Podczas dzia�ania programu sprawdzamy pole "error" w 219 strukturze tlen_session, je�li jest r�ne od zera, ponownie ��czymy si� z 220 serwerem. 221 </para> 222 <sect2> 223 <title>Funkcje.</title> 224 <para> 225 <itemizedlist> 226 <listitem><para> 227 tlen_addcontact - dodanie osoby do ksi�zki adresowej lub aktualizacja 228 danych, opr�cz loginu mo�emy poda� nazw� dla danej osoby i nazw� grupy, do 229 kt�rej chcemy j� zapisa�. 230 </para></listitem> 231 <listitem><para> 232 tlen_removecontact - usuwanie osoby z ksi��ki. 233 </para></listitem> 234 <listitem><para> 235 tlen_request_subscribe - pro�ba o autoryzacj� u danej osoby. 236 </para></listitem> 237 <listitem><para> 238 tlen_request_unsubscribe - pro�ba o wypisanie si� z ksi��ki danej osoby. 239 </para></listitem> 240 <listitem><para> 241 tlen_accept_subscribe - autoryzowanie danej osoby w naszej ksi��ce. 242 </para></listitem> 243 <listitem><para> 244 tlen_accept_unsubscribe - zatwierdzenie wypisania z naszej ksi��ki danej 245 osoby. 246 </para></listitem> 247 <listitem><para> 248 tlen_presence - zmiana statusu, podajemy TLEN_STATUS_* oraz opis, je�li 249 podamy TLEN_STATUS_UNAVAILABLE to zerwiemy po��czenie z serwerem. 250 </para></listitem> 251 <listitem><para> 252 tlen_sendmsg - wys�anie komunikatu, musimy okre�li� typ (TLEN_CHAT dla 253 rozmowy lub TLEN_MESSAGE dla wiadomo�ci). 254 </para></listitem> 255 <listitem><para> 256 tlen_search - wyszukiwanie w katalogu publicznym. 257 </para></listitem> 258 <listitem><para> 259 tlen_new_pubdir - inicjalizacja struktury tlen_pubdir. 260 </para></listitem> 261 <listitem><para> 262 tlen_free_pubdir - zwolnienie pami�ci zajmowanem przez struktur� 263 tlen_pubdir. 264 </para></listitem> 265 <listitem><para> 266 tlen_get_pubdir - pobranie z serwera naszych danych. 267 </para></listitem> 268 <listitem><para> 269 tlen_change_pubdir - zmiana naszych danych w katalogu publicznym. 270 </para></listitem> 271 </itemizedlist> 272 </para> 273 </sect2> 274 </sect1> 275</chapter> 276 277 278