2.7 Obsługa rostera
W tym rozdziale omówimy sobie podstawowe metody obsługi rostera, naszej listy kontaktów, przechowywanej na serwerze.
W następnym rozdziale omówimy integracje rostera z subskrypcją, przedstawimy procesy zachodzące w rosterze w czasie zarządzania subskrypcją.
2.7.1 Pobieranie rostera
Po zalogowaniu powinniśmy pobrać swoją listę kontaktów. Dokonujemy tego wysyłając do serwera zapytanie z prośbą o przesłanie rostera:
<iq type="get" id="GetRoster">
<query xmlns="jabber:iq:roster"></query>
</iq>W odpowiedzi serwer zwraca nam dane, o które prosiliśmy:
<iq type="result" id="GetRoster">
<query xmlns="jabber:iq:roster">
<item jid="malcom@tlen.pl" name="MalCom"
subscription="both">
<group>Kontakty</group>
</item>
<item jid="malcom21@tlen.pl" name="malcom21"
subscription="none">
<group>Kontakty</group>
</item>
<item jid="david@tlen.pl" name="Dawid"
subscription="to">
<group>Znajomi</group>
</item>
<item jid="contact@tlen.pl" name="ktos"
subscription="none" ask="subscribe"/>
</query>
</iq>Lista kontaktów znajduje się pomiędzy tagami <query></query>. Każdy kontakt reprezentowany jest przez osobny tag <item/>.
Atrybut jid jest identyfikatorem tlenowym danego kontaktu, name określa nazwę kontaktu na liście, a subscription rodzaj subskrypcji, o której już pisaliśmy w poprzednim rozdziale. Parametr ask mówi nam, że oczekujemy na odpowiedź wysłanej (kiedyś) prośby o subskrypcje (autoryzacje).
Jeśli dany kontakt przypisany jest do jakieś grupy na liście kontaktów to <group></group> definiuje tą grupę. W przeciwnym wypadku tag ten jest pomijany.
2.7.2 Dodawanie pozycji
Aby dodać do naszej książki kontaktowej użytkownika należy wysłać serwerowi odpowiedni pakiet z danymi o dodawanym kontakcie:
<iq type="set">
<query xmlns="jabber:iq:roster">
<item jid="malcom@tlen.pl" name="MalCom">
<group>Kontakty</group>
</item>
</query>
</iq>Myślę, że opis nie jest wymagany, znaczenie poszczególnych elementów i atrybutów jest identyczne jak w pakiecie z danymi naszego rostera.
Odpowiedz serwera na dodanie nowego kontaktu:
<iq type="set">
<query xmlns="jabber:iq:roster">
<item jid="malcom@tlen.pl" name="MalCom"
subscription="none">
<group>Kontakty</group>
</item>
</query>
</iq>Opis nie jest wymagany, jedynie może zastanawiać występujący podwójnie tag <group></group>, prawdopodobnie jest błąd serwera tlenu, który do tej pory nie został usunięty. Bo jak dobrze pamiętam, w jabberze podwójny tag występował tylko przy aktualizacji.
2.7.3 Aktualizacja pozycji
Przy aktualizacji kontaktu używane są identyczne pakiety, co przy dodawaniu. Po prostu dane "pola" wypełniamy nowymi informacjami i wysyłamy do serwera:
<iq type="set">
<query xmlns="jabber:iq:roster">
<item jid="malcom@tlen.pl" subscription="both"
name="malcomus">
<group>Kontakty</group>
</item>
</query>
</iq>Atrybuty związane z subskrypcją można w zapytaniu pominąć. Tak samo pozycje, które nie chcemy aktualizować, zmieniać.
Reakcją serwera na wysłanie powyższego pakietu jest następującą odpowiedź:
<iq type="set">
<query xmlns="jabber:iq:roster">
<item jid="malcom@tlen.pl" subscription="both"
name="malcomus">
<group>Kontakty</group>
</item>
</query>
</iq>Należy zaznaczyć, że w przypadku, kiedy edytujemy kontakt, który nie znajduje się w naszym rosterze, to zostanie on normalnie dodany.
2.7.4 Usuwanie pozycji
Jeśli chcemy usunąć jakiś kontakt z naszego rostera, wysyłamy do serwera:
<iq type="set">
<query xmlns="jabber:iq:roster">
<item jid="malcom@tlen.pl" subscription="remove"/>
</query>
</iq>W jid podajemy identyfikator tlenowy użytkownika, którego chcemy usunąć z naszej książki kontaktowej. Jako subscription ustawiamy remove, co oznacza usunięcie.
W odpwiedzi otrzymamy potwierdzenie:
<iq type="set">
<query xmlns="jabber:iq:roster">
<item jid="malcom" subscription="remove"/>
</query>
</iq>Dziwne, że tutaj, w jid znajduje się sam login bez adresu serwera (@tlen.pl).